.NET SDK プロジェクトの MSBuild リファレンス

このページは、.NET プロジェクトの構成に使用できる、MSBuild のプロパティと項目のリファレンスです。

注意

このページの編集は進行中であり、.NET SDK の便利な MSBuild プロパティがすべて記載されている訳ではありません。 一般的な MSBuild プロパティの一覧については、「MSBuild プロジェクトの共通プロパティ」を参照してください。

フレームワークのプロパティ

このセクションでは、次の MSBuild プロパティについて説明します。

TargetFramework

TargetFramework プロパティには、アプリのターゲット フレームワーク バージョンを指定します。 有効なターゲット フレームワーク モニカーの一覧については、「SDK スタイルのプロジェクトでのターゲット フレームワーク」を参照してください。

<PropertyGroup>
  <TargetFramework>netcoreapp3.1</TargetFramework>
</PropertyGroup>

詳細については、「SDK スタイルのプロジェクトでのターゲット フレームワーク」を参照してください。

TargetFrameworks

アプリで複数のプラットフォームをターゲットにする場合は、TargetFrameworks プロパティを使用します。 有効なターゲット フレームワーク モニカーの一覧については、「SDK スタイルのプロジェクトでのターゲット フレームワーク」を参照してください。

注意

TargetFramework (単数形) が指定されている場合、このプロパティは無視されます。

<PropertyGroup>
  <TargetFrameworks>netcoreapp3.1;net462</TargetFrameworks>
</PropertyGroup>

詳細については、「SDK スタイルのプロジェクトでのターゲット フレームワーク」を参照してください。

NetStandardImplicitPackageVersion

注意

このプロパティは、netstandard1.x を使用するプロジェクトにのみ適用されます。 netstandard2.x を使用するプロジェクトには適用されません。

メタパッケージ バージョンよりも低いフレームワーク バージョンを指定する場合は、NetStandardImplicitPackageVersion プロパティを使用します。 次の例のプロジェクト ファイルは、netstandard1.3 をターゲットにしていますが、NETStandard.Library の 1.6.0 バージョンを使用しています。

<PropertyGroup>
  <TargetFramework>netstandard1.3</TargetFramework>
  <NetStandardImplicitPackageVersion>1.6.0</NetStandardImplicitPackageVersion>
</PropertyGroup>

アセンブリの属性プロパティ

GenerateAssemblyInfo

GenerateAssemblyInfo プロパティによってプロジェクトの AssemblyInfo 属性の生成を制御できます。 既定値は true です。 ファイルの生成を無効にするには、false を使用します。

<PropertyGroup>
  <GenerateAssemblyInfo>false</GenerateAssemblyInfo>
</PropertyGroup>

GeneratedAssemblyInfoFile 設定は、生成されるファイルの名前を制御します。

GenerateAssemblyInfo 値が true の場合、パッケージ関連のプロジェクト プロパティがアセンブリ属性に変換されます。 属性を生成するプロジェクト プロパティの一覧を次の表に示します。 また、次のように、属性ごとにその生成を無効にするために使用できるプロパティの一覧も示しています。

<PropertyGroup>
  <GenerateNeutralResourcesLanguageAttribute>false</GenerateNeutralResourcesLanguageAttribute>
</PropertyGroup>
MSBuild のプロパティ Assembly 属性 属性の生成を無効にするプロパティ
Company AssemblyCompanyAttribute GenerateAssemblyCompanyAttribute
Configuration AssemblyConfigurationAttribute GenerateAssemblyConfigurationAttribute
Copyright AssemblyCopyrightAttribute GenerateAssemblyCopyrightAttribute
Description AssemblyDescriptionAttribute GenerateAssemblyDescriptionAttribute
FileVersion AssemblyFileVersionAttribute GenerateAssemblyFileVersionAttribute
InformationalVersion AssemblyInformationalVersionAttribute GenerateAssemblyInformationalVersionAttribute
Product AssemblyProductAttribute GenerateAssemblyProductAttribute
AssemblyTitle AssemblyTitleAttribute GenerateAssemblyTitleAttribute
AssemblyVersion AssemblyVersionAttribute GenerateAssemblyVersionAttribute
NeutralLanguage NeutralResourcesLanguageAttribute GenerateNeutralResourcesLanguageAttribute

これらの設定に関する注意事項:

  • AssemblyVersionFileVersion の既定値は、サフィックスのない $(Version) の値です。 たとえば、$(Version)1.2.3-beta.4 の場合、値は 1.2.3 です。
  • InformationalVersion の既定値は、$(Version) の値です。
  • $(SourceRevisionId) プロパティが存在する場合は、それが InformationalVersion の後に追加されます。 IncludeSourceRevisionInInformationalVersion を使用して、この動作を無効にすることができます。
  • NuGet メタデータには、Copyright および Description プロパティも使用されます。
  • Configuration (既定値は Debug) は、すべての MSBuild ターゲットと共有されます。 これは、dotnet コマンド (dotnet pack など) の --configuration オプションを使用して設定できます。
  • 一部のプロパティは、NuGet パッケージを作成するときに使用されます。 詳細については、「パッケージのプロパティ」を参照してください。

.NET Framework からの移行

.NET Framework プロジェクト テンプレートでは、これらのアセンブリ情報属性を設定したコード ファイルを作成します。 通常、このファイルは .\Properties\AssemblyInfo.cs または .\Properties\AssemblyInfo.vb にあります。 SDK スタイルのプロジェクトでは、プロジェクトの設定に基づいてこのファイルが生成されます。 両方を持つことはできません。 コードを .NET 5 (または .NET Core 3.1) 以降に移植する場合は、次のいずれかの操作を行います。

  • プロジェクト ファイルで GenerateAssemblyInfofalse に設定することにより、アセンブリ情報属性を含む一時コード ファイルの生成を無効にします。 これにより、AssemblyInfo ファイルを保持することができます。
  • AssemblyInfo ファイルの設定をプロジェクト ファイルに移行した後、AssemblyInfo ファイルを削除します。

GeneratedAssemblyInfoFile

GeneratedAssemblyInfoFile プロパティによって、生成されるアセンブリ情報ファイルの相対パスまたは絶対パスを定義します。 既定値は、$(IntermediateOutputPath) (通常は obj) ディレクトリ内の [プロジェクト名].AssemblyInfo.[cs|vb] という名前のファイルです。

<PropertyGroup>
  <GeneratedAssemblyInfoFile>assemblyinfo.cs</GeneratedAssemblyInfoFile>
</PropertyGroup>

パッケージのプロパティ

説明プロパティ

PackageIdPackageVersionPackageIconTitleDescription などのプロパティを指定し、プロジェクトから作成されたパッケージについて説明できます。 以上のプロパティとその他のプロパティの詳細については、「pack ターゲット」を参照してください。

<PropertyGroup>
  ...
  <PackageId>ClassLibDotNetStandard</PackageId>
  <Version>1.0.0</Version>
  <Authors>John Doe</Authors>
  <Company>Contoso</Company>
</PropertyGroup>

PackRelease

この PackRelease プロパティは PublishRelease プロパティに似ていますが、既定の dotnet pack 動作が変更される点が異なります。

<PropertyGroup>
  <PackRelease>true</PackRelease>
</PropertyGroup>

注意

PackRelease を Visual Studio ソリューションの一部であるプロジェクトで使用するには、環境変数 DOTNET_CLI_ENABLE_PACK_RELEASE_FOR_SOLUTIONStrue (またはその他の値) に設定する必要があります。 この変数を設定すると、多くのプロジェクトを含むソリューションをパックするために必要な時間が長くなります。

このセクションでは、次の MSBuild プロパティについて説明します。

AppendTargetFrameworkToOutputPath

AppendTargetFrameworkToOutputPath プロパティは、ターゲット フレームワーク モニカー (TFM) を出力パス (OutputPath で定義されている) に追加するかどうかを制御します。 .NET SDK はターゲット フレームワークを、それが存在する場合にはランタイム識別子を出力パスに自動的に追加します。 AppendTargetFrameworkToOutputPathfalse に設定すると、TFM が出力パスに追加されなくなります。 ただし、出力パスに TFM がないと、複数のビルド成果物が相互に上書きされる可能性があります。

たとえば、.NET 5 アプリの場合、出力パスは次の設定を使用して bin\Debug\net5.0 から bin\Debug に変更されます。

<PropertyGroup>
  <AppendTargetFrameworkToOutputPath>false</AppendTargetFrameworkToOutputPath>
</PropertyGroup>

AppendRuntimeIdentifierToOutputPath

AppendRuntimeIdentifierToOutputPath プロパティは、ランタイム識別子 (RID) を出力パスに追加するかどうかを制御します。 .NET SDK はターゲット フレームワークを、それが存在する場合にはランタイム識別子を出力パスに自動的に追加します。 AppendRuntimeIdentifierToOutputPathfalse に設定すると、RID が出力パスに追加されなくなります。

