Project structure & SDK
Use one solution format and Central Package Management, and pin versions at the repository root. The files in templates/ implement these opinions. Copy them verbatim and trim, instead of writing your own.
Solution & SDK
- Use
.slnxfor new solutions. The .NET 10 SDK'sdotnet new slncreates one by default. Migrate a.slnfile when you're already changing it, and use.slnffilters for large solutions. Start from templates/example.slnx and templates/example.slnf. (Microsoft Learn: Breaking changes in .NET 10) - Pin the SDK in
global.jsonwithrollForwardset tolatestFeature, as in templates/global.json. (Microsoft Learn: global.json overview) - Treat the pinned version as a minimum, and raise it only for a feature you need. Under
latestFeature,11.0.100means that version or any later band and patch on the machine, so new bands reach the build without a file change. Pinning a patch such as11.0.105, or bumping for every band, only fails contributors one servicing release behind. When a band ships something the repository uses, raise the minimum, and name the feature in the commit. (Microsoft Learn: global.json overview) -
To try a preview SDK, use
sdk.paths, and ignore its install folder in the same commit../dotnet-install.sh --install-dir .dotnet(-InstallDirin PowerShell) installs the SDK inside the repository.pathsmakes the host prefer it, and$host$falls back to the machine install.- Paths resolve relative to
global.json, so this works from any subdirectory. errorMessagereplaces the bare version error for a contributor who has neither SDK.- Only SDK commands, such as
dotnet buildanddotnet run, readpaths. It doesn't affect "running the native apphost launcher (app.exe), running withdotnet app.dll, or running withdotnet exec app.dll". (Microsoft Learn: global.json overview) - The folder holds a full SDK of several hundred megabytes, so never commit it.
(Versluis: Test .NET MAUI Preview SDKs Locally with global.json sdk.paths, Microsoft Learn: test prerelease SDKs locally)
{ "sdk": { "version": "11.0.100-rc.2.26504.105", "paths": [".dotnet", "$host$"], "errorMessage": "Run ./dotnet-install.sh --install-dir .dotnet --version 11.0.100-rc.2.26504.105" } }The example pins .NET 11 RC 2, a real version of a release that has since shipped, because no .NET 12 preview exists yet. When .NET 12 Preview 1 ships, replace both version strings with its SDK version, and drop this note. Review by 2027-03-31.
dotnet new gitignoredoesn't ignore.dotnet/, because it covers build output and a local SDK is a build prerequisite.dotnet/runtime,dotnet/aspnetcore,dotnet/sdk, anddotnet/mauieach add the rule by hand. When you adoptsdk.paths, add.dotnet/to the repository-specific block of.gitignoredescribed below. - Paths resolve relative to
-
Use Central Package Management (
Directory.Packages.props), even in a single-project repository. It applies to everyPackageReference-based project. Versions set per project drift apart once a second project arrives. On .NET 10 and later, NU1510 flags direct references that package pruning can remove. Start from templates/Directory.Packages.props, which enablesCentralPackageTransitivePinningEnabled. (Microsoft Learn: Central Package Management, Microsoft Learn: NU1510, Microsoft Learn: Breaking changes in .NET 10)- Remove the
Versionfrom eachPackageReferencethat adotnet newtemplate writes.dotnet new webapiwrites<PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="11.0.0" />, and the restore it then runs fails with NU1008: "Projects using Central Package Management must define a Version value on a PackageVersion item." Delete the attribute, and add aPackageVersiontoDirectory.Packages.propsif the package has none. (Microsoft Learn: NuGet Error NU1008)
- Remove the
- Put shared build settings in
Directory.Build.props: the TFM,LangVersionset to latest, nullable enabled, analyzers on, and warnings as errors. Copy templates/Directory.Build.props. A setting that depends on a property the project file sets, such asIsPackable, goes in templates/Directory.Build.targets, which MSBuild imports after the project file. Project files are then nearly empty, as in templates/projects/. (Microsoft Learn: Customize the build by folder) -
Set
<IsPackable>true</IsPackable>in the project file of every library that ships as a NuGet package. MSBuild's default istrue, but templates/Directory.Build.props sets it tofalse, sodotnet packskips every project that doesn't opt in. The same property keeps MA0004 on for the library, as runtime-performance.md: Async describes. (Microsoft Learn: NuGet pack and restore as MSBuild targets) -
Run one-off tools with
dotnet tool execordnxinstead of installing them globally.dnxignores the SDK selection inglobal.json. (Microsoft Learn: What's new in the .NET 10 SDK, Microsoft Learn: Breaking changes in .NET 10) - Use file-based apps (
dotnet run app.cs) for scripts and samples instead of throwaway console projects. They support publishing and Native AOT. (Microsoft Learn: What's new in the .NET 10 SDK) - Target the latest release, LTS or STS. That's this repository's freshness policy. .NET 11 is an STS release, supported until 2028-11-14. .NET 10, the LTS release before it, ends support on the same day. (Microsoft: .NET Support Policy)
Repository layout
- Put shipping code in
src/, test projects intests/, and build configuration at the root. Give each project its own directory, named after the assembly. Mirror the disk layout in the solution with/src/and/tests/solution folders, as templates/example.slnx does. (Stannard: project-structure, dotnet/samples: migrate-library-csproj)
House opinion ยท Simon McKenna
House: Add a /build/ solution folder that lists Directory.Build.props, Directory.Build.targets, Directory.Packages.props, global.json, and .editorconfig. They configure every project, and the folder shows them in Solution Explorer. templates/example.slnx includes it, and Stannard: project-structure uses the same shape.
-
Set
<UseArtifactsOutput>true</UseArtifactsOutput>in the rootDirectory.Build.props. All build output goes under oneartifacts/<type>/<project>/<pivot>root, instead ofbin/andobj/in each project.- The types are
bin,obj,publish, andpackage.packagehas no project folder, so.nupkgfiles go toartifacts/package/<configuration>. - Tools and CI steps can rely on the layout. The per-project layout "can change drastically via relatively simple MSBuild changes".
- It has been GA since .NET 8, and it's still opt-in in the .NET 10 SDK. templates/Directory.Build.props opts in.
- MSBuild reads the property before it evaluates the project, so set it only in
Directory.Build.propsor on the command line. In a project file, it fails the build withNETSDK1199. (dotnet/sdk: Strings.resx) - For a single-TFM project, the last folder is the lowercase configuration, with no TFM:
artifacts/bin/App/release. Update hard-codedbin/<Config>/<tfm>paths in Dockerfiles, CI steps, and scripts in the same commit. dotnet new gitignorealready ignoresartifacts/. (dotnet/sdk: Gitignore template)
(Microsoft Learn: Artifacts output layout, .NET Blog: Announcing .NET 8 Preview 3)
- The types are
-
Keep
global.json,Directory.Build.props,Directory.Build.targets,Directory.Packages.props, and.editorconfigat the repository root. MSBuild searches up from each project for the nearestDirectory.Build.propsandDirectory.Build.targets, and Central Package Management findsDirectory.Packages.propsthe same way, so every project inherits the root files. The search stops at the first file it finds. A file of the same name in a subfolder therefore replaces the root one for the projects under it, unless it imports the root one first:<Import Project="$([MSBuild]::GetPathOfFileAbove('Directory.Build.targets', '$(MSBuildThisFileDirectory)../'))" />. (Microsoft Learn: Customize the build by folder, Microsoft Learn: Central Package Management) - Put test projects beside the code they test, never inside it.
tests/Example.Library.Testsmirrorssrc/Example.Library, named<Project>.Tests. For what goes in them, see testing.md. - Inside a project, group by feature, not by pattern. For modules and vertical slices, see architecture.md.
- Don't add structure before you need it. A single-project tool can be
src/Toolandtests/Tool.Tests. Adddocs/and solution filters when the repository needs them. (Microsoft Learn: Organizing and testing projects with the .NET CLI) - Generate
.gitignorewithdotnet new gitignore, and don't edit the generated part. The SDK template is the standard .NET ignore list, and it changes with the toolchain, so this repository ships no.gitignoretemplate. Regenerate the file after major SDK upgrades. Keep repository-specific additions, such as.dotnet/, in a marked block at the end, so you can overwrite everything above it. (Microsoft Learn: dotnet new gitignore)
.editorconfig
- Give every repository a root
.editorconfig, copied from templates/.editorconfig. Remove a rule only after you've decided you disagree with it. The file sets file-scoped namespaces, expression-bodied members where they fit on one line, collection expressions, auto-implemented properties (IDE0032), and standard .NET naming, with analyzer diagnostics atwarningby default. - Let the build enforce style.
.editorconfigseverities fail the build only because templates/Directory.Build.props setsEnforceCodeStyleInBuildandTreatWarningsAsErrors. Without both files, nothing enforces the style rules. - Use one
.editorconfigat the root, not one per project. Add a nested file only for a real exception, such as relaxed documentation comment rules undertests/. Put only the differences in it: when both files set a key, the deeper file wins. (Microsoft Learn: Configuration files for code analysis rules)
Containers
-
Build images with
dotnet publish /t:PublishContainer, not a hand-written Dockerfile. The SDK builds the image from the project, so there's no Dockerfile to keep in step with it. It pushes to the local container runtime by default. From .NET 11, it useswslcon Windows orcontaineron macOS when one is installed, and falls back to Docker or Podman. SetContainerRegistryto push to a registry, orContainerArchiveOutputPathto write a tarball. Since .NET 10, console apps work without<EnableSdkContainerSupport>, like ASP.NET Core and Worker apps. (Microsoft Learn: Containerize a .NET app with dotnet publish, Microsoft Learn: What's new in the .NET 10 SDK, Microsoft Learn: What's new in the SDK and tooling for .NET 11)<!-- All container config is MSBuild properties; illustrative values --> <PropertyGroup Label="Container image"> <ContainerRepository>contoso/example-worker</ContainerRepository> <ContainerImageTags>1.4.0;latest</ContainerImageTags> <ContainerFamily>resolute-chiseled</ContainerFamily> </PropertyGroup> -
Expect Ubuntu, not Debian, in the base images. Since .NET 10, version-only tags resolve to Ubuntu, and there are no Debian images.
mcr.microsoft.com/dotnet/aspnet:11.0is Ubuntu 26.04 "Resolute", whereaspnet:10.0is Ubuntu 24.04 "Noble". For a smaller image, setContainerFamilyto a chiseled variant, such asresolute-chiseled, or toalpine. (Microsoft Learn: Default .NET container tags now use Ubuntu, Microsoft Learn: Containerize a .NET app reference, dotnet/dotnet-docker: .NET Container Tags -- Patterns and Policies) - If the app isn't invariant, use the
-extratag. The chiseled and Alpine images include neither ICU nortzdata, and setDOTNET_SYSTEM_GLOBALIZATION_INVARIANT=true. An app that names a culture throwsCultureNotFoundExceptionat startup. An app that only readsCurrentCultureformats and compares as invariant without an error.<InvariantGlobalization>false</InvariantGlobalization>doesn't override the environment variable.resolute-chiseled-extraandalpine-extraadd back ICU andtzdata. For details, see globalization.md. - Keep the rootless default. For .NET 8 and later on the Microsoft runtime images, container publish sets
ContainerUserto the non-rootappuser on Linux.ContainerPortcomes fromASPNETCORE_URLS,ASPNETCORE_HTTP_PORTS, orASPNETCORE_HTTPS_PORTS. To fix a broken volume mount, fix the mount. Don't setContainerUsertorootor expose a privileged port. (Microsoft Learn: Containerize a .NET app reference)