dotnet-tooling

.NET Tooling (stack-agnostic)

Project detection

Determine the project structure at the start of every task:

Signal	Meaning
*.sln exists	Solution file — multiple projects; use dotnet build <solution>.sln
Single *.csproj in root	Single-project layout
global.json exists	SDK version is pinned — read it first
Directory.Build.props exists	Solution-wide MSBuild properties apply
Directory.Packages.props exists	Central Package Management is active — do not specify versions in individual .csproj files

dotnet CLI — core commands

Always run dotnet commands from the directory containing the .sln or .csproj (or pass the path explicitly).

# Restore NuGet packages
dotnet restore

# Build (all projects in the solution, or a single project)
dotnet build
dotnet build MyApp.sln
dotnet build src/MyApp/MyApp.csproj

# Run (application project)
dotnet run --project src/MyApp/MyApp.csproj

# Run tests
dotnet test
dotnet test --filter "Category=Unit"
dotnet test --logger "trx;LogFileName=results.trx"

# Publish (Release, self-contained optional)
dotnet publish -c Release -o ./publish
dotnet publish -c Release --runtime linux-x64 --self-contained

# Check outdated packages
dotnet list package --outdated

# Format code (respects .editorconfig)
dotnet format

# Verify formatting without writing changes (useful in CI)
dotnet format --verify-no-changes

global.json — pin the SDK version

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

Always read global.json first to learn which SDK version is in use. Do not recommend commands or features that require a higher SDK version than what is pinned.

rollForward: "latestPatch" allows minor patch upgrades automatically — safe for CI. Use "disable" for strict reproducibility.

.csproj — project file conventions

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

  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>   <!-- or net9.0, net10.0 -->
    <Nullable>enable</Nullable>                  <!-- always enable -->
    <ImplicitUsings>enable</ImplicitUsings>      <!-- reduces boilerplate using directives -->
    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>  <!-- recommended for new projects -->
    <AnalysisLevel>latest</AnalysisLevel>        <!-- Roslyn analyzers at latest rules set -->
  </PropertyGroup>

  <ItemGroup>
    <!-- With Central Package Management: version goes in Directory.Packages.props -->
    <PackageReference Include="Microsoft.Extensions.Logging.Abstractions" />
    <PackageReference Include="Newtonsoft.Json" />

    <!-- Without CPM: pin versions explicitly — no floating ranges -->
    <!-- <PackageReference Include="Serilog" Version="4.1.0" /> -->
  </ItemGroup>

</Project>

Never use floating version ranges (*, 1.*, [1.0,)) — they break reproducible builds. Pin exact or minimum patch versions.

NuGet — PackageReference lifecycle

# Add a package
dotnet add package Serilog --version 4.1.0
dotnet add src/MyApp/MyApp.csproj package FluentValidation

# Remove a package
dotnet remove package Serilog

# Inspect the dependency graph
dotnet list package
dotnet list package --include-transitive
dotnet list package --outdated

When to add a package

1. Check if the framework already provides the functionality (Microsoft.Extensions.* for DI, logging, configuration).
2. Prefer packages with active maintenance, wide adoption, and no critical CVEs.
3. Note the addition in DECISIONS — non-trivial additions change the project's supply-chain footprint.

Central Package Management (Directory.Packages.props)

When Directory.Packages.props exists, do not specify Version= attributes in individual .csproj files — the central file owns all version pins.

<!-- Directory.Packages.props (at solution root) -->
<Project>
  <PropertyGroup>
    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
  </PropertyGroup>

  <ItemGroup>
    <PackageVersion Include="Microsoft.EntityFrameworkCore" Version="8.0.11" />
    <PackageVersion Include="FluentValidation" Version="11.11.0" />
    <PackageVersion Include="xunit" Version="2.9.2" />
    <PackageVersion Include="xunit.runner.visualstudio" Version="2.8.2" />
    <PackageVersion Include="Moq" Version="4.20.72" />
    <PackageVersion Include="FluentAssertions" Version="6.12.1" />
  </ItemGroup>
</Project>

Add new packages with:

# When CPM is active, dotnet add package still updates Directory.Packages.props
dotnet add package NewPackage --version 1.2.3

Directory.Build.props — solution-wide MSBuild properties

<!-- Directory.Build.props (at solution root) — applies to ALL projects -->
<Project>
  <PropertyGroup>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
    <LangVersion>latest</LangVersion>
    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
    <AnalysisLevel>latest</AnalysisLevel>
    <Authors>Your Org</Authors>
    <Copyright>© 2025 Your Org</Copyright>
  </PropertyGroup>
</Project>

Do not repeat properties already in Directory.Build.props in individual .csproj files — they are inherited automatically.

Multi-targeting

When a library must support multiple runtimes:

<PropertyGroup>
  <TargetFrameworks>net6.0;net8.0</TargetFrameworks>  <!-- semicolon-separated -->
</PropertyGroup>

Use #if NET8_0_OR_GREATER preprocessor symbols to conditionally compile version-specific code.

dotnet format — code formatting

dotnet format respects .editorconfig and Roslyn analyzer rules. Run it after writing code:

# Fix all formatting issues in place
dotnet format

# Only fix whitespace issues (fastest)
dotnet format whitespace

# Only fix style issues (var usage, using directives, etc.)
dotnet format style

# CI gate — fails if any changes would be made
dotnet format --verify-no-changes

Create a .editorconfig at the solution root to enforce consistent style. Minimum recommended settings:

root = true

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

# Prefer file-scoped namespaces
csharp_style_namespace_declarations = file_scoped:warning

# Prefer var when type is apparent
csharp_style_var_for_built_in_types = false:suggestion
csharp_style_var_when_type_is_apparent = true:suggestion
csharp_style_var_elsewhere = false:suggestion

packages.lock.json — lock file for reproducibility

Enable lock files when reproducible restores are required (CI, Docker images):

<!-- .csproj or Directory.Build.props -->
<PropertyGroup>
  <RestorePackagesWithLockFile>true</RestorePackagesWithLockFile>
</PropertyGroup>

Commit packages.lock.json alongside source. In CI, restore with --locked-mode to fail on any drift:

dotnet restore --locked-mode