# Project Conventions > This skill should be used when creating or editing .csproj files, managing NuGet packages, configuring Directory.Build.props or Directory.Packages.props, organizing .NET solutions, or setting up global.json and .editorconfig. - Skill: `diegosouzapw/project-conventions` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add diegosouzapw/project-conventions` - Raw SKILL.md: https://api.skillmd.com/api/skills/diegosouzapw/project-conventions/raw - Safety review: pending (external: skill-scanner PASS, skillspector CAUTION) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: diegosouzapw (https://skillmd.com/u/diegosouzapw) - Updated: 2026-09-08 - Page: https://skillmd.com/skills/diegosouzapw/project-conventions --- # .NET Project Conventions and Build Configuration This skill defines comprehensive conventions for .NET project structure, Central Package Management, build configuration, solution organization, and tooling setup. ## SDK-Style .csproj Structure ### Minimal .csproj for Source Projects Source project files should be as minimal as possible. Properties shared across all projects belong in `Directory.Build.props`, not in each `.csproj`. ```xml Catalog.Application ``` ```xml net8.0 enable enable true latest Catalog.Application ``` ### Web API Project Uses Web SDK ```xml Catalog.Api ``` ```xml Catalog.Api Exe ``` ### Test Project Inherits from tests/Directory.Build.props ```xml ``` ```xml false true ``` ## Central Package Management (CPM) ### Always Use Directory.Packages.props All package versions must be declared centrally. Individual `.csproj` files reference packages without version numbers. ```xml true true ``` ```xml ``` ```xml ``` ### Group Packages by Category in CPM ```xml true ``` ```xml true ``` ### Enable Transitive Pinning Always enable `CentralPackageTransitivePinningEnabled` to control transitive dependency versions. ```xml true true ``` ```xml true ``` ## Directory.Build.props ### Root Props for Shared Settings Place at the solution root. Applies to all projects in the directory tree. ```xml net8.0 enable enable true latest latest-recommended true true ``` ```xml net8.0 ``` ### Test Props Import Parent Then Add Test-Specific Settings ```xml false true $(NoWarn);CA1707 ``` ```xml net8.0 false true ``` ## Solution Layout ### Layered Architecture with src/ and tests/ ```text CORRECT: project-root/ ├── src/ │ ├── MyApp.Api/ (Web layer) │ ├── MyApp.Application/ (Business logic) │ ├── MyApp.Domain/ (Domain models) │ └── MyApp.Infrastructure/ (Data access, external) ├── tests/ │ ├── Directory.Build.props (test-specific) │ ├── MyApp.Application.Tests/ │ ├── MyApp.Domain.Tests/ │ └── MyApp.Api.Tests/ ├── Directory.Build.props (shared) ├── Directory.Packages.props (CPM) ├── global.json ├── .editorconfig └── MyApp.sln ``` ```text WRONG: project-root/ ├── MyApp.Api/ ├── MyApp.Application/ ├── MyApp.Domain/ ├── MyApp.Infrastructure/ ├── MyApp.Tests/ (single test project for everything) └── MyApp.sln ``` ### Test Project Mirrors Source Project ```text CORRECT: src/Catalog.Application/Services/ProductService.cs tests/Catalog.Application.Tests/Services/ProductServiceTests.cs src/Catalog.Domain/Models/Order.cs tests/Catalog.Domain.Tests/Models/OrderTests.cs ``` ```text WRONG: src/Catalog.Application/Services/ProductService.cs tests/Tests/ProductServiceTest.cs src/Catalog.Domain/Models/Order.cs tests/Tests/OrderTests.cs ``` ## global.json ### Always Pin SDK Version ```json { "sdk": { "version": "8.0.404", "rollForward": "latestPatch", "allowPrerelease": false } } ``` ```json // WRONG: No global.json at all // Different developers may use different SDK versions, // causing inconsistent builds ``` ### Use latestPatch Roll-Forward ```json { "sdk": { "version": "8.0.404", "rollForward": "latestPatch" } } ``` ```json // WRONG: latestMajor allows any SDK { "sdk": { "version": "8.0.404", "rollForward": "latestMajor" } } ``` ## .editorconfig ### Must Exist at Solution Root Every .NET solution must have an `.editorconfig` at the root. At minimum, it must set: ```text # CORRECT: Minimum .editorconfig 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}] indent_size = 2 [*.cs] csharp_style_namespace_declarations = file_scoped:warning dotnet_style_qualification_for_field = false:warning ``` ### Enforce File-Scoped Namespaces ```text # CORRECT: Enforce file-scoped namespaces [*.cs] csharp_style_namespace_declarations = file_scoped:warning ``` ```text # WRONG: No namespace style enforcement [*.cs] csharp_style_namespace_declarations = file_scoped:suggestion ``` ### Enforce Naming Conventions ```text # CORRECT: Naming rules enforced as errors dotnet_naming_rule.interfaces_must_begin_with_i.severity = error dotnet_naming_rule.types_must_be_pascal_case.severity = error dotnet_naming_rule.private_fields_must_be_camel_case.severity = warning ``` ```text # WRONG: Naming rules as suggestions (not enforced) dotnet_naming_rule.interfaces_must_begin_with_i.severity = suggestion dotnet_naming_rule.types_must_be_pascal_case.severity = suggestion ``` ## NuGet Publishing ### Library Projects Include Package Metadata ```xml Acme.Shared.Contracts 1.0.0 Shared contracts and DTOs for Acme services MIT README.md true snupkg true true ``` ```xml Acme.Shared.Contracts 1.0.0 ``` ### Non-Publishable Projects Are Marked IsPackable false ```xml false ``` ```xml ``` ## Target Framework ### Use Latest LTS Framework ```xml net8.0 ``` ```xml net6.0 ``` ### Libraries May Multi-Target for Compatibility ```xml net8.0;net9.0 ``` ```xml net6.0;net7.0;net8.0 ``` ## Analyzer Configuration ### Analyzers Are Configured in Directory.Build.props ```xml ``` ```xml ``` ### Analyzer Severity in .editorconfig, Not .csproj ```text # CORRECT: Severity in .editorconfig [*.cs] dotnet_diagnostic.CA1062.severity = none dotnet_diagnostic.CA2007.severity = none dotnet_diagnostic.IDE0005.severity = warning ``` ```xml $(NoWarn);CA1062;CA2007 ``` ## Build Determinism ### Enable Deterministic Builds ```xml true true ``` ```xml ``` ## dotnet format Integration ### Format Exclusions Are Applied Consistently Always exclude generated code from formatting checks: ```bash # CORRECT: Exclude generated code dotnet format --verify-no-changes --exclude obj/ --exclude Migrations/ ``` ```bash # WRONG: No exclusions (fails on EF migrations) dotnet format --verify-no-changes ``` ## .gitignore Essentials ### Must Ignore Build Artifacts and IDE Files ```text # CORRECT: Standard .NET .gitignore [Bb]in/ [Oo]bj/ TestResults/ .vs/ .idea/ *.user *.suo launchSettings.json ``` ```text # WRONG: Missing critical entries bin/ obj/ # Missing .vs/, TestResults/, *.user ```