たとえば、.NET 5 アプリで RID が win10-x64 の場合、出力パスは次の設定を使用して bin\Debug\net5.0\win10-x64 から bin\Debug\net5.0 に変更されます。

<PropertyGroup>
  <AppendRuntimeIdentifierToOutputPath>false</AppendRuntimeIdentifierToOutputPath>
</PropertyGroup>

CopyLocalLockFileAssemblies

CopyLocalLockFileAssemblies プロパティは、他のライブラリに依存しているプラグイン プロジェクトにとって便利です。 このプロパティを true に設定すると、NuGet パッケージの依存関係が出力ディレクトリにコピーされます。 つまり、dotnet build の出力を使用し、任意のコンピューターでプラグインを実行できます。

<PropertyGroup>
  <CopyLocalLockFileAssemblies>true</CopyLocalLockFileAssemblies>
</PropertyGroup>

ヒント

あるいは、dotnet publish を使用し、クラス ライブラリを発行できます。 詳細については、「dotnet publish」を参照してください。

ErrorOnDuplicatePublishOutputFiles

ErrorOnDuplicatePublishOutputFiles プロパティは、MSBuild によって発行出力のファイル重複が検出されるが、削除するべきファイルを判断できないとき、SDK によってエラー NETSDK1148 が生成されるかどうかに関係します。 エラーを生成しない場合、ErrorOnDuplicatePublishOutputFiles プロパティを false に設定します。

<PropertyGroup>
  <ErrorOnDuplicatePublishOutputFiles>false</ErrorOnDuplicatePublishOutputFiles>
</PropertyGroup>

このプロパティは .NET 6 で導入されました。

EnablePackageValidation

EnablePackageValidation プロパティを使用すると、pack タスクの後にパッケージの一連の検証が有効になります。 詳細については、パッケージの検証に関する記事を参照してください。

<PropertyGroup>
  <EnablePackageValidation>true</EnablePackageValidation>
</PropertyGroup>

このプロパティは .NET 6 で導入されました。

GenerateRuntimeConfigDevFile

.NET 6 SDK 以降、コンパイル時に [Appname].runtimesettings.dev.json ファイルは既定で生成されなくなりました。 このファイルを生成させる場合、GenerateRuntimeConfigDevFile プロパティを true に設定してください。

<PropertyGroup>
  <GenerateRuntimeConfigDevFile>true</GenerateRuntimeConfigDevFile>
</PropertyGroup>

GenerateRuntimeConfigurationFiles

GenerateRuntimeConfigurationFiles プロパティによって、ランタイム構成オプションを runtimeconfig.template.json ファイルから [appname].runtimeconfig.json ファイルにコピーするかどうかを制御します。 runtimeconfig.json ファイルが必要なアプリの場合 (つまり、その OutputTypeExe である場合)、このプロパティの既定値は true です。

<PropertyGroup>
  <GenerateRuntimeConfigurationFiles>true</GenerateRuntimeConfigurationFiles>
</PropertyGroup>

GenerateSatelliteAssembliesForCore

GenerateSatelliteAssembliesForCore プロパティは、.NET Framework プロジェクトでサテライト アセンブリが csc.exe または Al.exe (アセンブリ リンカー) のどちらを使って生成されるかを制御します。 (.NET Core および .NET 5 以降のプロジェクトでは、サテライト アセンブリは常に csc.exe を使って生成されます)。.NET Framework プロジェクトの場合、サテライト アセンブリは既定では al.exe によって作成されます。 GenerateSatelliteAssembliesForCore プロパティを true に設定すると、代わりに csc.exe によってサテライト アセンブリが作成されます。 csc.exe を使うと、次の状況で有利になる場合があります。

<PropertyGroup>
  <GenerateSatelliteAssembliesForCore>true</GenerateSatelliteAssembliesForCore>
</PropertyGroup>

IsPublishable

IsPublishable プロパティを使用すると、Publish ターゲットを実行できます。 このプロパティは、.*proj ファイルと Publish ターゲット (dotnet publish コマンドなど) を使用するプロセスにのみ影響します。 これは PublishOnly ターゲットを使用する Visual Studio での発行には影響しません。 既定値は true です。

このプロパティを使用すると、発行する必要があるプロジェクトを自動的に選択できるようになるため、ソリューション ファイルで dotnet publish を実行する場合に便利です。

<PropertyGroup>
  <IsPublishable>false</IsPublishable>
</PropertyGroup>

PreserveCompilationContext

PreserveCompilationContext プロパティを使うと、ビルド時に使用されたのと同じ設定で、ビルドまたは発行されたアプリケーションで実行時により多くのコードをコンパイルできるようになります。 ビルド時に参照されるアセンブリは、出力ディレクトリの ref サブディレクトリにコピーされます。 参照アセンブリの名前は、コンパイラに渡されるオプションと共に、アプリケーションの .deps.json ファイルに格納されます。 この情報は、DependencyContext.CompileLibrariesDependencyContext.CompilationOptions のプロパティを使用して取得できます。

この機能は、ほとんどの場合、Razor ファイルの実行時コンパイルをサポートするために ASP.NET Core MVC と Razor Pages によって内部的に使用されます。

<PropertyGroup>
  <PreserveCompilationContext>true</PreserveCompilationContext>
</PropertyGroup>

PreserveCompilationReferences

PreserveCompilationReferences プロパティは PreserveCompilationContext プロパティと似ていますが、 .deps.json ファイルではなく、発行ディレクトリに参照アセンブリのみがコピーされる点が異なります。

<PropertyGroup>
  <PreserveCompilationReferences>true</PreserveCompilationReferences>
</PropertyGroup>

詳細については、「Razor SDK」の「プロパティ」を参照してください。

ProduceReferenceAssemblyInOutDir

.NET 5 以前のバージョンでは、参照アセンブリは常に OutDir ディレクトリに書き込まれます。 .NET 6 以降のバージョンでは、 ProduceReferenceAssemblyInOutDir プロパティを使用して、参照アセンブリを OutDir ディレクトリに書き込むかどうかを制御できます。 既定値は false で、参照アセンブリは IntermediateOutputPath ディレクトリにのみ書き込まれます。 参照アセンブリを OutDir ディレクトリに書き込むには、値を true に設定します。

<PropertyGroup>
  <ProduceReferenceAssemblyInOutDir>true</ProduceReferenceAssemblyInOutDir>
</PropertyGroup>

詳細については、「中間出力への参照アセンブリの書き込み」を参照してください。

PublishDocumentationFile

このプロパティが true の場合、プロジェクトの XML ドキュメント ファイルが (生成されていれば)、プロジェクトの発行出力に含まれます。 このプロパティでは、既定値が true に設定されます。

ヒント

コンパイル時に XML ドキュメント ファイルを生成するには、GenerateDocumentationFiletrue に設定します。

PublishDocumentationFiles

このプロパティは、さまざまな種類の XML ドキュメント ファイル (つまり PublishDocumentationFilePublishReferencesDocumentationFiles) を既定で発行ディレクトリにコピーするかどうかを制御する他のいくつかのプロパティ用の有効化フラグです。 これらのプロパティが未設定で、このプロパティを設定すると、これらのプロパティは既定で true になります。 このプロパティでは、既定値が true に設定されます。

PublishReferencesDocumentationFiles

このプロパティが true の場合、プロジェクトの参照用の XML ドキュメント ファイルが発行ディレクトリにコピーされます (DLL ファイルなどの単なる実行時アセットではなく)。 このプロパティでは、既定値が true に設定されます。

PublishRelease

この PublishRelease プロパティは、既定で Debug 構成の代わりに Release 構成を使用するように dotnet publish に通知します。

<PropertyGroup>
  <PublishRelease>true</PublishRelease>
</PropertyGroup>

注意

  • このプロパティは dotnet build /t:Publish の動作には影響せず、.NET CLI 経由で発行する場合にのみ構成を変更します。
  • PublishRelease を Visual Studio ソリューションの一部であるプロジェクトで使用するには、環境変数 DOTNET_CLI_ENABLE_PUBLISH_RELEASE_FOR_SOLUTIONStrue (またはその他の値) に設定する必要があります。 これにより、多くのプロジェクトを含むソリューションを発行するために必要な時間が長くなります。 この変数を有効にしてソリューションを発行する場合、実行可能プロジェクトの PublishRelease 値が優先され、ソリューション内の他のプロジェクトに新しい既定の構成がフローされます。 ソリューションに複数の実行可能ファイルまたは最上位レベルのプロジェクトの異なる PublishRelease の値が含まれている場合、ソリューションは正常に発行されません。

RollForward

RollForward プロパティによって、複数のランタイム バージョンが利用できるときのアプリケーションによるランタイム選択方法が制御されます。 この値は .runtimeconfig.jsonrollForward 設定として出力されます。

