dotnet-scaffold-project

dotnet-scaffold-project

使用已应用所有现代最佳实践的配置搭建新的 .NET 项目。生成完整的解决方案结构，包括 Central Package Management、分析器、.editorconfig、SourceLink 和确定性生成。

前提条件： 先运行 [skill:dotnet-version-detection]，确定可用的 SDK 版本——这会影响可用的功能和模板。

交叉引用：[skill:dotnet-project-structure] 介绍布局设计依据，[skill:dotnet-add-analyzers] 介绍分析器配置，[skill:dotnet-add-ci] 介绍搭建后如何添加 CI。

---

步骤 1：创建解决方案结构

创建目录布局和解决方案文件。

# Create the directory structure
mkdir -p MyApp/src MyApp/tests

# Create solution file
cd MyApp
dotnet new sln -n MyApp

# For .NET 9+ SDK, convert to .slnx
dotnet sln MyApp.sln migrate

选择项目模板

根据应用类型选择合适的模板：

模板	命令	SDK
Web API（最简）	dotnet new webapi -n MyApp.Api -o src/MyApp.Api	Microsoft.NET.Sdk.Web
Web API（控制器）	dotnet new webapi -n MyApp.Api -o src/MyApp.Api --use-controllers	Microsoft.NET.Sdk.Web
控制台应用	dotnet new console -n MyApp.Cli -o src/MyApp.Cli	Microsoft.NET.Sdk
Worker 服务	dotnet new worker -n MyApp.Worker -o src/MyApp.Worker	Microsoft.NET.Sdk.Worker
类库	dotnet new classlib -n MyApp.Core -o src/MyApp.Core	Microsoft.NET.Sdk
Blazor Web 应用	dotnet new blazor -n MyApp.Web -o src/MyApp.Web	Microsoft.NET.Sdk.Web
MAUI 应用	dotnet new maui -n MyApp.Mobile -o src/MyApp.Mobile	Microsoft.Maui.Sdk
xUnit 测试	dotnet new xunit -n MyApp.Tests -o tests/MyApp.Tests	Microsoft.NET.Sdk

# Example: Web API with class library and tests
dotnet new classlib -n MyApp.Core -o src/MyApp.Core
dotnet new webapi -n MyApp.Api -o src/MyApp.Api
dotnet new xunit -n MyApp.UnitTests -o tests/MyApp.UnitTests

# Add projects to solution
dotnet sln add src/MyApp.Core/MyApp.Core.csproj
dotnet sln add src/MyApp.Api/MyApp.Api.csproj
dotnet sln add tests/MyApp.UnitTests/MyApp.UnitTests.csproj

# Add project references
dotnet add src/MyApp.Api/MyApp.Api.csproj reference src/MyApp.Core/MyApp.Core.csproj
dotnet add tests/MyApp.UnitTests/MyApp.UnitTests.csproj reference src/MyApp.Core/MyApp.Core.csproj

---

步骤 2：添加 global.json

固定 SDK 版本，确保生成可重现。

{
  "sdk": {
    "version": "10.0.100",
    "rollForward": "latestPatch"
  }
}

调整版本，使其与 dotnet --version 的输出一致。

---

步骤 3：添加 Directory.Build.props

在仓库根目录创建此文件，以便在所有项目间共享生成设置。

<Project>
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <LangVersion>14</LangVersion>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
    <EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>
    <AnalysisLevel>latest-all</AnalysisLevel>
  </PropertyGroup>

  
  <PropertyGroup>
    <PublishRepositoryUrl>true</PublishRepositoryUrl>
    <EmbedUntrackedSources>true</EmbedUntrackedSources>
    <DebugType>embedded</DebugType>
    <ContinuousIntegrationBuild Condition="'$(CI)' == 'true'">true</ContinuousIntegrationBuild>
  </PropertyGroup>

  
  <PropertyGroup>
    <NuGetAudit>true</NuGetAudit>
    <NuGetAuditLevel>low</NuGetAuditLevel>
    <NuGetAuditMode>all</NuGetAuditMode>
    <RestorePackagesWithLockFile>true</RestorePackagesWithLockFile>
  </PropertyGroup>
</Project>

创建后，请从各个 .csproj 文件中移除 <TargetFramework>、<Nullable> 和 <ImplicitUsings>，避免重复配置。

可选：单独的测试 props 文件

<Project>
  <Import Project="$([MSBuild]::GetPathOfFileAbove('Directory.Build.props', '$(MSBuildThisFileDirectory)../'))" />
  <PropertyGroup>
    <IsPackable>false</IsPackable>
    <IsTestProject>true</IsTestProject>
    
    <UseMicrosoftTestingPlatformRunner>true</UseMicrosoftTestingPlatformRunner>
    
    <TreatWarningsAsErrors>false</TreatWarningsAsErrors>
  </PropertyGroup>
