project-structure

用途

该技能用于指导 .NET 项目的组织与构建配置，帮助开发者按照现代最佳实践搭建和维护 .NET 解决方案。适用场景包括：新建 .NET 解决方案、跨多个项目配置集中式构建属性、实现中央包版本管理、为调试和 NuGet 包设置 SourceLink、通过发布说明自动化版本管理、固定 SDK 版本以保证构建一致性。

解决方案文件格式

.slnx（现代格式，.NET 9+）

基于 XML 的解决方案格式，可读性强且对 diff 友好，需要 .NET 9+ SDK 或 Visual Studio 17.13+。示例：

<Solution>
  <Folder Name="/build/">
    <File Path="Directory.Build.props" />
    <File Path="Directory.Packages.props" />
    <File Path="global.json" />
    <File Path="NuGet.Config" />
  </Folder>
  <Folder Name="/src/">
    <Project Path="src/MyApp.Core/MyApp.Core.csproj" />
    <Project Path="src/MyApp.Api/MyApp.Api.csproj" />
    <Project Path="src/MyApp.Infrastructure/MyApp.Infrastructure.csproj" />
  </Folder>
  <Folder Name="/tests/">
    <Project Path="tests/MyApp.UnitTests/MyApp.UnitTests.csproj" />
    <Project Path="tests/MyApp.IntegrationTests/MyApp.IntegrationTests.csproj" />
  </Folder>
</Solution>

从 .sln 迁移到 .slnx：

dotnet sln MySolution.sln migrate

注意：不要在同一仓库中同时保留 .sln 和 .slnx 文件。

创建新的 .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

优势：大幅减少合并冲突；人类可读可编辑；与现代 .csproj 格式一致；在拉取请求中提供更好的 diff/审查体验。

Directory.Build.props

应用于目录子树中所有项目的共享 MSBuild 属性。示例包含元数据（Authors、Company、Copyright、Product、PackageProjectUrl、RepositoryUrl、PackageLicenseExpression）、C# 语言设置（LangVersion、Nullable、ImplicitUsings、TreatWarningsAsErrors、EnforceCodeStyleInBuild、AnalysisLevel、NoWarn）、目标框架定义（NetStandardLibVersion、NetLibVersion、NetTestVersion）、SourceLink 配置、NuGet 包资产、全局 using 语句等。

嵌套的 Directory.Build.props：内部文件不会自动导入外部文件，需显式导入：

<!-- src/Directory.Build.props -->
<Project>
  <Import Project="$([MSBuild]::GetPathOfFileAbove('Directory.Build.props', '$(MSBuildThisFileDirectory)../'))" />
  <PropertyGroup>
    <!-- src 专属设置 -->
  </PropertyGroup>
</Project>

Directory.Build.targets

在项目评估之后导入，用于共享分析器包引用、自定义构建目标、基于项目类型的条件逻辑。

Directory.Packages.props - 中央包管理

CPM 将全部 NuGet 包版本集中在仓库根目录，各个 .csproj 文件引用包时无需 Version 属性。示例包含 ManagePackageVersionsCentrally、CentralPackageTransitivePinningEnabled 设置，以及按应用依赖、测试依赖、构建依赖分组的 PackageVersion 条目。

消费包时无需版本：

<!-- 在 MyApp.csproj 中 -->
<ItemGroup>
  <PackageReference Include="Akka" />
  <PackageReference Include="Microsoft.Extensions.Hosting" />
</ItemGroup>

版本覆盖：

<PackageReference Include="Newtonsoft.Json" VersionOverride="13.0.3" />

.editorconfig

置于仓库根目录以强制统一代码风格，示例包含缩进、行尾、字符集、C# 命名空间声明、大括号偏好、var 使用、可访问性修饰符、模式匹配、switch 表达式、using 指令位置、私有字段命名规则等配置。

global.json - SDK 版本固定

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

Roll Forward 策略包括 disable、patch、feature、latestFeature、minor、latestMinor、major。推荐使用 latestFeature，允许在同一功能带内进行补丁更新。

nuget.config

配置包源与安全，示例包含 disableSourceControlIntegration、packageSources（使用 <clear /> 加显式源）、packageSourceMapping。<clear /> + 显式源 + <packageSourceMapping> 模式可防止供应链攻击。私有源配置示例展示了为内部源指定 MyCompany.* 模式。

NuGet 审计：.NET 9+ 默认启用 NuGetAudit，可配置 NuGetAudit、NuGetAuditLevel、NuGetAuditMode。

锁文件：启用 RestorePackagesWithLockFile 以实现确定性还原，CI 中使用 dotnet restore --locked-mode。

SourceLink 与确定性构建

面向发布到 NuGet 的库，配置 PublishRepositoryUrl、EmbedUntrackSources、DebugType、ContinuousIntegrationBuild，并引用 Microsoft.SourceLink.GitHub。

使用 RELEASE_NOTES.md 进行版本管理

发布说明格式示例：

#### 1.2.0 January 15th 2025 ####

- Added new feature X
- Fixed bug in Y

#### 1.1.0 December 10th 2024 ####

- Initial release

CI/CD 集成示例：

- name: Update version from release notes
  shell: pwsh
  run: ./build.ps1

- name: Build
  run: dotnet build -c Release

- name: Pack with tag version
  run: dotnet pack -c Release /p:PackageVersion=${{ github.ref_name }}

快速参考

文件	用途
MySolution.slnx	现代 XML 解决方案文件
Directory.Build.props	集中式构建属性
Directory.Packages.props	中央包版本管理
global.json	SDK 版本固定
NuGet.Config	包源配置
RELEASE_NOTES.md	版本历史
.editorconfig	代码风格强制
.config/dotnet-tools.json	本地 .NET 工具

限制

资料未提供该技能的具体安装方式、收费模式、平台支持范围或效果保证等信息，暂未提供。

技能介绍

用途

推荐的解决方案布局