<PropertyGroup>
  <RollForward>LatestMinor</RollForward>
</PropertyGroup>

RollForward には、次のいずれかの値を選択します。

説明
Minor 指定されない場合は既定値
要求されたマイナー バージョンが見つからない場合は、それよりも高い最小マイナー バージョンにロール フォワードします。 要求されたマイナー バージョンが存在する場合は、LatestPatch ポリシーが使用されます。
Major 要求されたメジャー バージョンが見つからない場合は、次に利用できる中でそれよりも高いメジャー バージョンかつ最小マイナー バージョンにロール フォワードします。 要求されたメジャー バージョンが存在する場合は、Minor ポリシーが使用されます。
LatestPatch 最新のパッチ バージョンにロール フォワードします。 この値によって、マイナー バージョンのロールフォワードが無効になります。
LatestMinor 要求されたマイナー バージョンが存在する場合でも、最上位のマイナー バージョンにロール フォワードします。
LatestMajor 要求されたメジャーが存在する場合でも、最上位のメジャー バージョンで最上位のマイナー バージョンにロール フォワードします。
Disable ロールフォワードせず、指定されたバージョンにバインドされるだけです。 このポリシーは、最新のパッチにロールフォワードする機能が無効になるため、一般的な使用にはお勧めできません。 この値はテスト用にのみ推奨されます。

詳細については、ロールフォワード動作の制御に関するページを参照してください。

RuntimeFrameworkVersion

RuntimeFrameworkVersion プロパティによって、発行時に使用するランタイムのバージョンが指定されます。 ランタイム バージョンを指定する:

<PropertyGroup>
  <RuntimeFrameworkVersion>5.0.7</RuntimeFrameworkVersion>
</PropertyGroup>

フレームワーク依存のアプリケーションを発行するとき、この値によって、必須の "最小" バージョンが指定されます。 自己完結型のアプリケーションを発行するとき、この値によって、必須となる "厳密な" バージョンが指定されます。

RuntimeIdentifier

RuntimeIdentifier プロパティを使用すると、プロジェクトに 1 つのランタイム識別子 (RID) を指定できます。 RID により、自己完結型の展開を発行できます。

<PropertyGroup>
  <RuntimeIdentifier>ubuntu.16.04-x64</RuntimeIdentifier>
</PropertyGroup>

RuntimeIdentifiers

RuntimeIdentifiers プロパティには、プロジェクトのランタイム識別子 (RID) のセミコロン区切りリストを指定できます。 複数のランタイムに発行する必要がある場合は、このプロパティを使用します。 RuntimeIdentifiers は、復元時に適切な資産をグラフに確実に含めるために使用されます。

ヒント

RuntimeIdentifier (単数形) を使用すると、必要なランタイムが 1 つだけのとき、ビルドが速くなります。

<PropertyGroup>
  <RuntimeIdentifiers>win10-x64;osx.10.11-x64;ubuntu.16.04-x64</RuntimeIdentifiers>
</PropertyGroup>

SatelliteResourceLanguages

SatelliteResourceLanguages プロパティを使用すると、ビルドおよび発行時にサテライト リソース アセンブリを保持する言語を指定できます。 多くの NuGet パッケージには、そのメイン パッケージにローカライズされたリソース サテライト アセンブリが含まれています。 ローカライズされたリソースを必要としない NuGet パッケージを参照するプロジェクトの場合、ローカライズされたアセンブリによってビルドと発行の出力サイズが不必要に大きくなる可能性があります。 プロジェクト ファイルに SatelliteResourceLanguages プロパティを追加することで、指定した言語のローカライズされたアセンブリだけがビルドと発行の出力に含まれます。 たとえば、次のプロジェクト ファイルでは、英語 (米国) とドイツ語 (ドイツ) のリソース サテライト アセンブリだけが保持されます。

<PropertyGroup>
  <SatelliteResourceLanguages>en-US;de-DE</SatelliteResourceLanguages>
</PropertyGroup>

注意

  • このプロパティは、ローカライズされたリソース サテライト アセンブリを含む NuGet を参照するプロジェクトで指定する必要があります。

  • 引数 dotnet publish として複数の言語を指定するには、言語識別子を囲む引用符の "ペアを 3 つ" 追加する必要があります。 次に例を示します。

    dotnet msbuild multi.msbuildproj -p:SatelliteResourceLanguages="""de;en"""

UseAppHost

UseAppHost プロパティにより、デプロイ用にネイティブ実行可能ファイルを作成するかどうかが制御されます。 自己完結型の配置にはネイティブの実行可能ファイルが必要です。

.NET Core 3.0 以降のバージョンでは、既定でフレームワークに依存する実行可能ファイルが作成されます。 実行可能ファイルの生成を無効にするには、UseAppHost プロパティを false に設定します。

<PropertyGroup>
  <UseAppHost>false</UseAppHost>
</PropertyGroup>

配置の詳細については、.NET アプリケーションの配置に関するページを参照してください。

さまざまな MSBuild プロパティをトリミングの微調整に使用できます。これは、自己完結型の展開から未使用のコードをトリミングする機能です。 これらのオプションの詳細については、「トリミングのオプション」を参照してください。 次の表に、クイック リファレンスを示します。

プロパティ 説明
PublishTrimmed true または false 公開中にトリミングを有効にするかどうかを制御します。
TrimMode full または partial 既定値は full です。 トリミングの粒度を制御します。
SuppressTrimAnalysisWarnings true または false トリミング分析の警告を生成するかどうかを制御します。
EnableTrimAnalyzer true または false トリミング分析の警告のサブセットを生成するかどうかを制御します。 PublishTrimmedfalse に設定されている場合でも、分析を有効にすることができます。
ILLinkTreatWarningsAsErrors true または false トリミングの警告をエラーとして扱うかどうかを制御します。 たとえば、TreatWarningsAsErrorstrue に設定されている場合は、このプロパティを false に設定することができます。
TrimmerSingleWarn true または false アセンブリごとに 1 つの警告を表示するか、すべての警告を表示するかを制御します。
TrimmerRemoveSymbols true または false トリミングされたアプリケーションからすべてのシンボルを削除するかどうかを制御します。

このセクションでは、次の MSBuild プロパティについて説明します。

LangVersionNullable などの C# コンパイラ オプションは、プロジェクト ファイルの MSBuild プロパティとして指定することもできます。 詳細については、「C# コンパイラ オプション」を参照してください。

CopyDebugSymbolFilesFromPackages

このプロパティを true に設定すると、プロジェクト内の PackageReference 項目のすべてのシンボル ファイル (PDB ファイルとも呼ばれる) がビルド出力にコピーされます。 これらのファイルは、例外に関するより有益な情報を含むスタック トレースを提供し、実行中のアプリケーションのメモリ ダンプとトレースを理解しやすくします。 ただし、これらのファイルを含めると、デプロイ バンドルのサイズが大きくなります。

このプロパティは .NET SDK 7.0.100 で導入されましたが、既定値は指定されていません。

CopyDocumentationFilesFromPackages

このプロパティを true に設定すると、プロジェクト内の PackageReference 項目のすべての生成された XML ドキュメント ファイルがビルド出力にコピーされます。 この機能を有効にすると、デプロイ バンドルのサイズが大きくなることに注意してください。

このプロパティは .NET SDK 7.0.100 で導入されましたが、既定値は指定されていません。

DisableImplicitFrameworkDefines

DisableImplicitFrameworkDefines プロパティによって、.NET プロジェクトのターゲット フレームワークとプラットフォーム用のプリプロセッサ シンボルを SDK が生成するかどうかが、コントロールされます。 このプロパティは false に設定されているか、設定されていない (既定値) ときは、次のプリプロセッサ シンボルが生成されます。

  • バージョンのないフレームワーク (NETFRAMEWORKNETSTANDARDNET)
  • バージョンのあるフレームワーク (NET48NETSTANDARD2_0NET6_0)
  • バージョンが最小バインドのフレームワーク (NET48_OR_GREATERNETSTANDARD2_0_OR_GREATERNET6_0_OR_GREATER)

ターゲット フレームワーク モニカーとそれらのプリプロセッサ シンボルの詳細については、ターゲット フレームワークに関するページを参照してください。

また、プロジェクトでオペレーティング システム固有のターゲット フレームワーク (たとえば net6.0-android) を指定する場合、次のプリプロセッサ シンボルが生成されます。

  • バージョンのないプラットフォーム (ANDROIDIOSWINDOWS)
  • バージョンのあるプラットフォーム (IOS15_1)
  • バージョンが最小バインドのプラットフォーム (IOS15_1_OR_GREATER)

オペレーティング システム固有のターゲット フレームワーク モニカーの詳細については、OS 固有の TFM に関するセクションを参照してください。

