dotnet-artifacts-output

dotnet-artifacts-output

.NET SDK のアーティファクト出力レイアウトに関するリファレンスガイドです。ビルド出力（bin/、obj/、publish/、package/）をリポジトリルートの単一の artifacts/ ディレクトリに集約します。.NET 8 以降でオプトイン機能として利用できます。新しいプロジェクトでは推奨されます。既存のプロジェクトを移行する場合は、トレードオフを検討してください。

前提条件： 先に [skill:dotnet-version-detection] を実行して、.NET 8 以降の SDK であることを確認してください。アーティファクト出力レイアウトは、それ以前の SDK バージョンでは利用できません。

対象範囲： [skill:dotnet-project-structure] ではソースツリーの構成（.sln、.csproj、src/、tests/）を扱います。このスキルではビルド出力の構成（artifacts/bin/、artifacts/obj/、artifacts/publish/）を扱います。ソースツリーと出力ツリーの違いです。

相互参照：ソリューションのレイアウトについては [skill:dotnet-project-structure]、Dockerfile のパス調整については [skill:dotnet-containers]、CI アーティファクトのアップロードパスについては [skill:dotnet-gha-build-test]、アーティファクト出力を有効にした新しいプロジェクトの生成については [skill:dotnet-scaffold-project] を参照してください。

---

アーティファクト出力を使用する理由

従来の .NET ビルド出力では、ソースツリー内の各プロジェクトに bin/ と obj/ ディレクトリが分散して作成されます。アーティファクト出力レイアウトでは、すべてのビルド出力を Directory.Build.props と同じ階層にある単一の artifacts/ ディレクトリに集約します。

メリット：

• .gitignore の簡素化 -- プロジェクトごとに必要だった bin/ と obj/ のエントリを、1つの artifacts/ エントリに置き換えられます
• クリーンビルドの簡素化 -- 分散した bin/／obj/ フォルダーを探す代わりに、1つのディレクトリを削除できます
• 予測可能な出力パス -- ツールはソースツリーをたどらずに、ビルド出力の場所を予測できます
• ソースツリーの整理 -- プロジェクトディレクトリにビルドアーティファクトが混在しません

トレードオフ：

• パスの前提が崩れる -- bin/Debug/net10.0/ のようなパスを参照する既存の CI パイプライン、Dockerfile、ツールを更新する必要があります
• IDE／ツールとの互換性 -- 古いツールの中には、新しい出力パスを正しく解決できないものがあります
• 移行の手間 -- 既存のプロジェクトでは、ハードコードされた出力パスの参照をすべて更新する必要があります

---

アーティファクト出力を有効にする

リポジトリルートの Directory.Build.props に UseArtifactsOutput を追加します。

<Project>
  <PropertyGroup>
    <UseArtifactsOutput>true</UseArtifactsOutput>
  </PropertyGroup>
</Project>

または、アーティファクト出力をあらかじめ設定した新しい Directory.Build.props を生成します。

dotnet new buildprops --use-artifacts

これにより、次のファイルが作成されます。

<Project>
  <PropertyGroup>
    <ArtifactsPath>$(MSBuildThisFileDirectory)artifacts</ArtifactsPath>
  </PropertyGroup>
</Project>

ArtifactsPath を直接設定することは UseArtifactsOutput=true と同等であり、さらにルートディレクトリの場所をカスタマイズできます。

---

出力パスの構造

すべてのビルド出力は artifacts/ 配下に、出力タイプ、プロジェクト名、ピボット（構成／TFM／RID）の3階層で整理されます。

artifacts/
  bin/
    MyApp/
      debug/                          # Single-targeted project
      debug_net10.0/                  # Multi-targeted project
      release_linux-x64/              # RID-specific build
    MyApp.Core/
      debug/
  obj/
    MyApp/
      debug/
  publish/
    MyApp/
      release/                        # dotnet publish output
      release_linux-x64/              # RID-specific publish
  package/
    release/                          # NuGet .nupkg files (no project subfolder)

出力タイプのディレクトリ

ディレクトリ	内容	従来の対応先
artifacts/bin/	コンパイル済みアセンブリと依存関係	<project>/bin/
artifacts/obj/	中間ビルドファイル、生成されたコード	<project>/obj/
artifacts/publish/	発行されたアプリケーションの出力	<project>/bin/<config>/<tfm>/publish/
artifacts/package/	NuGet パッケージ（.nupkg、.snupkg）	<project>/bin/<config>/

ピボットの命名

ピボットのサブフォルダー名は、構成、TFM、RID をアンダースコアで連結したものです。存在しない要素は省略されます。

シナリオ	ピボット	フルパスの例
単一ターゲット、デバッグ	debug	artifacts/bin/MyApp/debug/
マルチターゲット、デバッグ	debug_net10.0	artifacts/bin/MyApp/debug_net10.0/
リリース、RID 指定	release_linux-x64	artifacts/bin/MyApp/release_linux-x64/
パッケージ出力	release	artifacts/package/release/

注：artifacts/package/ ではプロジェクト名のサブフォルダーが省略されます。ピボットに含まれるのは構成のみです。

---

アーティファクトのパスをカスタマイズする

カスタムルートディレクトリ

ArtifactsPath を設定して、ルートの場所を変更します。