</Project>

---

步骤 4：添加 Directory.Build.targets

将共享的包引用（SourceLink、分析器）应用于所有项目。项目项应放在 .targets 中，这样它们会在项目评估后导入。

<Project>
  <ItemGroup>
    
    <PackageReference Include="Microsoft.SourceLink.GitHub" PrivateAssets="all" />
  </ItemGroup>
</Project>

Directory.Build.props（步骤 3）中的 AnalysisLevel 和 EnforceCodeStyleInBuild 属性已启用内置 Roslyn 分析器。如需使用其他第三方分析器，请参阅 [skill:dotnet-add-analyzers]。

---

步骤 5：设置 Central Package Management

在仓库根目录创建 Directory.Packages.props。

<Project>
  <PropertyGroup>
    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
    <CentralPackageTransitivePinningEnabled>true</CentralPackageTransitivePinningEnabled>
  </PropertyGroup>
  <ItemGroup>
    
    <PackageVersion Include="Microsoft.SourceLink.GitHub" Version="9.0.0" />
  </ItemGroup>
  <ItemGroup>
    
    <PackageVersion Include="Microsoft.NET.Test.Sdk" Version="18.0.1" />
    <PackageVersion Include="xunit.v3" Version="3.2.2" />
    <PackageVersion Include="xunit.runner.visualstudio" Version="3.1.5" />
    <PackageVersion Include="coverlet.collector" Version="8.0.0" />
  </ItemGroup>
</Project>

创建后，请从 .csproj 文件中所有 <PackageReference> 元素移除 Version 属性。

---

步骤 6：添加 .editorconfig

在仓库根目录创建此文件。完整的推荐配置请参阅 [skill:dotnet-project-structure]。

最简入门配置：

root = true

[*]
indent_style = space
indent_size = 4
end_of_line = lf
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = true

[*.{csproj,props,targets,xml,json,yml,yaml}]
indent_size = 2

[*.cs]
csharp_style_namespace_declarations = file_scoped:warning
csharp_prefer_braces = true:warning
dotnet_style_require_accessibility_modifiers = always:warning
dotnet_sort_system_directives_first = true
csharp_using_directive_placement = outside_namespace:warning

---

步骤 7：添加 nuget.config

配置包源以保障供应链安全：

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <clear />
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
  </packageSources>
  <packageSourceMapping>
    <packageSource key="nuget.org">
      <package pattern="*" />
    </packageSource>
  </packageSourceMapping>
</configuration>

---

步骤 8：添加 .gitignore

dotnet new gitignore

此命令会生成标准的 .NET .gitignore，其中包含 bin/、obj/、*.user 等。

---

步骤 9：清理生成的项目

搭建完成后，应用共享配置：

1. 移除各个 .csproj 文件中重复的属性（TargetFramework、Nullable、ImplicitUsings——这些属性已在 Directory.Build.props 中定义）
2. 移除 PackageReference 元素中的 Version 属性（由 CPM 管理）
3. 删除类库中由模板生成的 Class1.cs
4. 在所有生成的 .cs 文件中设置文件范围命名空间

清理后的 csproj 示例

清理前（由模板生成）：

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>
</Project>

清理后（使用共享 props 和 CPM）：

<Project Sdk="Microsoft.NET.Sdk">
</Project>

对于需要使用 Microsoft.NET.Sdk.Web 的 Web 项目，csproj 仍需指定 SDK，但其他设置都会继承。

---

步骤 10：验证

运行以下命令，验证搭建好的项目：

# Restore and verify lock files generated
dotnet restore
find . -name "packages.lock.json" -type f

# Build with all analyzers
dotnet build --no-restore

# Run tests
dotnet test --no-build

# Verify CPM is active (no Version attributes in project PackageReferences)
# Should only find versions in Directory.Packages.props, not in csproj files
find . -name "*.csproj" -exec grep -l 'Version=' {} \;  # expect no output

---

最终结构

MyApp/
├── .editorconfig
├── .gitignore
├── global.json
├── nuget.config
├── MyApp.slnx
├── Directory.Build.props
├── Directory.Build.targets
├── Directory.Packages.props
├── src/
│   ├── MyApp.Core/
│   │   └── MyApp.Core.csproj
│   └── MyApp.Api/
│       ├── MyApp.Api.csproj
│       ├── Program.cs
│       └── appsettings.json
└── tests/
    └── MyApp.UnitTests/
        ├── MyApp.UnitTests.csproj
        └── SampleTest.cs

---

参考资料

• .NET 库设计指南
• 中央包管理
• SourceLink
• NuGet 审核
• dotnet new 模板