最後に、ターゲット フレームワークが前のターゲット フレームワークのサポートを意味する場合は、それらの前のフレームワークのプリプロセッサ シンボルが生成されます。 たとえば、net6.0net5.0 から .netcoreapp1.0 まで対象にするサポートを意味します。 そのため、これらの各ターゲット フレームワークについて "バージョンが最小限にバインドされているフレームワーク" のシンボルが定義されます。

DocumentationFile

DocumentationFile プロパティを使用すると、そのライブラリのドキュメントが含まれる XML ファイルのファイル名を指定できます。 IntelliSense がドキュメントで正しく機能するには、ファイル名がアセンブリ名と同じである必要があり、アセンブリと同じディレクトリにある必要があります。 このプロパティを指定せず、GenerateDocumentationFiletrue に設定すると、そのドキュメント ファイルの名前は既定でアセンブリの名前になりますが、ファイル拡張子は .xml になります。 このため、多くの場合はこのプロパティを省略し、代わりに GenerateDocumentationFile プロパティを使用する方が簡単です。

このプロパティを指定しても、GenerateDocumentationFilefalse に設定した場合は、そのコンパイラでドキュメント ファイルは生成 されません。 このプロパティを指定し、GenerateDocumentationFile プロパティを省略した場合は、そのコンパイラでドキュメント ファイルが生成 されます

<PropertyGroup>
  <DocumentationFile>path/to/file.xml</DocumentationFile>
</PropertyGroup>

EmbeddedResourceUseDependentUponConvention

EmbeddedResourceUseDependentUponConvention プロパティによって、リソース マニフェスト ファイル名が、リソース ファイルと併置されているソース ファイルの型情報から生成されるかどうかを定義します。 たとえば、Form1.vbForm1.cs と同じフォルダーにあり、EmbeddedResourceUseDependentUponConventiontrue に設定されている場合、生成された .resources ファイルは Form1.cs で定義されている最初の型から名前を受け取ります。 たとえば、MyNamespace.Form1Form1.cs で定義されている最初の型である場合、生成されたファイル名は MyNamespace.Form1.resources になります。

注意

LogicalNameManifestResourceName、または DependentUpon メタデータが EmbeddedResource 項目に対して指定されている場合、そのリソース ファイルに対して生成されたマニフェスト ファイル名は、代わりにそのメタデータがベースになります。

既定では、新しい .NET プロジェクトでは、このプロパティは true に設定されます。 false に設定され、かつプロジェクト ファイルの EmbeddedResource 項目に LogicalNameManifestResourceNameDependentUpon のメタデータがどれも指定されていない場合、リソース マニフェストのファイル名は、プロジェクトのルート名前空間と、 .resx ファイルへの相対ファイル パスがベースになります。 詳細については、「リソース マニフェスト ファイルの名前付けの方法」を参照してください。

<PropertyGroup>
  <EmbeddedResourceUseDependentUponConvention>true</EmbeddedResourceUseDependentUponConvention>
</PropertyGroup>

EnablePreviewFeatures

EnablePreviewFeatures プロパティによって、RequiresPreviewFeaturesAttribute 属性で修飾されている API またはアセンブリにプロジェクトが依存するかどうかを定義します。 この属性は、API またはアセンブリによって、使用している SDK バージョンの "プレビュー段階" と見なされる機能が使われることを示す場合に使用されます。 プレビュー機能はサポートされておらず、将来のバージョンで削除される可能性があります。 プレビュー機能の使用を有効にするには、このプロパティを True に設定します。

<PropertyGroup>
  <EnablePreviewFeatures>True</EnablePreviewFeatures>
</PropertyGroup>

True に設定されたこのプロパティがプロジェクトに含まれている場合、AssemblyInfo.cs ファイルに次のアセンブリ レベルの属性が追加されます。

[assembly: RequiresPreviewFeatures]

EnablePreviewFeaturesTrue に設定されていないプロジェクトの依存関係にこの属性が存在する場合、アナライザーによって警告が表示されます。

プレビュー アセンブリをリリースする予定のライブラリ作成者は、このプロパティを True に設定する必要があります。 プレビューと非プレビューの API を組み合わせてアセンブリと共に出荷する必要がある場合は、以下の「GenerateRequiresPreviewFeaturesAttribute」セクションを参照してください。

EnableWindowsTargeting

EnableWindowsTargeting プロパティを true に設定して、Windows 以外のプラットフォームで Windows アプリ (Windows フォーム、Windows Presentation Foundation アプリなど) をビルドします。 このプロパティを true に設定しないと、ビルド警告 NETSDK1100 が表示されます。 このエラーは、ターゲット パックやランタイム パックが、サポートされていないプラットフォームで自動的にダウンロードされていないことが原因で発生します。 このプロパティを設定すると、これらのパックはクロスターゲット時にダウンロードされます。

<PropertyGroup>
  <EnableWindowsTargeting>true</EnableWindowsTargeting>
</PropertyGroup>

GenerateDocumentationFile

GenerateDocumentationFile プロパティは、コンパイラでそのライブラリの XML ドキュメント ファイルが生成されるかどうかを制御します。 このプロパティを true に設定し、DocumentationFile プロパティを使用してファイル名を指定しなかった場合、生成された XML ファイルはアセンブリと同じ出力ディレクトリに配置され、同じファイル名になります (ただし、拡張子は .xml になります)。

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

