Organizing Build Infrastructure with Directory.Build Files
Repository integration: this template already uses
Directory.Build.propsandDirectory.Packages.props. Preserve its current conventions; do not re-bootstrap CPM or reorganize build infrastructure unless the task requires it.
Evaluation order
Directory.Build.props → SDK .props → .csproj → SDK .targets → Directory.Build.targets
Use .props for |
Use .targets for |
|---|---|
| property defaults | custom build targets |
| common items | late-bound property overrides |
| package/assembly metadata | logic depending on final SDK properties |
| analyzer PackageReferences | post-build/pack validation |
TargetFramework pitfall
Property conditions on $(TargetFramework) in .props files can silently fail for single-target projects because the project may set the TFM after .props import. Move such property logic to .targets or the project file. See references/targetframework-props-pitfall.md.
Central Package Management
When CPM is enabled:
- package versions belong in
Directory.Packages.props; - project
PackageReferenceitems normally omitVersion=; - do not migrate away from the repository's existing package-governance model as part of unrelated work.
Multi-level Directory.Build files
MSBuild auto-imports the first Directory.Build.props/.targets it finds walking upward. If a repo intentionally uses multiple levels, inner files must explicitly import the parent. See references/multi-level-examples.md.
Workflow
- Audit relevant
.csproj,Directory.Build.props,Directory.Build.targets, andDirectory.Packages.propsfiles. - Identify duplicated vs project-specific settings.
- Preserve existing ownership of versioning, analyzers, packaging, and warnings.
- Move only clearly shared defaults into
.props. - Keep custom targets/late SDK-dependent logic in
.targets. - Validate with restore/build/test and, when needed, preprocessed MSBuild output.
Useful diagnosis:
dotnet msbuild -pp:output.xml path/to/Project.csproj
Validation
- No
TargetFramework-dependent property was moved to an early.propsevaluation point - CPM remains consistent
- Project-specific settings were not generalized without evidence
- Restore/build/test still pass
- Packaging metadata/output remains unchanged unless intentionally modified
See references/common-patterns.md for common layouts and validation examples.