CMS后端【免费下载链接】Umbraco-CMSUmbraco is a free and open source .NET content management system helping you deliver delightful digital experiences.项目地址https://gitcode.com/gh_mirrors/um/Umbraco-CMS点击查看免费下载导读本文以 Umbraco-CMS 仓库中的src/Umbraco.Web.UI/CLAUDE.md为骨架剖析 Umbraco CMS 官方自带的 ASP.NET Core 开发测试站点它通过引用Umbraco.Cms元包与Umbraco.Cms.DevelopmentMode.Backoffice用一份仅 33 行的Program.cs启动起完整的 Backoffice 与前台网站并演示了典型 Composer、区块视图与配置模板的组织方式。读完本文你将掌握该项目的启动命令与调试 Profile、appsettings.template.json与开发环境覆盖的每个关键配置项、ModelsBuilderInMemoryAuto模式的运行机制与底层热更新链路以及 app-local ICU 全局化的启用与关闭方法可直接将这些模式复用到自己的 Umbraco 站点开发中。1. 项目定位一个最小但完整的可运行 Umbraco 实例src/Umbraco.Web.UI是仓库中唯一可直接运行的 ASP.NET Core Web 应用程序其作用不是对外发布产品而是为开发与测试提供一个参考实现。文档src/Umbraco.Web.UI/CLAUDE.md明确了它的四个核心职责引用全部 Umbraco 包通过Umbraco.Cms元包聚合所有子项目见 src/Umbraco.Cms/Umbraco.Cms.csproj它串联了 Targets、Imaging.ImageSharp、Persistence.Sqlite/SqlServer、Persistence.EFCore.Sqlite/SqlServer 等提供最小启动代码Program.cs采用 builder 模式仅数十行即可完成 Umbraco 启动包含开发工具引用Umbraco.Cms.DevelopmentMode.Backoffice支持 Backoffice 的模型热重载演示模式内置示例 Composer、Razor 视图与 Block Grid / Block List 模板。项目的工程属性如下属性值说明项目类型ASP.NET Core Web ApplicationMicrosoft.NET.Sdk.Web目标框架net10.0与仓库全局目标一致可打包性IsPackablefalse不作为 NuGet 包发布根命名空间Umbraco.Cms.Web.UI—提示这个项目仅面向开发切勿将其当作生产站点模板生产模板请参考 templates/UmbracoProject 目录。目录结构速览文档给出了完整的目录树已核对真实仓库结构一致Umbraco.Web.UI/ ├── Composers/ │ ├── ControllersAsServicesComposer.cs # DI 验证 composer66 行 │ └── UmbracoAppAuthenticatorComposer.cs # 2FA 示例被注释 ├── Properties/ │ └── launchSettings.json # 调试 Profile29 行 ├── Views/ │ ├── _ViewImports.cshtml # 全局视图导入 │ ├── page.cshtml / BlockPage.cshtml / BlockTester.cshtml # 页面模板 │ └── Partials/ │ ├── blockgrid/ # Block Grid 分部视图 │ ├── blocklist/ # Block List 分部视图 │ └── singleblock/ # Single Block 分部视图 ├── wwwroot/favicon.ico ├── umbraco/ # 运行时数据目录Git 忽略 │ ├── Data/ # SQLite 数据库、TEMP │ ├── Logs/ # Serilog JSON 日志 │ └── models/ # 生成的内容模型 ├── appsettings.json # 生产配置首次构建自动复制 ├── appsettings.Development.json # 开发覆盖首次构建自动复制 ├── appsettings.template.json # 新安装默认配置 ├── appsettings.Development.template.json # 开发模板 ├── Program.cs # 应用入口33 行 └── Umbraco.Web.UI.csproj # 项目文件75 行其中Views/Partials/blockgrid/下的area.cshtml、areas.cshtml、default.cshtml、items.cshtml与blocklist/default.cshtml是 Block Grid / Block List 渲染的标准参考实现例如blockgrid/default.cshtml通过Html.GetBlockGridItemsHtmlAsync(Model)输出网格areas.cshtml则遍历Model.Areas逐区域渲染——这些可直接作为自定义 Block 渲染的起点。2. 启动方式与调试 Profile命令行运行文档推荐的启动方式如下命令在仓库根目录执行# 用 Kestrel 运行推荐 dotnet run --project src/Umbraco.Web.UI # 带自动重载的 watch 模式 dotnet watch --project src/Umbraco.Web.UIdotnet watch对前后端修改均生效结合下方DevelopmentMode.Backoffice引用内容类型变更也能触发模型热更新无需手动重启。调试 ProfilelaunchSettings.jsonlaunchSettings.json 定义了两个 ProfileProfileURLCommandUmbraco.Web.UIhttps://localhost:44339, http://localhost:11000ProjectKestrelIIS Expresshttp://localhost:11000, SSL 端口 44339IISExpress两个 Profile 都会设置ASPNETCORE_ENVIRONMENTDevelopment并自动打开浏览器。首次运行时访问根路径会进入安装向导/install完成安装后即可访问 Backoffice/umbraco。数据库开发环境默认使用 SQLite数据库文件生成在src/Umbraco.Web.UI/umbraco/Data/Umbraco.sqlite.db连接字符串在appsettings.json的ConnectionStrings:umbracoDbDSN中配置模板中留空表示走默认 SQLite 安装流程。3. Program.cs33 行的最小 Umbraco 启动骨架Program.cs 是理解 Umbraco 启动流程的最佳入口完整代码如下WebApplicationBuilder builder WebApplication.CreateBuilder(args); //-:cnd:noEmit #if DEBUG builder.Configuration.AddJsonFile(appsettings.Local.json, optional: true, reloadOnChange: true); #endif //:cnd:noEmit builder.CreateUmbracoBuilder() .AddBackOffice() .AddWebsite() #if UseDeliveryApi .AddDeliveryApi() #endif .AddComposers() .Build(); WebApplication app builder.Build(); #if UseDocumentedCsp app.UseDocumentedContentSecurityPolicy(); #endif await app.BootUmbracoAsync(); #if UseHttpsRedirect app.UseHttpsRedirection(); #endif app.UseUmbraco() .WithMiddleware(u { u.UseBackOffice(); u.UseWebsite(); }) .WithEndpoints(u { u.UseBackOfficeEndpoints(); u.UseWebsiteEndpoints(); }); await app.RunAsync();关键点逐行拆解AddJsonFile(appsettings.Local.json, optional: true)仅 DEBUG 构建时加载本地个性化配置如本机 SMTP文件不存在也不报错CreateUmbracoBuilder()创建 Umbraco builder 并聚合所有注册项.AddBackOffice()/.AddWebsite()分别启用管理后台与前台网站Razor 渲染、路由、Surface Controller 等.AddDeliveryApi()由#if UseDeliveryApi编译符号控制开关即文档所述的预处理器指令之一.AddComposers()扫描并执行所有IComposer本项目的ControllersAsServicesComposer即在此阶段生效BootUmbracoAsync()执行运行时启动安装检测、数据库迁移、模型生成等UseUmbraco().WithMiddleware(...).WithEndpoints(...)注册中间件管道与端点Backoffice 与 Website 两组。预处理器指令编译符号符号作用UseDeliveryApi启用/禁用 Delivery APIUseHttpsRedirect启用/禁用 HTTPS 重定向UseHttpsRedirection()UseDocumentedCsp启用文档化的 Content-Security-Policy 中间件本仓库在 csproj 中默认定义UseDocumentedCsp对应 Extensions/WebApplicationExtensions.cs 中UseDocumentedContentSecurityPolicy()的实现它借助ICspNonceService为 Backoffice 脚本注入 nonce并按官方健康检查文档中的 CSP 规则为开发站点提前暴露任何冲突。4. 关键组件Composer 与 DI 校验ControllersAsServicesComposer控制器容器校验Composers/ControllersAsServicesComposer.cs 的核心仅一行public void Compose(IUmbracoBuilder builder) builder.Services .AddMvc() .AddControllersAsServicesWithoutChangingActivator();文档指出其目的是在 CMS 控制器中检测会导致ServiceBasedControllerActivator出问题的歧义构造函数。仓库注释进一步说明了背景Umbraco 9 起默认使用DefaultControllerActivator不直接从 IoC 容器解析控制器实例而是解析依赖后自行构造部分用户希望切换到ServiceBasedControllerActivator便于拦截/装饰本项目通过将所有控制器注册进 DI 来提前暴露歧义构造函数问题。实现细节同文件内的MvcBuilderExtensions值得一提用ControllerFeature枚举全部控制器逐个TryAddTransient若 Backoffice 未启用通过IBackOfficeEnabledMarker判断则跳过Umbraco.Cms.Api.Management程序集下的 Management API 控制器为RenderNoContentController显式注册构造函数所需依赖IHostingEnvironment、IOptionsSnapshotGlobalSettings、IDocumentUrlService。注意该 Composer不会随Umbraco.Templates模板包分发仅存在于本开发站点中。UmbracoAppAuthenticatorComposer2FA 示例注释态Composers/UmbracoAppAuthenticatorComposer.cs 整体被注释演示了为 Member 添加 Google 2FA Provider 的标准写法var identityBuilder new MemberIdentityBuilder(builder.Services); identityBuilder.AddTwoFactorProviderUmbracoAppAuthenticator(UmbracoAppAuthenticator.Name);如需启用双因子认证取消注释并补齐UmbracoAppAuthenticator实现即可。5. 配置模板详解5.1 appsettings.template.json新安装默认配置appsettings.template.json 是新装站点的基线配置文档提取的关键项如下配置路径值说明Umbraco.CMS.ModelsBuilder.ModelsModeInMemoryAuto内存中自动生成强类型模型Umbraco.CMS.Global.DefaultUILanguageen-usBackoffice 默认界面语言Umbraco.CMS.Global.HideTopLevelNodeFromPathtrue顶级节点不进入 URL 路径更干净的 URLUmbraco.CMS.Global.TimeOut00:20:00用户会话超时Umbraco.CMS.Global.UseHttpsfalse是否强制 HTTPSUmbraco.CMS.Security.UsernameIsEmailtrue使用邮箱作为用户名Umbraco.CMS.Security.UserPassword.RequiredLength10用户密码最小长度对照仓库实际 JSON完整结构还包括ConnectionStrings:umbracoDbDSN留空走安装向导、Serilog 日志级别默认 InformationMicrosoft/System 降为 WarningMicrosoft.Hosting.Lifetime保持 Information、Hosting.Debugfalse、RequestHandler.ConvertUrlsToAsciitry以及 Security 节点下更细的密码策略UserPasswordRequireNonLetterOrDigit、RequireDigit、RequireLowercase、RequireUppercase均为falseMaxFailedAccessAttemptsBeforeLockout5MemberPassword与用户密码同构的成员密码策略AllowedUserNameCharacters定义了合法的用户名字符集。这些值均可按需在站点的appsettings.json中覆盖。5.2 appsettings.Development.template.json开发覆盖appsettings.Development.template.json 提供仅开发环境生效的覆盖配置项值说明Umbraco.CMS.Hosting.Debugtrue开启调试模式Umbraco.CMS.Examine.LuceneDirectoryFactoryTempFileSystemDirectoryFactoryExamine 索引放入临时文件系统避免污染仓库Serilog 控制台输出Asyncsink 包裹Console异步写入控制台降低日志阻塞Examine 相关日志级别Debug对Examine.Lucene.Providers.LuceneIndex、Examine.BaseIndexProvider、Examine.Lucene.LoggingReplicationClient、Examine.Lucene.ExamineReplicator四个来源开启 Debug 级别便于索引调试此外还预留了注释态的 SMTP 配置Global:Smtp供本地邮件联调。5.3 自动复制模板的 MSBuild TargetUmbraco.Web.UI.csproj 中定义了两个BeforeTargetsBuild的 Target当appsettings.json或appsettings.Development.json不存在时自动从对应 template 文件复制生成并输出 high 级别构建消息。因此删掉这两个文件即可重置为全新安装状态配合清理umbraco/Data目录。6. ModelsBuilder InMemoryAuto 模式与热更新原理6.1 工作目录与产物本项目采用InMemoryAuto模式见appsettings.template.json模型在运行时自动生成umbraco/models/*.generated.cs # 生成源码供参考 umbraco/Data/TEMP/InMemoryAuto/ # 运行时编译产物文档列出的关键中间产物包括models.hash记录内容类型定义哈希用于判断是否需要重建、生成的.cs源文件以及编译后的程序集。6.2 底层实现Umbraco.Cms.DevelopmentMode.Backoffice热更新能力来自项目引用的 src/Umbraco.Cms.DevelopmentMode.Backoffice其 CLAUDE.md 给出了完整设计。核心技术组合为RoslynMicrosoft.CodeAnalysis.CSharp运行时将生成代码编译为 DLLCollectible AssemblyLoadContext模型与编译后的 Razor 视图装入可卸载的程序集上下文实现不重启应用的热替换Runtime Razor 视图编译克隆 ASP.NET Core 内部RuntimeViewCompiler等类Clone-and-Own 模式原因是 .NET 7 起默认AssemblyLoadContext无法引用 collectible 上下文官方内部 API 又不开放扩展。内容类型变更后的完整重建链路摘自 DevelopmentMode.Backoffice 文档内容类型变更 → Reset() 置 _pendingRebuild true ↓ 下一次视图请求 → EnsureModels() → GetModelsAssembly(forceRebuild: true) ↓ GenerateModelsCode() → RoslynCompiler.CompileToFile() ↓ ReloadAssembly() → InMemoryAssemblyLoadContextManager.RenewAssemblyLoadContext()卸载旧上下文、创建新 collectible 上下文 ↓ RuntimeCompilationCacheBuster.BustCache() → 视图使用新模型重新编译启动时则通过models.hash与当前内容类型哈希比对一致则直接加载磁盘上缓存的 DLLCompiled/generated.cs{hash}.dll以加速启动不一致或缺失才重新编译。6.3 前提条件与安全注意启用该模式要求如文档 §6 及 DevelopmentMode.Backoffice 的InMemoryModelsBuilderModeValidator所述{ Umbraco: { CMS: { Runtime: { Mode: BackofficeDevelopment }, ModelsBuilder: { ModelsMode: InMemoryAuto } } } }即RuntimeMode必须是BackofficeDevelopment否则校验器会阻止InMemoryAuto模式同时由于编译产物位于~/umbraco/Data/TEMP/InMemoryAuto/应确保该目录不对 Web 暴露。6.4 Razor 编译设置因为使用 InMemoryAuto模型在运行时以内存程序集形式存在csproj 中关闭了构建/发布时的 Razor 预编译RazorCompileOnBuildfalse/RazorCompileOnBuild RazorCompileOnPublishfalse/RazorCompileOnPublish文档明确提示切换为非 InMemoryAuto 模式时需移除这两项否则 Razor 视图无法正常预编译。同时CopyRazorGenerateFilesToPublishDirectorytrue/CopyRazorGenerateFilesToPublishDirectory确保发布目录包含 Backoffice 运行所需的 Razor 文件。7. App-Local ICU 全球化跨平台一致性7.1 为什么需要Umbraco.Web.UI.csproj 通过引入Microsoft.ICU.ICU4C.Runtimev72.1.0.3启用 app-local ICU使全球化行为在 Windows / Linux 上保持一致——尤其是 Windows Server 2016 与 Windows 10 1703–1809 这些会回退到 NLS 的旧平台可避免CultureInfo行为差异。7.2 启用条件与覆盖路径开关属性为UmbracoUseAppLocalIcu默认逻辑与原先RuntimeIdentifier感知条件一致非 macOS 的 Linux/Windows 构建默认启用truemacOS 下默认关闭false。csproj 中对应的条件判断与版本属性为UmbracoUseAppLocalIcu Condition$(UmbracoUseAppLocalIcu) and ($(RuntimeIdentifier.StartsWith(linux)) or $(RuntimeIdentifier.StartsWith(win)) or ($(RuntimeIdentifier) and !$([MSBuild]::IsOSPlatform(osx))))true/UmbracoUseAppLocalIcu UmbracoUseAppLocalIcu Condition$(UmbracoUseAppLocalIcu) false/UmbracoUseAppLocalIcu UmbracoAppLocalIcuVersion Condition$(UmbracoAppLocalIcuVersion) 72.1.0.3/UmbracoAppLocalIcuVersion两种覆盖方式文档 §6 强调的关键路径时机做法构建/发布时dotnet publish -p:UmbracoUseAppLocalIcufalse或在.csproj/Directory.Build.props中显式设置该属性发布后不重新构建编辑发布的*.runtimeconfig.json删除或修改runtimeOptions.configProperties下的System.Globalization.AppLocalIcu7.3 关于 DOTNET_SYSTEM_GLOBALIZATION_APPLOCALICU 的误区文档特别提醒并在 csproj 注释中标注已在 .NET 10 上实证该环境变量不能覆盖 runtimeconfig.json 中已有的 AppLocalIcu 条目。因为 AppLocalIcu 由原生宿主在 CLR 启动前读取.NET 9 的环境变量优先于 runtimeconfig通用规则在此不适用——只有当 runtimeconfig 中完全没有 AppLocalIcu 条目时即用上述两种方式之一移除后才构建/修改环境变量才会被采纳。因此请优先使用 7.2 中的两条路径。7.4 同步维护要求保持UmbracoAppLocalIcuVersion与Microsoft.ICU.ICU4C.Runtime包版本一致任何改动需同步到 templates/UmbracoProject/UmbracoProject.csproj 的 CPM 与非 CPM 两个分支。8. 项目专属配置与工程细节8.1 不采用中央包管理csproj 显式设置ManagePackageVersionsCentrallyfalse/ManagePackageVersionsCentrally版本直接写在 PackageReference 中原因包括Microsoft.EntityFrameworkCore.Designv10.0.12PrivateAssetsall为 EF Core 迁移工具链提供设计期支持Microsoft.CodeAnalysis.CSharp.Workspaces/Microsoft.CodeAnalysis.Workspaces.MSBuildv5.9.0对齐 EFCore.Design 带入的 Roslyn 传递版本冲突NU1107 / NU1608Microsoft.OpenApiv2.12.2与SQLitePCLRaw.lib.e_sqlite3v2.1.13绕过传递版本漏洞CVE-2026-49451 / GHSA-2m69-gcr7-jv3q与根目录 Directory.Packages.props 的集中固定版本保持一致Microsoft.ICU.ICU4C.Runtime全球化受UmbracoUseAppLocalIcu门控见 §7。8.2 导入 Targets 与排除视图通过Import引入 Umbraco.Cms.Targets 的 props/targets共享构建配置从内容中排除三个来自Umbraco.Cms.StaticAssetsRCL 的视图umbraco/UmbracoInstall/Index.cshtml、umbraco/UmbracoLogin/Index.cshtml、umbraco/UmbracoBackOffice/Default.cshtmlcsproj 中_ContentIncludedByDefault Remove三项隐藏Microsoft.CodeAnalysis.Workspaces.MSBuild包带入的内容文件Visiblefalse。8.3 已知技术债SA1119多余括号被加入WarningsNotAsErrors豁免csproj 中标注TODO: Fix and remove overrides。8.4 运行时数据目录Git 忽略目录内容Git 状态umbraco/Data/SQLite 数据库、MainDom 锁忽略umbraco/Logs/Serilog JSON 追踪日志忽略umbraco/models/生成的内容模型忽略umbraco/Data/TEMP/ModelsBuilder、DistCache忽略9. 快速参考常用命令# 运行开发站点 dotnet run --project src/Umbraco.Web.UI # 清理运行时数据重置数据库 rm -rf src/Umbraco.Web.UI/umbraco/Data # 重置为全新安装恢复初始模板 rm src/Umbraco.Web.UI/appsettings.json rm src/Umbraco.Web.UI/appsettings.Development.json执行rm会触发 csproj 中的自动复制 Target从 template 重新生成两个配置文件。关键文件文件用途Program.cs应用入口点appsettings.template.json默认配置appsettings.Development.template.json开发环境覆盖launchSettings.json调试 ProfileControllersAsServicesComposer.csDI 校验Umbraco.Web.UI.csproj项目文件与构建细节访问地址环境URL开发KestrelHTTPShttps://localhost:44339开发HTTPhttp://localhost:11000Backoffice/umbraco安装向导/install首次运行关联项目一览项目关系Umbraco.Cms元包聚合全部依赖Umbraco.Cms.DevelopmentMode.Backoffice模型热重载支持Umbraco.Cms.StaticAssetsBackoffice/登录视图 RCLUmbraco.Cms.Targets共享构建配置Umbraco.Web.CommonWeb 基础设施总结src/Umbraco.Web.UI是 Umbraco 开发者最值得通读的最小可运行范例从Program.cs的 builder 启动链路、appsettings.template.json的完整配置基线到ControllersAsServicesComposer的 DI 校验技巧、InMemoryAuto 模型热更新的 Clone-and-Own 实现与 app-local ICU 的跨平台全球化取舍它覆盖了日常开发与排障所需的大部分知识点。如需深入底层实现可继续研读 src/Umbraco.Cms.DevelopmentMode.Backoffice/CLAUDE.md 中的设计概览DependencyInjection/UmbracoBuilderExtensions.cs的 80 行设计注释与仓库根目录 CLAUDE.md。赞分享CMS后端【免费下载链接】Umbraco-CMSUmbraco is a free and open source .NET content management system helping you deliver delightful digital experiences.项目地址https://gitcode.com/gh_mirrors/um/Umbraco-CMS点击查看免费下载相关推荐为什么选择jeffding/bert-base-uncased-openmind110M参数BERT模型的7大核心优势解析为什么选择jeffding/bert base uncased openmind110M参数BERT模型的7大核心优势解析 在自然语言处理领域选择合适的预训Calico confd 模板资源Template Resource配置详解用 TOML 声明式驱动配置生成与热更新Calico confd 模板资源Template Resource配置详解用 TOML 声明式驱动配置生成与热更新 本文以 Calico 仓库内置的 c网络云原生网络安全RuboCop配置模板快速启动新项目的最佳配置RuboCop配置模板快速启动新项目的最佳配置 为什么需要统一的RuboCop配置 在Ruby项目开发中团队协作时的代码风格不一致往往导致以下问题 代码代码质量Lint格式化静态分析开发工具上一篇Metapi 仪表盘完全指南余额分布、消费趋势、模型用量一图掌握下一篇拆解thinking-orbs源码架构React层、烘焙预设系统与纯几何引擎如何协作附架构表格创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
 Promise到事件驱动UI的核心控制)