<PropertyGroup>
  <ArtifactsPath>$(MSBuildThisFileDirectory).output</ArtifactsPath>
</PropertyGroup>

すべてのビルド出力は artifacts/ ではなく .output/ 配下に配置されます。

カスタムピボット

ArtifactsPivots を使用して、ピボットのサブフォルダー名をカスタマイズします。

<PropertyGroup>
  <ArtifactsPivots>$(ArtifactsPivots)_MyCustomPivot</ArtifactsPivots>
</PropertyGroup>

---

.gitignore への影響

アーティファクト出力を有効にした場合は、.gitignore を簡素化できます。

# Artifacts output layout (replaces per-project bin/ and obj/ entries)
artifacts/

このエントリ 1 つで、従来のパターンを置き換えられます。

# Traditional layout (no longer needed with artifacts output)
[Bb]in/
[Oo]bj/

カスタムの ArtifactsPath を使用する場合は、一致するように .gitignore のエントリを更新してください。

---

Dockerfile への影響

ビルド出力をコピーするマルチステージ Dockerfile では、新しいパス構造を参照する必要があります。Dockerfile のパターンについて詳しくは、[skill:dotnet-containers] を参照してください。

従来のパス：

COPY --from=build /app/src/MyApp/bin/Release/net10.0/publish/ .

アーティファクト出力のパス：

COPY --from=build /app/artifacts/publish/MyApp/release/ .

Dockerfile のパスにおける主な違い：

• 出力先は bin/Release/<tfm>/publish/ ではなく artifacts/publish/ の下になります
• プロジェクト名は出力の種類の下にサブディレクトリとして配置されます
• 構成ピボットは小文字です（Release ではなく release）
• ターゲットが 1 つのプロジェクトでは、TFM はピボットに含まれません

---

CI パイプラインへの影響

ビルドアーティファクトをアップロードする CI ワークフローや、出力パスを参照する CI ワークフローは更新が必要です。CI ワークフローのパターンについて詳しくは、[skill:dotnet-gha-build-test] を参照してください。

GitHub Actions — ビルド出力のアップロード：

- name: Publish
  run: dotnet publish src/MyApp/MyApp.csproj -c Release

- name: Upload artifact
  uses: actions/upload-artifact@v4
  with:
    name: app
    path: artifacts/publish/MyApp/release/

GitHub Actions — NuGet パッケージのアップロード：

- name: Pack
  run: dotnet pack -c Release

- name: Upload packages
  uses: actions/upload-artifact@v4
  with:
    name: packages
    path: artifacts/package/release/*.nupkg

Azure DevOps — アーティファクトの発行：

- script: dotnet publish src/MyApp/MyApp.csproj -c Release
  displayName: 'Publish'

- task: PublishPipelineArtifact@1
  inputs:
    targetPath: 'artifacts/publish/MyApp/release/'
    artifact: 'app'

---

移行チェックリスト

既存のプロジェクトでアーティファクト出力を有効にする場合：

1. Directory.Build.props に UseArtifactsOutput を追加する
2. .gitignore を更新する — [Bb]in/ と [Oo]bj/ を artifacts/ に置き換える
3. Dockerfile を更新する — すべての COPY --from=build パスを artifacts/ 構造に変更する
4. CI パイプラインを更新する — アーティファクトのアップロードパス、テスト結果のパス、発行パスを修正する
5. ローカルスクリプトを更新する — bin/ または obj/ のパスを参照するシェルスクリプトを修正する
6. 古い出力をクリーンアップする — すべてのプロジェクトから既存の bin/ と obj/ ディレクトリを削除する
7. ビルドを検証する — dotnet build と dotnet publish を実行し、出力が artifacts/ の下に生成されることを確認する
8. テストを検証する — dotnet test を実行し、新しいパスでテストが実行されることを確認する

---

エージェントが注意すべき点

1. ターゲットが 1 つのプロジェクトでは、アーティファクト出力パスに TFM をハードコードしないでください。 ターゲットが 1 つのプロジェクトのピボットは構成（例：debug）のみで、debug_net10.0 ではありません。複数のターゲットを持つプロジェクトでは、ピボットに TFM が含まれます。
2. アーティファクトパスに大文字の構成名を使用しないでください。 アーティファクトのレイアウトでは小文字のピボット（debug、release）を使用し、従来の大文字表記（Debug、Release）は使用しません。
3. artifacts/package/ にプロジェクト名のサブフォルダーがあると想定しないでください。 bin/、obj/、publish/ とは異なり、package/ の出力の種類ではプロジェクト名の階層が省略されます。パッケージは artifacts/package/<config>/ の直下に配置されます。
4. Dockerfile と CI パイプラインを先に更新せずに、アーティファクト出力を有効にしないでください。 パスが変わると、従来の bin/ パスを参照する COPY --from=build ディレクティブやアーティファクトのアップロード手順が動作しなくなります。
5. アーティファクト出力を .NET の既定のレイアウトとして紹介しないでください。 .NET 8 以降、オプトイン方式のままです。新しいプロジェクトには推奨してください。既存のプロジェクトでは、移行の労力とメリットを比較検討してください。

---

参考資料

• アーティファクト出力のレイアウト
• ビルドのカスタマイズ（Directory.Build.props）
• dotnet new buildprops