Skip to content

NetFabric/NetFabric.Numerics / .agents/skills/dotnet-solution-setup

dotnet-solution-setup

Verified

Repository and solution-level scaffolding best practices for .NET: .slnx solution format, Directory.Build.props shared MSBuild properties, Directory.Packages.props central package management (CPM), .editorconfig, SourceLink, deterministic/reproducible builds, global.json SDK pinning. USE FOR: scaffolding a new .NET repo or solution; choosing .sln vs .slnx; sharing MSBuild properties (TargetFramework, LangVersion, Nullable, ImplicitUsings, TreatWarningsAsErrors, EnforceCodeStyleInBuild, EnableNETAnalyzers, Deterministic) across every project; configuring SourceLink for debuggable NuGet packages; central package version management and GlobalPackageReference; pinning the SDK with global.json; .editorconfig code-style rules; CI-only ContinuousIntegrationBuild flag; reproducible/deterministic builds and packages; repo root file checklist. DO NOT USE FOR: C# language feature choices (use csharp-best-practices); benchmarking (use dotnet-benchmarking); generic math (use dotnet-generic-math).

references/central-package-management.md

View on GitHub
# Central Package Management (CPM) — Full Reference

## Enabling

Create `Directory.Packages.props` at the repo root:

```xml
<Project>
  <PropertyGroup>
    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
    <CentralPackageTransitivePinningEnabled>true</CentralPackageTransitivePinningEnabled>
  </PropertyGroup>

  <ItemGroup>
    <PackageVersion Include="Microsoft.Extensions.Configuration" Version="10.0.0" />
    <PackageVersion Include="xunit" Version="2.9.2" />
  </ItemGroup>

  <!-- Applies to every project automatically; use for build-time-only deps -->
  <ItemGroup>
    <GlobalPackageReference Include="Microsoft.SourceLink.GitHub" Version="8.0.0" />
    <GlobalPackageReference Include="Nerdbank.GitVersioning" Version="3.6.*" />
  </ItemGroup>
</Project>
```

Each project's `.csproj` then omits the version:

```xml
<ItemGroup>
  <PackageReference Include="Microsoft.Extensions.Configuration" />
</ItemGroup>
```

Auto-generate the skeleton: `dotnet new packagesprops`.

## Key Behaviors

| Feature | Property | Notes |
|---------|----------|-------|
| Central versions | `ManagePackageVersionsCentrally=true` | required; NuGet auto-imports `Directory.Packages.props` if present (since .NET 5) even without this flag — rename the file if you don't want that |
| Transitive pinning | `CentralPackageTransitivePinningEnabled=true` | promotes a transitive dependency to top-level when you pin a higher version than requested; downgrades below the requested version raise `NU1109` |
| Per-project override | `<PackageReference Include="X" VersionOverride="1.2.3" />` | escape hatch for one project; disable repo-wide via `CentralPackageVersionOverrideEnabled=false` |
| Global references | `<GlobalPackageReference>` in `Directory.Packages.props` | added to every project with `PrivateAssets=All` implicitly — use for analyzers, SourceLink, versioning tools, never for runtime libraries |
| Per-TFM versions | MSBuild `Condition` on `<PackageVersion Update="X" Condition="...">` | needed when a package drops support for an older TFM your repo still targets |

## Multiple `Directory.Packages.props` Files

Only the **closest** file to a project is auto-imported. A nested one does *not* inherit the root file's `<PackageVersion>` entries unless you import it explicitly:

```xml
<Project>
  <Import Project="$([MSBuild]::GetPathOfFileAbove(Directory.Packages.props, $(MSBuildThisFileDirectory)..))" />
  <ItemGroup>
    <PackageVersion Update="Newtonsoft.Json" Version="13.0.3" />
  </ItemGroup>
</Project>
```

Prefer a single root-level file for a mono-repo unless different solutions genuinely need different dependency graphs.

## NU1507 — Multiple Package Sources

CPM warns if `NuGet.config` defines more than one package source, because it can't tell which source should resolve which package. Fix with [package source mapping](https://aka.ms/nuget-package-source-mapping):

```xml
<!-- NuGet.config -->
<configuration>
  <packageSourceMapping>
    <packageSource key="nuget.org">
      <package pattern="*" />
    </packageSource>
  </packageSourceMapping>
</configuration>
```

Or reduce to a single source if internal feeds aren't in use.

## Disabling for One Project

```xml
<PropertyGroup>
  <ManagePackageVersionsCentrally>false</ManagePackageVersionsCentrally>
</PropertyGroup>
```

Use sparingly — defeats the purpose of a repo-wide single source of truth for versions.
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall