Directory.Build ファイルを使用したビルド インフラストラクチャの構成

Directory.Build.props vs Directory.Build.targets

どちらのファイルを使用すべきかを理解することは重要です。これらはビルド評価中にインポートされるタイミングが異なります。

評価順序:

Directory.Build.props → SDK .props → YourProject.csproj → SDK .targets → Directory.Build.targets

.props で使用	.targets で使用
プロパティのデフォルト値設定	カスタム ビルド ターゲット
共通の項目定義	後期バインディング プロパティ オーバーライド
プロジェクトがオーバーライドできるプロパティ	ビルド後ステップ
アセンブリ/パッケージ メタデータ	最終値の条件付きロジック
アナライザー PackageReferences	SDK定義プロパティに依存するターゲット

経験則: プロパティと項目は .props に配置します。カスタム ターゲットと後期バインディング ロジックは .targets に配置します。

.props はプロジェクト ファイルの前にインポートされるため、プロジェクトはそこで設定された任意の値をオーバーライドできます。.targets はすべての後でインポートされるため、最終的な決定権を持ちます。ただし、プロジェクトは .targets の値をオーバーライドできません。

⚠️ 重要: .props vs .targets での TargetFramework の利用可能性

.props ファイルで $(TargetFramework) の条件が設定されたプロパティは、シングル ターゲット プロジェクトでは暗黙的に失敗します — .props 評価中にプロパティは空です。TFM条件付きプロパティを代わりに .targets に移動してください。ItemGroup と Target の条件は影響を受けません。

完全な説明については targetframework-props-pitfall.md を参照してください。

Directory.Build.props

推奨される用途: 言語設定、アセンブリ/パッケージ メタデータ、ビルド警告、コード分析、共通のアナライザー。

<Project>
  <PropertyGroup>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
    <EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>
    <Company>Contoso</Company>
    <Authors>Contoso Engineering</Authors>
  </PropertyGroup>
</Project>

ここに配置しないでください: プロジェクト固有の TFM、プロジェクト固有の PackageReferences、ターゲット/ビルド ロジック、またはSDK定義値に依存するプロパティ（.props 評価中は利用できません）。

Directory.Build.targets

推奨される用途: カスタム ビルド ターゲット、後期バインディング プロパティ オーバーライド（SDK プロパティに依存する値）、ビルド後検証。

<Project>
  <Target Name="ValidateProjectSettings" BeforeTargets="Build">
    <Error Text="All libraries must target netstandard2.0 or higher"
           Condition="'$(OutputType)' == 'Library' AND '$(TargetFramework)' == 'net472'" />
  </Target>

  <PropertyGroup>
    <!-- DocumentationFile は、SDK によって設定される OutputPath に依存 -->
    <DocumentationFile Condition="'$(IsPackable)' == 'true'">$(OutputPath)$(AssemblyName).xml</DocumentationFile>
  </PropertyGroup>
</Project>

Directory.Packages.props (Central Package Management)

Central Package Management (CPM) は、すべての NuGet パッケージ バージョンの唯一の情報源を提供します。詳細については https://learn.microsoft.com/en-us/nuget/consume-packages/central-package-management を参照してください。

リポジトリ ルートの Directory.Packages.props で CPM を有効にする:

<Project>
  <PropertyGroup>
    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
  </PropertyGroup>

  <ItemGroup>
    <PackageVersion Include="Microsoft.Extensions.Logging" Version="8.0.0" />
    <PackageVersion Include="Newtonsoft.Json" Version="13.0.3" />
    <PackageVersion Include="xunit" Version="2.9.0" />
    <PackageVersion Include="xunit.runner.visualstudio" Version="2.8.2" />
  </ItemGroup>

  <ItemGroup>
    <!-- GlobalPackageReference はすべてのプロジェクトに適用 — アナライザーに最適 -->
    <GlobalPackageReference Include="StyleCop.Analyzers" Version="1.2.0-beta.556" />
    <GlobalPackageReference Include="Microsoft.CodeAnalysis.NetAnalyzers" Version="8.0.0" />
  </ItemGroup>
</Project>

Directory.Build.rsp

ディレクトリ ツリー下のすべてのビルドに適用される既定の MSBuild CLI 引数を含みます。

サンプル Directory.Build.rsp:

/maxcpucount
/nodeReuse:false
/consoleLoggerParameters:Summary;ForceNoAlign
/warnAsMessage:MSB3277

• 最新の .NET バージョンでは msbuild と dotnet CLI の両方で動作
• 一貫した CI とローカル ビルド フラグの実装に最適
• 各引数は独立した行に配置

マルチレベル Directory.Build ファイル

MSBuild は、プロジェクト ディレクトリから上方向へ探索して見つかった最初の Directory.Build.props（または .targets）のみを自動インポートします。複数のレベルをチェーンするには、内側のファイルの先頭で親を明示的にインポートしてください。完全なファイル例については multi-level-examples を参照してください。