コード コメントからドキュメントを生成する方法について詳しくは、「XML ドキュメント コメント (C#)」、「XML の使用によるコードのドキュメントの作成 (Visual Basic)」、または「XML コメントを含むコードの文書化 (F#)」をご覧ください。

GenerateRequiresPreviewFeaturesAttribute

GenerateRequiresPreviewFeaturesAttribute プロパティは、EnablePreviewFeatures プロパティと密接に関連しています。 ライブラリでプレビュー機能を使用しているが、アセンブリ全体を RequiresPreviewFeaturesAttribute 属性でマークしたくない場合 (すべてのコンシューマーがプレビュー機能を有効にする必要があります) は、このプロパティを False に設定します。

<PropertyGroup>
    <EnablePreviewFeatures>True</EnablePreviewFeatures>
    <GenerateRequiresPreviewFeaturesAttribute>False</GenerateRequiresPreviewFeaturesAttribute>
</PropertyGroup>

重要

GenerateRequiresPreviewFeaturesAttribute プロパティを False に設定する場合は、プレビュー機能に依存するすべてのパブリック API を RequiresPreviewFeaturesAttribute で修飾する必要があります。

OptimizeImplicitlyTriggeredBuild

ビルド時間を高速化するために、Visual Studio によって暗黙的にトリガーされるビルドでは、null 許容の分析を含め、コード分析がスキップされます。 たとえば、テストを実行すると、Visual Studio によって暗黙的なビルドがトリガーされます。 ただし、暗黙的なビルドは、TreatWarningsAsErrorstrue ではない場合にのみ最適化されます。 TreatWarningsAsErrorstrue に設定したが、暗黙的にトリガーされるビルドを引き続き最適化したい場合は、OptimizeImplicitlyTriggeredBuildTrue に設定できます。 暗黙的にトリガーされるビルドに対してビルドの最適化を無効にする場合は、OptimizeImplicitlyTriggeredBuildFalse に設定します。

<PropertyGroup>
    <OptimizeImplicitlyTriggeredBuild>True</OptimizeImplicitlyTriggeredBuild>
</PropertyGroup>

既定の項目の包含プロパティ

このセクションでは、次の MSBuild プロパティについて説明します。

詳細については、「既定で含まれるものと除外されるもの」を参照してください。

DefaultItemExcludes

DefaultItemExcludes プロパティを使用して、含まれる、除外される、および削除の glob から除外するファイルとフォルダーの glob パターンを定義します。 既定では、 ./bin および ./obj フォルダーは、glob パターンから除外されます。

<PropertyGroup>
  <DefaultItemExcludes>$(DefaultItemExcludes);**/*.myextension</DefaultItemExcludes>
</PropertyGroup>

DefaultItemExcludesInProjectFolder

DefaultItemExcludesInProjectFolder プロパティを使用して、含まれる、除外される、および削除の glob から除外する、プロジェクト フォルダーのファイルとフォルダーの glob パターンを定義します。 既定では、ピリオド (.) で始まるフォルダー ( .git.vs など) は、glob パターンから除外されます。

このプロパティは、プロジェクト フォルダー内のファイルとフォルダーのみが考慮される点を除いて、DefaultItemExcludes プロパティとよく似ています。 glob パターンが意図せずにプロジェクト フォルダー外の項目と相対パスを照合する場合は、DefaultItemExcludes プロパティの代わりに DefaultItemExcludesInProjectFolder プロパティを使用します。

<PropertyGroup>
  <DefaultItemExcludesInProjectFolder>$(DefaultItemExcludesInProjectFolder);**/myprefix*/**</DefaultItemExcludesInProjectFolder>
</PropertyGroup>

EnableDefaultItems

EnableDefaultItems プロパティは、コンパイル項目、埋め込みリソース項目、および None 項目がプロジェクトに暗黙的に含まれるかどうかを制御します。 既定値は true です。 EnableDefaultItems プロパティを false に設定して、暗黙的なファイルの組み込みをすべて無効にします。

<PropertyGroup>
  <EnableDefaultItems>false</EnableDefaultItems>
</PropertyGroup>

EnableDefaultCompileItems

EnableDefaultCompileItems プロパティは、コンパイル項目がプロジェクトに暗黙的に含まれるかどうかを制御します。 既定値は true です。 EnableDefaultCompileItems プロパティを false に設定して、*.cs およびその他の言語拡張ファイルの暗黙的な包含を無効にします。

<PropertyGroup>
  <EnableDefaultCompileItems>false</EnableDefaultCompileItems>
</PropertyGroup>

EnableDefaultEmbeddedResourceItems

EnableDefaultEmbeddedResourceItems プロパティは、埋め込みリソース項目がプロジェクトに暗黙的に含まれるかどうかを制御します。 既定値は true です。 埋め込みリソース ファイルの暗黙的な包含を無効にするには、EnableDefaultEmbeddedResourceItems プロパティを false に設定します。

<PropertyGroup>
  <EnableDefaultEmbeddedResourceItems>false</EnableDefaultEmbeddedResourceItems>
</PropertyGroup>

EnableDefaultNoneItems

EnableDefaultNoneItems プロパティは、None 項目 (ビルド プロセスでロールがないファイル) がプロジェクトに暗黙的に含まれるかどうかを制御します。 既定値は true です。 EnableDefaultNoneItems プロパティを false に設定して、None 項目の暗黙的な包含を無効にします。

<PropertyGroup>
  <EnableDefaultNoneItems>false</EnableDefaultNoneItems>
</PropertyGroup>

コード分析のプロパティ

このセクションでは、次の MSBuild プロパティについて説明します。

AnalysisLevel

AnalysisLevel プロパティを使用すると、.NET リリースに従って実行するコード アナライザーのセットを指定できます。 .NET 5 以降の各 .NET リリースには、一連のコード分析規則が含まれています。 そのセットのうち、そのリリースで既定で有効になっている規則によって、コードが分析されます。 たとえば、.NET 7 にアップグレードしても、コード分析ルールの既定のセットを変更したくない場合は、 を に設定 AnalysisLevel します 6

<PropertyGroup>
  <AnalysisLevel>preview</AnalysisLevel>
</PropertyGroup>

必要に応じて、.NET 6 以降は、このプロパティに複合値を指定して、規則をどの程度積極的に有効にするかを指定することもできます。 複合値は、<version>-<mode> という形式になります。ここで、<mode> 値は、AnalysisMode 値の 1 つです。 次の例では、プレビュー バージョンのコード アナライザーを使用して、推奨される規則のセットを有効にします。

<PropertyGroup>
  <AnalysisLevel>preview-recommended</AnalysisLevel>
</PropertyGroup>

注意

AnalysisLevel5-<mode> または 5.0-<mode> に設定し、.NET 6 SDK をインストールしてプロジェクトを再コンパイルすると、予期しない新しいビルド警告が表示されることがあります。 詳細については、dotnet/roslyn-analyzers#5679 を参照してください。

既定値:

  • プロジェクトのターゲットが .NET 5.0 以降の場合、または AnalysisMode プロパティを追加した場合、既定値は latest になります。
  • それ以外の場合、このプロパティは、プロジェクト ファイルに明示的に追加されていない限り省略されます。

次の表は、指定できる値を示しています。

説明
latest リリースされている最新のコード アナライザーが使用されます。 既定値です。
latest-<mode> リリースされている最新のコード アナライザーが使用されます。 <mode> 値によって、有効になる規則が決まります。
preview 最新のコード アナライザーが、プレビュー段階であっても使用されます。
preview-<mode> 最新のコード アナライザーが、プレビュー段階であっても使用されます。 <mode> 値によって、有効になる規則が決まります。
7.0 .NET 7 リリースで使用できる一連のルールは、新しいルールが使用可能な場合でも使用されます。
7.0-<mode> .NET 7 リリースで使用できる一連のルールは、新しいルールが使用可能な場合でも使用されます。 <mode> 値によって、有効になる規則が決まります。
7 .NET 7 リリースで使用できる一連のルールは、新しいルールが使用可能な場合でも使用されます。
7-<mode> .NET 7 リリースで使用できる一連のルールは、新しいルールが使用可能な場合でも使用されます。 <mode> 値によって、有効になる規則が決まります。
6.0 新しい規則が使用可能な場合でも、.NET 6 リリースで使用可能であった一連の規則が使用されます。
6.0-<mode> 新しい規則が使用可能な場合でも、.NET 6 リリースで使用可能であった一連の規則が使用されます。 <mode> 値によって、有効になる規則が決まります。
6 新しい規則が使用可能な場合でも、.NET 6 リリースで使用可能であった一連の規則が使用されます。
6-<mode> 新しい規則が使用可能な場合でも、.NET 6 リリースで使用可能であった一連の規則が使用されます。 <mode> 値によって、有効になる規則が決まります。
5.0 新しい規則が使用可能な場合でも、.NET 5 リリースで使用可能であった一連の規則が使用されます。
5.0-<mode> 新しい規則が使用可能な場合でも、.NET 5 リリースで使用可能であった一連の規則が使用されます。 <mode> 値によって、有効になる規則が決まります。
5 新しい規則が使用可能な場合でも、.NET 5 リリースで使用可能であった一連の規則が使用されます。
5-<mode> 新しい規則が使用可能な場合でも、.NET 5 リリースで使用可能であった一連の規則が使用されます。 <mode> 値によって、有効になる規則が決まります。

注意

  • .NET 5 およびそれより前のバージョンでは、このプロパティはコード品質 (CAXXXX) 規則にのみ影響します。 .NET 6 以降は、EnforceCodeStyleInBuildtrue に設定した場合、このプロパティはコード スタイル (IDEXXXX) の規則にも影響します。
  • AnalysisLevel に複合値を設定した場合、AnalysisMode を指定する必要はありません。 ただし、そのようにした場合、AnalysisLevelAnalysisMode よりも優先されます。
  • このプロパティは、プロジェクト SDK を参照しないプロジェクト (たとえば、Microsoft. CodeAnalysis. NetAnalyzers NuGet パッケージを参照するレガシ .NET Framework プロジェクト) のコード分析には影響しません。

AnalysisLevel<Category>

.NET 6 で導入されたこのプロパティは、コード分析規則の特定のカテゴリにのみ適用される点を除いて、AnalysisLevel と同じです。 このプロパティを使用すると、特定のカテゴリに対して異なるバージョンのコード アナライザーを使用したり、他の規則カテゴリに対して異なるレベルの規則を有効または無効にしたりできます。 特定の規則カテゴリに対してこのプロパティを省略した場合、既定で AnalysisLevel 値に設定されます。 使用可能な値は、AnalysisLevel に使用できるものと同じです。

<PropertyGroup>
  <AnalysisLevelSecurity>preview</AnalysisLevelSecurity>
</PropertyGroup>
<PropertyGroup>
  <AnalysisLevelSecurity>preview-recommended</AnalysisLevelSecurity>
</PropertyGroup>

次の表は、各規則カテゴリのプロパティ名を示しています。

プロパティ名 規則カテゴリ
<AnalysisLevelDesign> デザイン規則
<AnalysisLevelDocumentation> ドキュメント規則
<AnalysisLevelGlobalization> グローバリゼーション規則
<AnalysisLevelInteroperability> 移植性と相互運用性の規則
<AnalysisLevelMaintainability> 保守容易性の規則
<AnalysisLevelNaming> 名前付け規則
<AnalysisLevelPerformance> パフォーマンス ルール
<AnalysisLevelSingleFile> 単一ファイルのアプリケーション規則
<AnalysisLevelReliability> 信頼性の規則
<AnalysisLevelSecurity> セキュリティ規則
<AnalysisLevelStyle> コード スタイル (IDEXXXX) 規則
<AnalysisLevelUsage> 使い方の規則

AnalysisMode

.NET 5 以降、.NET SDK には、すべての "CA" コード品質ルールが付属しています。 既定では、各 .NET リリースでビルド警告として一部のルールが有効になっています。 AnalysisModeプロパティを使用すると、既定で有効になっているルールのセットをカスタマイズできます。 より積極的な分析モード (ルールを個々にオプトアウトできる)、またはより保守的な分析モード (特定のルールにオプトインできる) に切り替えることができます。 たとえば、すべてのルールをビルド警告として有効にする場合は、値を All に設定します。

<PropertyGroup>
  <AnalysisMode>All</AnalysisMode>
</PropertyGroup>

次の表は、.NET 5 以降のバージョンで使用できるオプション値を示しています。 これらは、有効になる規則の数に従って昇順に一覧表示されています。

.NET 6 以降の値 .NET 5 の値 説明
None AllDisabledByDefault すべてのルールが無効になっています。 個々の規則を選択的にオプトインして有効にすることができます。
Default Default 既定のモードでは、特定のルールがビルド警告として有効になり、特定のルールが Visual Studio IDE の提案として有効になり、残りは無効になります。
Minimum 該当なし Default モードよりも積極的なモード。 ビルドの実施のために強く推奨される特定の提案が、ビルドの警告として有効になります。
Recommended 該当なし Minimum モードよりも積極的なモードであり、より多くの規則がビルド警告として有効になります。
All AllEnabledByDefault すべてのルールがビルド警告として有効になっています。 個々のルールを選択的にオプトアウトして無効にすることができます。

注意

  • .NET 5 の場合、このプロパティはコード品質 (CAXXXX) 規則にのみ影響します。 .NET 6 以降は、EnforceCodeStyleInBuildtrue に設定した場合、このプロパティはコード スタイル (IDEXXXX) の規則にも影響します。
  • AnalysisLevel に複合値 (例: <AnalysisLevel>5-recommended</AnalysisLevel>) を使用する場合は、このプロパティを完全に省略できます。 ただし、両方のプロパティを指定した場合は、AnalysisLevelAnalysisMode よりも優先されます。
  • AnalysisModeAllEnabledByDefault に設定し、AnalysisLevel5 または 5.0 に設定し、.NET 6 SDK をインストールしてプロジェクトを再コンパイルすると、予期しない新しいビルド警告が表示されることがあります。 詳細については、dotnet/roslyn-analyzers#5679 を参照してください。
  • このプロパティは、プロジェクト SDK を参照しないプロジェクト (たとえば、Microsoft. CodeAnalysis. NetAnalyzers NuGet パッケージを参照するレガシ .NET Framework プロジェクト) のコード分析には影響しません。

AnalysisMode<Category>

.NET 6 で導入されたこのプロパティは、コード分析規則の特定のカテゴリにのみ適用される点を除いて、AnalysisMode と同じです。 このプロパティを使用すると、他の規則カテゴリとは異なるレベルで規則を有効または無効にすることができます。 特定の規則カテゴリに対してこのプロパティを省略した場合、既定で AnalysisMode 値に設定されます。 使用可能な値は、AnalysisMode に使用できるものと同じです。

<PropertyGroup>
  <AnalysisModeSecurity>All</AnalysisModeSecurity>
</PropertyGroup>

次の表は、各規則カテゴリのプロパティ名を示しています。

プロパティ名 規則カテゴリ
<AnalysisModeDesign> デザイン規則
<AnalysisModeDocumentation> ドキュメント規則
<AnalysisModeGlobalization> グローバリゼーション規則
<AnalysisModeInteroperability> 移植性と相互運用性の規則
<AnalysisModeMaintainability> 保守容易性の規則
<AnalysisModeNaming> 名前付け規則
<AnalysisModePerformance> パフォーマンス ルール
<AnalysisModeSingleFile> 単一ファイルのアプリケーション規則
<AnalysisModeReliability> 信頼性の規則
<AnalysisModeSecurity> セキュリティ規則
<AnalysisModeStyle> コード スタイル (IDEXXXX) 規則
<AnalysisModeUsage> 使い方の規則

CodeAnalysisTreatWarningsAsErrors

CodeAnalysisTreatWarningsAsErrors プロパティを使用すると、コード品質分析の警告 (CAxxxx) を警告として扱い、ビルドを中断するかどうかを構成できます。 プロジェクトをビルドするときに -warnaserror フラグを使用すると、.NET コード品質分析の警告もエラーとして扱われます。 コード品質分析の警告がエラーとして扱われないようにするには、プロジェクト ファイル内の CodeAnalysisTreatWarningsAsErrors MSBuild プロパティを false に設定します。

<PropertyGroup>
  <CodeAnalysisTreatWarningsAsErrors>false</CodeAnalysisTreatWarningsAsErrors>
</PropertyGroup>

EnableNETAnalyzers

.NET 5 以降のバージョンをターゲットとするプロジェクトでは、.NET コード品質分析が既定で有効になっています。 .NET 5 以降の SDK を使用して開発している場合、以前のバージョンの .NET をターゲットとする SDK スタイルのプロジェクトで .NET コード分析を有効にするには、EnableNETAnalyzers プロパティを true に設定します。 任意のプロジェクトでコード分析を無効にするには、このプロパティを false に設定します。

<PropertyGroup>
  <EnableNETAnalyzers>true</EnableNETAnalyzers>
</PropertyGroup>

注意

このプロパティは、特に、.NET 5+ SDK の組み込みアナライザーに適用されます。 これは NuGet コード分析パッケージをインストールするときには使用しないでください。

EnforceCodeStyleInBuild

すべての .NET プロジェクトのビルドでは、.NET コード スタイル分析は既定で無効になっています。 EnforceCodeStyleInBuild プロパティを true に設定して、.NET プロジェクトのコード スタイル分析を有効にできます。

<PropertyGroup>
  <EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>
</PropertyGroup>

警告またはエラーになるように構成されているすべてのコード スタイル ルールは、ビルド時に実行され、違反を報告します。

注意

.NET 6 (または .NET 6 を含む Visual Studio 2022) をインストールするが、Visual Studio 2019 を使ってご自分のプロジェクトのビルドを検討している場合に、EnforceCodeStyleInBuild プロパティを true に設定すると、新しい CS8032 警告が表示されることがあります。 この警告を解決するには、global.json エントリ を追加して、プロジェクトのビルドに使用する.NET SDK のバージョン (この場合は 5.0.404 など) を指定します。

_SkipUpgradeNetAnalyzersNuGetWarning

_SkipUpgradeNetAnalyzersNuGetWarning プロパティを使用すると、最新の .NET SDK のコード アナライザーと比較した場合に古くなった NuGet パッケージのコード アナライザーを使用しているときに、警告を受け取るかどうかを構成できます。 警告は次のように表示されます。

The .NET SDK has newer analyzers with version '6.0.0' than what version '5.0.3' of 'Microsoft.CodeAnalysis.NetAnalyzers' package provides. (.NET SDK には、"Microsoft.CodeAnalysis.NetAnalyzers" パッケージのバージョン '5.0.3' よりも新しいバージョン '6.0.0' のアナライザーが用意されています。) Update or remove this package reference. (このパッケージ参照を更新または削除してください。)

この警告を削除して、NuGet パッケージのコード アナライザーのバージョンの使用を続けるには、プロジェクト ファイルで、_SkipUpgradeNetAnalyzersNuGetWarningtrue に設定します。

<PropertyGroup>
  <_SkipUpgradeNetAnalyzersNuGetWarning>true</_SkipUpgradeNetAnalyzersNuGetWarning>
</PropertyGroup>

ランタイム構成プロパティ

アプリのプロジェクト ファイルに MSBuild プロパティを指定することで一部のランタイム動作を構成できます。 ランタイム動作のその他の構成方法については、ランタイム構成設定に関する記事をご覧ください。

ConcurrentGarbageCollection

ConcurrentGarbageCollection プロパティでは、バックグラウンド (同時実行) ガベージ コレクションの有効または無効が設定されます。 この値を false に設定すると、バックグラウンド ガベージ コレクションが無効になります。 詳細については、「バックグラウンド GC」を参照してください。

<PropertyGroup>
  <ConcurrentGarbageCollection>false</ConcurrentGarbageCollection>
</PropertyGroup>

InvariantGlobalization

InvariantGlobalization プロパティでは、アプリを globalization-invariant モードで実行するかどうかを設定します。このモードでは、カルチャ固有のデータにアクセスできません。 この値を true に設定すると、globalization-invariant モードで実行されます。 詳細については、「インバリアント モード」を参照してください。

<PropertyGroup>
  <InvariantGlobalization>true</InvariantGlobalization>
</PropertyGroup>

PredefinedCulturesOnly

.NET 6 以降のバージョンでは、グローバリゼーション インバリアント モードが有効になっているときにアプリでインバリアント カルチャ以外のカルチャを作成できるかどうかを PredefinedCulturesOnly プロパティで構成します。 既定では、 trueです。 グローバリゼーション インバリアント モードで新しいカルチャの作成を許可するには、値を false に設定します。

<PropertyGroup>
  <PredefinedCulturesOnly>false</PredefinedCulturesOnly>
</PropertyGroup>

詳細については、「グローバリゼーション インバリアント モードでのカルチャの作成とケース マッピング」を参照してください。

RetainVMGarbageCollection

RetainVMGarbageCollection プロパティでは、将来利用する目的で削除済みメモリ セグメントを待機一覧に載せるように、あるいは削除済みメモリ セグメントを解放するようにガベージ コレクターを設定します。 この値を true に設定すると、セグメントを待機一覧に載せるよう、ガベージ コレクターが命令されます。 詳細については、「VM の保持」を参照してください。

<PropertyGroup>
  <RetainVMGarbageCollection>true</RetainVMGarbageCollection>
</PropertyGroup>

ServerGarbageCollection

ServerGarbageCollection プロパティでは、アプリケーションで使用するガベージ コレクションとしてワークステーション ガベージ コレクションまたはサーバー ガベージ コレクションを設定します。 この値を true に設定すると、サーバー ガベージ コレクションが使用されます。 詳細については、「ワークステーションとサーバー」を参照してください。

<PropertyGroup>
  <ServerGarbageCollection>true</ServerGarbageCollection>
</PropertyGroup>

ThreadPoolMaxThreads

ThreadPoolMaxThreads プロパティでは、ワーカー スレッド プールの最大スレッド数を設定します。 詳細については、「最大スレッド数」を参照してください。

<PropertyGroup>
  <ThreadPoolMaxThreads>20</ThreadPoolMaxThreads>
</PropertyGroup>

ThreadPoolMinThreads

ThreadPoolMinThreads プロパティでは、ワーカー スレッド プールの最小スレッド数を設定します。 詳細については、「最小スレッド数」を参照してください。

<PropertyGroup>
  <ThreadPoolMinThreads>4</ThreadPoolMinThreads>
</PropertyGroup>

TieredCompilation

TieredCompilation プロパティでは、Just-In-Time (JIT) コンパイラで階層型コンパイルを使用するかどうかを設定します。 この値を false に設定すると、階層型コンパイルが無効になります。 詳細については、「階層型コンパイル」を参照してください。

<PropertyGroup>
  <TieredCompilation>false</TieredCompilation>
</PropertyGroup>

TieredCompilationQuickJit

TieredCompilationQuickJit プロパティでは、JIT コンパイラでクイック JIT を使用するかどうかを設定します。 この値を false に設定すると、クイック JIT が無効になります。 詳細については、「クイック JIT」を参照してください。

<PropertyGroup>
  <TieredCompilationQuickJit>false</TieredCompilationQuickJit>
</PropertyGroup>

TieredCompilationQuickJitForLoops

TieredCompilationQuickJitForLoops プロパティでは、ループを含むメソッドに対して JIT コンパイラでクリック JIT を使用するかどうかを設定します。 この値を true に設定すると、ループが含まれるメソッドでクイック JIT が有効になります。 詳細については、「ループに対するクイック JIT」を参照してください。

<PropertyGroup>
  <TieredCompilationQuickJitForLoops>true</TieredCompilationQuickJitForLoops>
</PropertyGroup>

このセクションでは、次の MSBuild プロパティについて説明します。

AssetTargetFallback

AssetTargetFallback プロパティを使用すると、プロジェクト参照と NuGet パッケージに対して、互換性のある追加のフレームワーク バージョンを指定できます。 たとえば、PackageReference を使用してパッケージの依存関係を指定し、そのパッケージにプロジェクトの TargetFramework と互換性のある資産が含まれない場合は、AssetTargetFallback プロパティが機能します。 参照されたパッケージの互換性は、AssetTargetFallback で指定された各ターゲット フレームワークを使用して再確認されます。 このプロパティは、非推奨のプロパティ PackageTargetFallback に代わるものです。

AssetTargetFallback プロパティを 1 つ以上のターゲット フレームワーク バージョンに設定できます。

<PropertyGroup>
  <AssetTargetFallback>net461</AssetTargetFallback>
</PropertyGroup>

DisableImplicitFrameworkReferences

DisableImplicitFrameworkReferences プロパティを使用すると、.NET Core 3.0 以降のバージョンを対象とする場合に、暗黙的な FrameworkReference の項目を制御できます。 .NET Core 2.1 または .NET Standard 2.0 以前のバージョンを対象としている場合は、これにより、メタパッケージ内のパッケージに対する暗黙的な PackageReference の項目が制御されます。 (メタパッケージは、他のパッケージへの依存関係でのみ構成されるフレームワーク ベースのパッケージです)。また、.NET Framework を対象とする場合は、このプロパティによって、SystemSystem.Core などの暗黙的な参照が制御されます。

このプロパティを true に設定して、暗黙的な FrameworkReference または PackageReference の項目を無効にします。 このプロパティを true に設定すると、必要なフレームワークまたはパッケージだけに明示的な参照を追加できます。

<PropertyGroup>
  <DisableImplicitFrameworkReferences>true</DisableImplicitFrameworkReferences>
</PropertyGroup>

DisableTransitiveFrameworkReferenceDownloads

DisableTransitiveFrameworkReferenceDownloads プロパティを true に設定して、プロジェクトによって直接参照されていない追加のランタイム パックやターゲット パックがダウンロードされないようにします。

<PropertyGroup>
  <DisableTransitiveFrameworkReferenceDownloads>true</DisableTransitiveFrameworkReferenceDownloads>
</PropertyGroup>

DisableTransitiveProjectReferences

DisableTransitiveProjectReferences プロパティにより、暗黙的なプロジェクト参照を制御できます。 暗黙的な ProjectReference の項目を無効にするには、このプロパティを true に設定します。 暗黙的なプロジェクト参照を無効にすると、レガシ プロジェクト システムに似た非推移的な動作になります。

このプロパティを true にすると、依存しているプロジェクトのすべての依存関係に対して PrivateAssets="All" を設定するのと同様の効果があります。

このプロパティを true に設定すると、必要なプロジェクトだけに明示的な参照を追加できます。

<PropertyGroup>
  <DisableTransitiveProjectReferences>true</DisableTransitiveProjectReferences>
</PropertyGroup>

参照されたパッケージを復元すると、その直接的な依存関係と間接的な依存関係がすべてインストールされます。 RestorePackagesPathRestoreIgnoreFailedSources など、プロパティを指定することでパッケージ復元をカスタマイズできます。 以上のプロパティとその他のプロパティの詳細については、「restore ターゲット」を参照してください。

<PropertyGroup>
  <RestoreIgnoreFailedSource>true</RestoreIgnoreFailedSource>
</PropertyGroup>

UseMauiEssentials

UseMauiEssentials プロパティを true に設定して、MAUI Essentials に依存するプロジェクトまたはパッケージに明示的な参照を宣言します。 この設定により、MAUI Essentials の正しい既知のフレームワーク参照でプロジェクトが確実にプルされます。 プロジェクトが MAUI Essentials を使用するプロジェクトを参照しているが、このプロパティを true に設定しない場合、ビルド警告 NETSDK1186 が発生する可能性があります。

<PropertyGroup>
  <UseMauiEssentials>true</UseMauiEssentials>
</PropertyGroup>

ValidateExecutableReferencesMatchSelfContained

ValidateExecutableReferencesMatchSelfContained プロパティを使用して、実行可能なプロジェクト参照に関連するエラーを無効にできます。 自己完結型の実行可能プロジェクトによってフレームワークに依存する実行可能プロジェクトが参照されていることが .NET により検出された場合、またはその逆の場合、エラー NETSDK1150 と NETSDK1151 がそれぞれ生成されます。 参照が意図的なものである場合にこのエラーを回避するには、ValidateExecutableReferencesMatchSelfContained プロパティを false に設定します。

<PropertyGroup>
  <ValidateExecutableReferencesMatchSelfContained>false</ValidateExecutableReferencesMatchSelfContained>
</PropertyGroup>

WindowsSdkPackageVersion

WindowsSdkPackageVersion プロパティは、Windows SDK ターゲット パッケージのバージョンをオーバーライドする目的で使用できます。 このプロパティは .NET 5 で導入され、この目的での FrameworkReference 項目の使用に取って代わります。

<PropertyGroup>
  <WindowsSdkPackageVersion>10.0.19041.18</WindowsSdkPackageVersion>
</PropertyGroup>

注意

Windows SDK バージョンのオーバーライドはお勧めしません。Windows SDK ターゲット パッケージが .NET 5+ SDK に含まれているためです。 代わりに、最新の Windows SDK パッケージを参照する目的で、.NET SDK のバージョンを更新してください。 このプロパティは、プレビュー パッケージを使用したり、C#/WinRT のバージョンをオーバーライドしたりするなど、まれな状況でのみ使用してください。

次のプロパティは、dotnet run コマンドを使用してアプリを起動するために使用されます。

RunArguments

RunArguments プロパティを使用すると、実行時にアプリに渡される引数が定義されます。

<PropertyGroup>
  <RunArguments>-mode dryrun</RunArguments>
</PropertyGroup>

ヒント

dotnet run-- オプションを使用して、アプリに渡す追加の引数を指定できます。

RunWorkingDirectory

RunWorkingDirectory プロパティを使用すると、開始するアプリケーション プロセスの作業ディレクトリが定義されます。 絶対パスまたはプロジェクト ディレクトリに対する相対パスを指定できます。 ディレクトリを指定しない場合、作業ディレクトリとして OutDir が使用されます。

<PropertyGroup>
  <RunWorkingDirectory>c:\temp</RunWorkingDirectory>
</PropertyGroup>

このセクションでは、次の MSBuild プロパティについて説明します。

EnableComHosting

EnableComHosting プロパティは、アセンブリで COM サーバーが提供されることを示します。 EnableComHostingtrue に設定することは、EnableDynamicLoadingtrue であることも意味します。

<PropertyGroup>
  <EnableComHosting>True</EnableComHosting>
</PropertyGroup>

詳細については、COM への .NET コンポーネントの公開に関するページを参照してください。

EnableDynamicLoading

EnableDynamicLoading プロパティは、アセンブリが動的に読み込まれたコンポーネントであることを示します。 このコンポーネントには、COM ライブラリ、またはネイティブ ホストから使用またはプラグインとして使用できる非 COM ライブラリを指定できます。 このプロパティを true に設定すると、次のような効果があります。

  • " .runtimeconfig.json" ファイルが生成される。
  • RollForwardLatestMinor に設定されます。
  • NuGet 参照がローカルにコピーされる。
<PropertyGroup>
  <EnableDynamicLoading>true</EnableDynamicLoading>
</PropertyGroup>

生成されたファイルのプロパティ

次のプロパティは、生成されたファイルのコードに関するものです。

DisableImplicitNamespaceImports

DisableImplicitNamespaceImports プロパティを使用すると、.NET 6 以降のバージョンをターゲットとする Visual Basic プロジェクトで暗黙的な名前空間のインポートを無効にできます。 暗黙的な名前空間とは、Visual Basic プロジェクトでグローバルにインポートされる既定の名前空間のことです。 暗黙的な名前空間のインポートを無効にするには、このプロパティを true に設定します。

<PropertyGroup>
  <DisableImplicitNamespaceImports>true</DisableImplicitNamespaceImports>
</PropertyGroup>

ImplicitUsings

ImplicitUsings プロパティを使用すると、.NET 6 以降のバージョンと C# 10 以降のバージョンをターゲットとする C# プロジェクトで、暗黙的な global using ディレクティブを有効または無効にすることができます。 この機能を有効にすると、.NET SDK により、既定の名前空間セットに対して、プロジェクト SDK の種類に基づいて global using ディレクティブが追加されます。 暗黙的な global using ディレクティブを有効にするには、このプロパティを true または enable に設定します。 暗黙的な global using ディレクティブを無効にするには、このプロパティを削除するか、false または disable に設定します。

<PropertyGroup>
  <ImplicitUsings>enable</ImplicitUsings>
</PropertyGroup>

注意

.NET 6 以降をターゲットとする新しい C# プロジェクトのテンプレートでは、ImplicitUsings は既定で enable に設定されます。

明示的な global using ディレクティブを定義するには、Using 項目を追加します。

アイテム

MSBuild 項目はビルド システムへの入力です。 項目は、要素名である型に従って指定されます。 たとえば、CompileReference は 2 つの一般的な項目の種類です。 .NET SDK では、次の追加の項目の種類を使用できます。

これらの項目には、標準の項目属性 (IncludeUpdate など) を使用できます。 Include を使用して新しい項目を追加し、Update を使用して既存の項目を変更します。 たとえば、Update は、.NET SDK によって暗黙的に追加された項目を変更するためによく使用されます。

AssemblyMetadata

AssemblyMetadata 項目によって、キーと値のペアの AssemblyMetadataAttribute アセンブリ属性を指定します。 Include メタデータがキーになり、Value メタデータが値になります。

<ItemGroup>
  <AssemblyMetadata Include="Serviceable" Value="True" />
</ItemGroup>

InternalsVisibleTo

InternalsVisibleTo 項目によって、指定されたフレンド アセンブリの InternalsVisibleToAttribute アセンブリ属性を生成します。

<ItemGroup>
  <InternalsVisibleTo Include="MyProject.Tests" />
</ItemGroup>

フレンド アセンブリが署名されている場合は、省略可能な Key メタデータを指定して、その完全な公開キーを指定できます。 Key メタデータを指定しておらず、$(PublicKey) が使用可能な場合は、そのキーが使用されます。 それ以外の場合、属性に公開キーは追加されません。

PackageReference

PackageReference 項目では、NuGet パッケージへの参照が定義されます。

Include 属性は、パッケージ ID を指定します。 Version 属性では、バージョンまたはバージョン範囲を指定します。 最小バージョン、最大バージョン、範囲、厳密一致を指定する方法については、「バージョン範囲」を参照してください。

次の例のプロジェクト ファイル スニペットでは、System.Runtime パッケージを参照しています。

<ItemGroup>
  <PackageReference Include="System.Runtime" Version="4.3.0" />
</ItemGroup>

PrivateAssets などのメタデータを使用して依存関係資産を制御することもできます。

<ItemGroup>
  <PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.0">
    <PrivateAssets>all</PrivateAssets>
  </PackageReference>
</ItemGroup>

詳細については、プロジェクト ファイルのパッケージ参照に関するページを参照してください。

TrimmerRootAssembly

TrimmerRootAssembly 項目ではアセンブリを "トリミング" から除外できます。 トリミングとは、パッケージ化されたアプリケーションからランタイムの未使用部分を削除するプロセスです。 必要な参照がトリミングによって間違って削除されることもあります。

次の XML では、トリミングから System.Security アセンブリが除外されます。

<ItemGroup>
  <TrimmerRootAssembly Include="System.Security" />
</ItemGroup>

詳細については、「トリミングのオプション」を参照してください。

使用

Using 項目を使用すると、C# プロジェクト全体で名前空間をグローバルに含めることができるので、ソース ファイルの先頭に名前空間の using ディレクティブを追加する必要はありません。 この項目は、Visual Basic プロジェクトで同じ目的のために使用できる Import 項目と似ています。 このプロパティは、.NET 6 以降で使用できます。

<ItemGroup>
  <Using Include="My.Awesome.Namespace" />
</ItemGroup>

また、Using 項目を使用して、グローバルな using <alias> および using static <type> ディレクティブを定義することもできます。

<ItemGroup>
  <Using Include="My.Awesome.Namespace" Alias="Awesome" />
</ItemGroup>

次に例を示します。

  • <Using Include="Microsoft.AspNetCore.Http.Results" Alias="Results" /> により、global using Results = global::Microsoft.AspNetCore.Http.Results; が生成されます
  • <Using Include="Microsoft.AspNetCore.Http.Results" Static="True" /> により、global using static global::Microsoft.AspNetCore.Http.Results; が生成されます

詳細については、エイリアス化された using ディレクティブusing static <type> ディレクティブを参照してください。

項目メタデータ

標準の MSBuild 項目属性に加えて、次の項目メタデータ タグが .NET SDK によって利用可能になります。

CopyToPublishDirectory

MSBuild 項目の CopyToPublishDirectory メタデータにより、項目が発行ディレクトリにコピーされるタイミングが制御されます。 使用できる値は、項目が変更された場合にのみコピーする PreserveNewest、常に項目をコピーする Always、項目をコピーしない Never です。 パフォーマンスの観点からは、インクリメンタル ビルドが有効になるので PreserveNewest をお勧めします。

<ItemGroup>
  <None Update="appsettings.Development.json" CopyToOutputDirectory="PreserveNewest" CopyToPublishDirectory="PreserveNewest" />
</ItemGroup>

LinkBase

プロジェクト ディレクトリとそのサブディレクトリの外部にある項目の場合、発行先で項目のコピー先を決定するために、項目の Link メタデータが使用されます。 また、プロジェクト ツリーの外部にある項目が Visual Studio の [ソリューション エクスプローラー] ウィンドウにどのように表示されるかも、Link によって決定されます。

プロジェクト コーンの外部にある項目に対して Link が指定されていない場合は、既定で %(LinkBase)\%(RecursiveDir)%(Filename)%(Extension) になります。 LinkBase を使用して、プロジェクト コーンの外部の項目に適切なベース フォルダーを指定できます。 ベース フォルダーの下のフォルダー階層は、RecursiveDir によって保持されます。 LinkBase を指定しないと、それは Link パスから省略されます。

<ItemGroup>
  <Content Include="..\Extras\**\*.cs" LinkBase="Shared"/>
</ItemGroup>

次の図は、前の項目の Include glob によって含められるファイルがソリューション エクスプローラーにどのように表示されるかを示したものです。

LinkBase メタデータが指定された項目が表示されているソリューション エクスプローラー。

関連項目