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: What's new in .NET 10) - Treat the pinned version as a minimum, and raise it only for a feature you need. Under
latestFeature,10.0.400means 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 as10.0.412, 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. The apphost anddotnet app.dllignore it. - 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-preview.1.25000.1", "paths": [".dotnet", "$host$"], "errorMessage": "Run ./dotnet-install.sh --install-dir .dotnet --version 11.0.100-preview.1.25000.1" } }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) - 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)
House opinion · Simon McKenna
House: Warnings as errors is always on, not only in CI. You can suppress a warning, but only with an inline comment that says why. ci.md holds the canonical statement.
- 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 10 is an LTS release, supported until November 2028. (Microsoft Learn: .NET releases, patches, and support)
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. (Microsoft Learn: Organize projects for .NET Framework and .NET, 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. - 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 drift. It pushes to the local Docker or Podman daemon by default. SetContainerRegistryto push to a registry, orContainerArchiveOutputPathto write a tarball. In .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) -
Expect Ubuntu, not Debian, in .NET 10 base images. Version-only tags, such as
mcr.microsoft.com/dotnet/aspnet:10.0, resolve to Ubuntu 24.04 "Noble", and there are no Debian images for .NET 10. For a smaller image, setContainerFamilyto a chiseled variant, such asnoble-chiseled, or toalpine. (Microsoft Learn: Default .NET container tags now use Ubuntu, 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.noble-chiseled-extraandalpine-extraadd back ICU andtzdata. For details, see globalization.md. - Keep the rootless default. Since .NET 8, Linux images run as the non-root
appuser, andContainerPortcomes 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)