SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场dotnet-project-structure

dotnet-project-structure

编程与开发

查看项目

更新于 10-15 10:24

技能介绍

用途

该技能用于搭建和维护现代 .NET 解决方案的项目结构与构建配置，覆盖从解决方案文件格式、集中构建属性、包版本管理到版本发布与持续集成的完整流程。适用于以下场景：搭建采用现代最佳实践的新 .NET 解决方案；为多项目配置集中化构建属性；实现中央包版本管理；为调试和 NuGet 包配置 SourceLink；结合发布说明自动化版本管理；固定 SDK 版本以获得一致的构建结果。

主要能力

解决方案文件格式（.slnx）

.slnx 是 .NET 9 引入的基于 XML 的现代解决方案文件格式，用于替代传统的 .sln 格式。相比传统格式，其格式为标准 XML，可读性更好（无 GUID 与晦涩语法），更易于版本控制中的 diff/merge，并可用任意文本编辑器编辑，而不必依赖 IDE。

版本要求：.NET SDK 最低 9.0.200，Visual Studio 最低 17.13，MSBuild 为 Visual Studio Build Tools 17.13。资料指出，从 .NET 10 开始，dotnet new sln 默认生成 .slnx 文件；在 .NET 9 中需要显式迁移或指定格式。

从 .sln 迁移可使用命令：

dotnet sln MySolution.sln migrate

或目录中仅有一个 .sln 时：

dotnet sln migrate

也可在 Visual Studio 中打开解决方案，在解决方案资源管理器中选中解决方案，依次选择 File > Save Solution As...，将“Save as type”改为 Xml Solution File (*.slnx)。

重要提醒：不要在同一仓库中同时保留 .sln 和 .slnx 文件，否则会影响自动解决方案检测并可能导致同步问题；迁移后应删除旧的 .sln 文件。

创建新 .slnx 解决方案：

# .NET 10+：默认创建 .slnx
dotnet new sln --name MySolution

# .NET 9：显式指定格式
dotnet new sln --name MySolution --format slnx

# 添加项目（两种格式通用）
dotnet sln add src/MyApp/MyApp.csproj

Directory.Build.props

Directory.Build.props 提供集中式构建配置，作用于目录树中的所有项目，通常放在解决方案根目录。资料给出的完整示例包含：元数据（Authors、Company、动态版权年份、Product、PackageProjectUrl、RepositoryUrl、PackageLicenseExpression、PackageTags）；C# 语言设置（LangVersion、Nullable、ImplicitUsings、TreatWarningsAsErrors、NoWarn）；版本管理（VersionPrefix、PackageReleaseNotes）；可复用的目标框架属性（NetStandardLibVersion、NetLibVersion、NetTestVersion）；SourceLink 配置（PublishRepositoryUrl、EmbedUntrackedSources、IncludeSymbols、SymbolPackageFormat）；NuGet 包资产（logo.png、README.md）；以及全局 using 语句。

关键模式：

  • 动态版权年份：使用 MSBuild 属性函数在构建时插入当前年份，无需手动更新，例如 <Copyright>Copyright © 2020-$([System.DateTime]::Now.Year) Your Company</Copyright>。
  • 可复用目标框架属性：在 Directory.Build.props 中一次定义 NetLibVersion、NetTestVersion，各项目通过 $(NetLibVersion)、$(NetTestVersion) 引用。
  • SourceLink：启用对 NuGet 包的逐行调试，并可根据源代码管理选择提供程序，如 Microsoft.SourceLink.GitHub，也可用 Microsoft.SourceLink.AzureRepos.Git、Microsoft.SourceLink.GitLab、Microsoft.SourceLink.Bitbucket.Git。

Directory.Packages.props（中央包管理）

中央包管理（CPM）为所有 NuGet 包版本提供单一事实来源。设置方式为在 Directory.Packages.props 中启用 <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>，并通过 <PackageVersion> 项集中声明版本。资料示例还展示了为相关包定义版本变量（如 AkkaVersion、AspireVersion），并按“应用依赖”“构建依赖”“测试依赖”分组。

使用包时，各项目只需写 <PackageReference Include="Akka" />，无需再填写版本号。其优势包括：单一事实来源、避免版本漂移、更新一次即全局生效、可对相关包进行分组管理。

global.json（SDK 版本固定）

通过 global.json 固定 .NET SDK 版本以获得跨环境一致的构建，示例：

{
  "sdk": {
    "version": "9.0.200",
    "rollForward": "latestFeature"
  }
}

Roll Forward 策略包括 disable（要求精确版本）、patch（相同 major.minor，取最新 patch）、feature（相同 major，取最新 minor.patch）、latestFeature（相同 major，取最新 feature band）、minor、latestMinor、major（最新 SDK，不推荐）。资料推荐使用 latestFeature，允许在同一 feature band 内进行 patch 更新。

基于 RELEASE_NOTES.md 的版本管理

发布说明格式以 #### 版本号 日期 #### 作为分段标题，后接变更列表。资料提供了 PowerShell 脚本：getReleaseNotes.ps1 用于解析 RELEASE_NOTES.md，提取 Version、Date、ReleaseNotes；bumpVersion.ps1 中的 UpdateVersionAndReleaseNotes 函数将解析结果写回到 XML 文件（如 Directory.Build.props）中的 VersionPrefix 与 PackageReleaseNotes 节点；build.ps1 组合调用上述脚本完成版本更新。

CI/CD 集成示例（GitHub Actions）包括：使用 pwsh 运行 ./build.ps1 更新版本；dotnet build -c Release 构建；dotnet pack -c Release /p:PackageVersion=${{ github.ref_name }} 按标签版本打包；以及使用 API Key 推送至 NuGet 源。

NuGet.Config

用于配置 NuGet 源与行为。示例中通过 <clear /> 移除继承/默认源以保证构建可复现，并设置 disableSourceControlIntegration 为 true 以避免 TFS/Git 集成问题，同时可添加私有源。

使用方式

按资料结构组织解决方案：根目录放置 Directory.Build.props、Directory.Packages.props、.slnx 解决方案文件、global.json、NuGet.Config、build.ps1、RELEASE_NOTES.md、README.md、logo.png；src 与 tests 目录分别存放应用与测试项目；scripts 目录存放解析与版本递增脚本；.config 目录存放 dotnet-tools.json；.github/workflows 存放 PR 校验与发布工作流。

适用范围与限制

.slnx 需要 .NET SDK 9.0.200 及以上、Visual Studio 17.13 及以上或对应版本的 MSBuild 构建工具；.NET 10 起才默认使用该格式，.NET 9 需显式指定或迁移。迁移时不可同时保留 .sln 与 .slnx。资料中未提供具体的收费、价格信息，也未提供除上述场景外的平台与效果说明。