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/directory-build-props.md

View on GitHub
# Directory.Build.props — Full Reference

MSBuild auto-imports `Directory.Build.props` from the project's directory or any ancestor, before the project file's own properties — put it at the repo root (or solution root) so every project inherits it.

## Complete Example

```xml
<Project>

  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <LangVersion>latest</LangVersion>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
    <EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>
    <Deterministic>true</Deterministic>

    <!-- Code-quality analyzers (CAxxxx) -->
    <EnableNETAnalyzers>true</EnableNETAnalyzers>
    <AnalysisLevel>latest</AnalysisLevel>
    <AnalysisMode>Recommended</AnalysisMode>

    <!-- Docs & globalization -->
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
    <NoWarn>$(NoWarn);CS1591</NoWarn> <!-- missing XML doc comment; drop once docs are complete -->
    <InvariantGlobalization>true</InvariantGlobalization>

    <!-- Repeat repo metadata once instead of per-project -->
    <Authors>Your Org</Authors>
    <Company>Your Org</Company>
    <RepositoryUrl>https://github.com/org/repo</RepositoryUrl>
    <PackageLicenseExpression>MIT</PackageLicenseExpression>
  </PropertyGroup>

  <!-- SourceLink: only meaningful for packable/publishable projects, harmless elsewhere -->
  <PropertyGroup>
    <PublishRepositoryUrl>true</PublishRepositoryUrl>
    <EmbedUntrackedSources>true</EmbedUntrackedSources>
    <DebugType>portable</DebugType>
    <IncludeSymbols>true</IncludeSymbols>
    <SymbolPackageFormat>snupkg</SymbolPackageFormat>
    <!-- Set true only on CI: rewrites local paths to repo-relative ones -->
    <ContinuousIntegrationBuild Condition="'$(CI)' == 'true' OR '$(TF_BUILD)' == 'true'">true</ContinuousIntegrationBuild>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.SourceLink.GitHub" Version="8.0.0" PrivateAssets="All" />
  </ItemGroup>

</Project>
```

## Property Rationale

| Property | Why |
|----------|-----|
| `AnalysisLevel=latest` | opt into newest analyzer rules as the SDK updates, instead of freezing at the SDK's TFM-tied default |
| `AnalysisMode=Recommended` | stricter than `Default`; use `All` for greenfield repos willing to triage every rule |
| `TreatWarningsAsErrors` + `EnforceCodeStyleInBuild` | turns IDE-only suggestions (`IDE0xxx`) and analyzer warnings (`CAxxxx`) into build failures — style drift can't merge |
| `GenerateDocumentationFile` | required for doc-comment analyzers (`CS1591` etc.) and for consumers' IntelliSense |
| `InvariantGlobalization` | smaller, faster apps; opt out (`false`) if the app does culture-sensitive formatting/sorting |
| `DebugType=portable` | cross-platform PDB format required by SourceLink (avoid `full`, which is Windows-only) |
| `ContinuousIntegrationBuild` | must be conditioned on a CI env var — always-true breaks local "Just My Code" debugging and makes local builds non-reproducible in a useful way |

## Test Project Overrides

Test projects shouldn't inherit packable/publish properties. Add a second, narrower props file at `tests/Directory.Build.props` (MSBuild uses the *closest* one, so re-`Import` the root file explicitly):

```xml
<Project>
  <Import Project="$([MSBuild]::GetPathOfFileAbove(Directory.Build.props, $(MSBuildThisFileDirectory)..))" />
  <PropertyGroup>
    <IsPackable>false</IsPackable>
    <IsTestProject>true</IsTestProject>
    <NoWarn>$(NoWarn);CA1707</NoWarn> <!-- underscores in test method names -->
  </PropertyGroup>
</Project>
```

## Git-Based Versioning

Add a `GlobalPackageReference` (applies to every project without touching each `.csproj`) in `Directory.Packages.props`, not `Directory.Build.props`:

```xml
<ItemGroup>
  <GlobalPackageReference Include="Nerdbank.GitVersioning" Version="3.6.*" />
</ItemGroup>
```

Alternative: `MinVer`. Both derive `Version`/`InformationalVersion` from git tags — avoids hand-editing version numbers per release.

## Deterministic / Reproducible Builds

- `Deterministic=true` is the C# compiler default since .NET SDK — set it explicitly for clarity.
- Starting with .NET 11, `dotnet pack` produces deterministic `.nupkg` files by default; the only variable is file-modification timestamps.
- Pin a reproducible timestamp with `DeterministicTimestamp` (or the `SOURCE_DATE_EPOCH` env var), e.g. from the last commit: `export SOURCE_DATE_EPOCH=$(git log -1 --pretty=%ct)`.
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