skip to content

How does Directory.Build.props share MSBuild settings across a .NET solution, and why does a nested Directory.Build.props stop inheriting from the parent one?

level: middleimportance: should knowfreq 42%

answer

  1. imported automatically, no Import line
  2. first file found walking up
  3. early import: the project can override
  4. explicit Import or buildprops --inherit
  5. Directory.Build.targets for late logic

basics

~20 s

MSBuild automatically imports the first Directory.Build.props it finds walking up from each project's folder, early in evaluation, so common properties live in one place. It stops at that first file, so a nested one must import its parent explicitly to keep inheriting.

solid answer

~40 s

Every SDK-style project imports **`Directory.Build.props`** automatically: MSBuild searches from the project's directory upward and imports the **first** one it finds, before the project's own properties, so the project can still override them. Put repository-wide settings there: `Nullable`, `TreatWarningsAsErrors`, `UseArtifactsOutput`, company metadata. The search **stops at the first file**, so a `tests/Directory.Build.props` that sets test-only properties hides the root file unless it imports it, for example `<Import Project="..\Directory.Build.props" />`; `dotnet new buildprops --inherit` generates that line. **`Directory.Build.targets`** is imported late, after the project body, for logic that depends on properties the project sets, such as conditions on `$(TargetFramework)`. Central package versions belong in `Directory.Packages.props`, a different file.

code

xml · 8 lines
xml
<!-- Directory.Build.props at the repository root -->
<Project>
  <PropertyGroup>
    <Nullable>enable</Nullable>
    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
    <UseArtifactsOutput>true</UseArtifactsOutput>
  </PropertyGroup>
</Project>

go deeper

for a junior

Recall that Directory.Build.props holds MSBuild settings every project below it picks up automatically.

for a middle

Explain the upward search, that only the first file is imported, early versus late import with Directory.Build.targets, and how a nested file inherits explicitly.

for a senior

Structure a large solution's shared settings, avoid TargetFramework traps, verify values with --getProperty, and keep test and source settings layered deliberately.

for a principal

Decide what is enforced centrally and what projects may override, so the build policy stays reviewable in a few files instead of drifting across dozens of project files.

## The problem it solves A 40-project solution repeats the same settings in every `.csproj`: nullable reference types on, warnings as errors, the same authors and copyright, an artifacts output folder. Changing one means 40 edits and inevitably a missed project. **`Directory.Build.props`** puts them in one file that every project picks up without any `Import` line. ## How the import works 1. When MSBuild evaluates a project, the SDK's common props look for `Directory.Build.props` starting in the **project's own directory** and walking **up** toward the file-system root. 2. The **first** file found is imported; the search then stops. 3. The import happens **early**, before the body of the `.csproj`. Properties set there act as defaults, and the project file can override any of them. The companion **`Directory.Build.targets`** is found the same way but imported **late**, after the project body and the SDK targets. Use it for logic that must see what the project set, such as items conditioned on `$(TargetFramework)` or custom targets. A project can opt out with `ImportDirectoryBuildProps` set to `false`, a property the SDK's own internal projects use. ## What belongs in it - Language and analysis settings: `<Nullable>enable</Nullable>`, `<ImplicitUsings>enable</ImplicitUsings>`, `<TreatWarningsAsErrors>true</TreatWarningsAsErrors>`. - Output layout: `<UseArtifactsOutput>true</UseArtifactsOutput>` moves `bin` and `obj` under one `artifacts` folder next to the file, which must be set this early to take effect. - Package metadata shared by all packable projects: authors, repository URL, license expression. - Avoid `TargetFramework` here unless every project truly shares it: a singular value hides any project's `TargetFrameworks`. - Avoid `LangVersion` `latest`; the default language version already follows the target framework. Central package versions go in **`Directory.Packages.props`**, a separate file with its own rules. ## Why nesting surprises people Because the search stops at the first file, a folder-level file **replaces** the root one for every project below it rather than adding to it. A team adds `tests/Directory.Build.props` with `<IsPackable>false</IsPackable>`, and suddenly the test projects lose `Nullable` and `TreatWarningsAsErrors` from the root file. The fix is an explicit import of the parent at the top of the nested file: - `<Import Project="..\Directory.Build.props" />` when the parent is one level up; EF Core's own `src/Directory.Build.props` starts exactly this way. - `dotnet new buildprops --inherit` generates a file that imports the closest parent file for you. ## Creating the files - `dotnet new buildprops` creates an empty `Directory.Build.props`; `--use-artifacts` adds the artifacts output settings. - `dotnet new buildtargets` does the same for `Directory.Build.targets`. ## Verifying `dotnet build --getProperty:Nullable` (or any property) evaluates a project and prints the final value, which shows whether the shared file and any nested file were applied as intended. ## Common mistakes - Expecting nested files to merge automatically. - Putting logic that tests `$(TargetFramework)` into the props file, where the project has not set it yet; move it to `Directory.Build.targets`. - Forgetting that a `Directory.Build.props` in a parent folder outside the repository, such as a user's home directory, is also found when the repository has none. ## Beyond project files The .NET 10 SDK's file-based apps are evaluated by MSBuild too, so a `Directory.Build.props` above a single `.cs` script applies to it as well. The SDK documentation even recommends the file as the place for settings a `#:property` directive cannot express, which makes it the one place shared defaults reach both projects and scripts in a repository.

  • Why must UseArtifactsOutput be set in Directory.Build.props rather than the project file?
    The SDK computes the output and intermediate paths early in evaluation. A value set in the project body arrives too late for those paths, while `Directory.Build.props` is imported before them, so the artifacts layout takes effect for every project.
  • How can one project opt out of the shared file?
    Set `ImportDirectoryBuildProps` to `false` before the import happens, for example as a global property, or override the individual properties in the project file, which is evaluated after the shared file.

Directory.Build.props works like a house-rules notice posted at each office floor's entrance: staff read the first notice they pass on the way up, and a floor that posts its own notice replaces the building-wide one unless it says 'and all building rules apply'.

  • Every Directory.Build.props up the folder tree is merged automatically.
  • Each .csproj needs an Import element to use Directory.Build.props.
  • Properties in Directory.Build.props override the same properties in the .csproj.
  • Directory.Build.props is the file for central NuGet package versions.
  • Conditions on $(TargetFramework) work best in Directory.Build.props.