<Project>
  <Import Project="$([MSBuild]::GetPathOfFileAbove('Directory.Build.props', '$(MSBuildThisFileDirectory)../'))"
         Condition="Exists('$([MSBuild]::GetPathOfFileAbove('Directory.Build.props', '$(MSBuildThisFileDirectory)../'))')" />

  <!-- 内側レベルのオーバーライドをここに配置 -->
</Project>

レイアウト例:

repo/
  Directory.Build.props          ← リポジトリ全体（言語バージョン、企業情報、アナライザー）
  Directory.Build.targets        ← リポジトリ全体のターゲット
  Directory.Packages.props       ← 中央パッケージ バージョン
  src/
    Directory.Build.props        ← src固有（リポジトリレベルをインポート、IsPackable=true に設定）
  test/
    Directory.Build.props        ← test固有（リポジトリレベルをインポート、IsPackable=false に設定、テストパッケージを追加）

アーティファクト出力レイアウト (.NET 8+)

Directory.Build.props に <ArtifactsPath>$(MSBuildThisFileDirectory)artifacts</ArtifactsPath> を設定すると、自動的にプロジェクト名で区切られた bin/、obj/、publish/ ディレクトリが単一の artifacts/ フォルダの下に生成され、bin/obj の競合をデフォルトで回避します。ディレクトリ レイアウトおよび追加パターン（プロジェクト タイプ別の条件付き設定、pack 後検証）については common-patterns を参照してください。

ワークフロー: ビルド インフラストラクチャの構成

1. すべての .csproj ファイルを監査 — ソリューション全体の <PropertyGroup>、<ItemGroup>、カスタム <Target> をカタログ化します。どの設定が繰り返されているか、どの設定がプロジェクト固有かをメモします。
2. ルート Directory.Build.props を作成 — 共有プロパティのデフォルト値（LangVersion、Nullable、TreatWarningsAsErrors、メタデータ）をここに移動します。これらはプロジェクト ファイルの前にインポートされるため、プロジェクトはそれらをオーバーライドできます。
3. ルート Directory.Build.targets を作成 — カスタム ビルド ターゲット、ビルド後検証、および SDK定義値に依存するプロパティ（例えば OutputPath、シングル ターゲット プロジェクトの TargetFramework）をここに移動します。これらは SDK の後でインポートされるため、すべてのプロパティが利用可能です。
4. Directory.Packages.props を作成 — Central Package Management を有効にし（ManagePackageVersionsCentrally）、すべての PackageVersion エントリをリストし、.csproj ファイルの PackageReference アイテムから Version= を削除します。
5. マルチレベル階層をセットアップ — src/ および test/ フォルダ用に内側の Directory.Build.props ファイルを作成し、異なる設定を指定します。GetPathOfFileAbove を使用して親へチェーンします。
6. .csproj ファイルを簡素化 — すべての一元化されたプロパティ、バージョン属性、および重複したターゲットを削除します。各プロジェクトはそれに固有の内容のみを含むべきです。
7. 検証 — dotnet restore && dotnet build を実行し、回帰がないことを確認します。必要に応じて dotnet msbuild -pp:output.xml を使用して最終的なマージされたビューを検査します。

トラブルシューティング

問題	原因	解決方法
Directory.Build.props が選択されない	ファイル名の大文字小文字が間違っている（Linux/macOS では正確なマッチが必要）	正確な大文字小文字を確認: Directory.Build.props（大文字の D、B）
.props のプロパティがプロジェクトに無視される	プロジェクトがインポート後に同じプロパティを設定している	プロパティを Directory.Build.targets に移動してプロジェクト後に設定
マルチレベル インポートが機能しない	内側のファイルに GetPathOfFileAbove インポートがない	内側のファイルの先頭に <Import> 要素を追加（マルチレベル セクションを参照）
SDK値を使用するプロパティが .props で空	SDK プロパティが .props 評価中にまだ定義されていない	.targets に移動（SDK の後でインポートされます）
Directory.Packages.props が見つからない	ファイルがリポジトリ ルートにないか、名前が正確でない	Directory.Packages.props という名前で、プロジェクト ディレクトリ以上に配置してください
.props の $(TargetFramework) のプロパティ条件が一致しない	シングル ターゲット プロジェクトの場合、.props 評価中に TargetFramework が設定されていない	プロパティを .targets に移動するか、ItemGroup/Target 条件を代わりに使用（これらは後期に評価）

診断: 前処理されたプロジェクト出力を使用してすべてのインポートと最終プロパティ値を確認します:

dotnet msbuild -pp:output.xml MyProject.csproj

これはすべてのインポートをインラインで展開し、各プロパティが設定されている場所と最終的な評価値を正確に確認できます。