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

  • [アーティクル]

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

注意

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

アセンブリ検証プロパティ

これらのプロパティと項目は、ValidateAssemblies タスクに渡されます。 アセンブリの検証の詳細については、「アセンブリの検証」を参照してください。

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

Note

これらのプロパティは、(まだ) .NET SDK の一部ではありません。 これらを使用するには、Microsoft.DotNet.ApiCompat.Task に PackageReference を追加する必要もあります。

さらに、「パッケージ検証プロパティ」に記載されている次のプロパティは、アセンブリの検証にも適用されます。

ApiCompatStrictMode

true プロパティに設定すると、API 互換性チェックを厳格モードで実行する必要があることが ApiCompatStrictMode プロパティにより指定されます。

<PropertyGroup>
  <ApiCompatStrictMode>true</ApiCompatStrictMode>
</PropertyGroup>

ApiCompatValidateAssemblies

ApiCompatValidateAssemblies プロパティを使用すると、指定したアセンブリに対して一連の検証を実行できます。 詳細については、「アセンブリ検証」を参照してください。

<PropertyGroup>
  <ApiCompatValidateAssemblies>true</ApiCompatValidateAssemblies>
</PropertyGroup>

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

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

TargetFramework

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

<PropertyGroup>
  <TargetFramework>net8.0</TargetFramework>
</PropertyGroup>

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

TargetFrameworks

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

注意

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

<PropertyGroup>
  <TargetFrameworks>net8.0;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 の場合、パッケージ関連のプロジェクト プロパティがアセンブリ属性に変換されます。

プロジェクト ファイルを使用してアセンブリ属性を生成する方法の詳細については、「プロジェクト ファイルでアセンブリ属性を設定する」を参照してください。

GeneratedAssemblyInfoFile

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

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

パッケージのプロパティ

説明プロパティ

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

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

PackRelease

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

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

Note

  • .NET 8 SDK 以降では、PackRelease の既定値は true です。 詳細については、「'dotnet pack' では Release 構成が使用される」を参照してください。
  • .NET 7 SDK のみ: Visual Studio ソリューションの一部であるプロジェクトで PackRelease を使用するには、環境変数 DOTNET_CLI_ENABLE_PACK_RELEASE_FOR_SOLUTIONS を true (またはその他の値) に設定する必要があります。 多くのプロジェクトを含むソリューションでは、この変数を設定すると、パックにより多くの時間が必要になります。

パッケージ検証プロパティ

これらのプロパティと項目は、ValidatePackage タスクに渡されます。 パッケージの検証の詳細については、「パッケージ検証の概要」を参照してください。

ValidateAssemblies タスクのプロパティについては、「アセンブリ検証プロパティ」を参照してください。

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

ApiCompatEnableRuleAttributesMustMatch

true に設定すると、ApiCompatEnableRuleAttributesMustMatch プロパティによって、属性が一致するかどうかをチェックする検証規則が有効になります。 既定値は、false です。

<PropertyGroup>
  <ApiCompatEnableRuleAttributesMustMatch>true</ApiCompatEnableRuleAttributesMustMatch>
</PropertyGroup>

ApiCompatEnableRuleCannotChangeParameterName

trueに設定すると、ApiCompatEnableRuleCannotChangeParameterName プロパティにより、パラメーター名がパブリック メソッドで変更されたかどうかを確認する検証規則が有効になります。 既定値は、false です。

<PropertyGroup>
  <ApiCompatEnableRuleCannotChangeParameterName>true</ApiCompatEnableRuleCannotChangeParameterName>
</PropertyGroup>

ApiCompatExcludeAttributesFile

ApiCompatExcludeAttributesFile 項目は、DocId 形式で除外する属性を含むファイルへのパスを指定します。

<ItemGroup>
  <ApiCompatExcludeAttributesFile Include="ApiCompatExcludedAttributes.txt" />
  <ApiCompatExcludeAttributesFile Include="ApiCompatBaselineExcludedAttributes.txt" />
</ItemGroup>

ApiCompatGenerateSuppressionFile

ApiCompatGenerateSuppressionFile プロパティにより、互換性抑制ファイルを生成するかどうかが指定されます。

<PropertyGroup>
  <ApiCompatGenerateSuppressionFile>true</ApiCompatGenerateSuppressionFile>
</PropertyGroup>

ApiCompatPermitUnnecessarySuppressions

ApiCompatPermitUnnecessarySuppressions プロパティにより、抑制ファイルで不要な抑制を許可するかどうかが指定されます。

既定値は、false です。

<PropertyGroup>
  <ApiCompatPermitUnnecessarySuppressions>true</ApiCompatPermitUnnecessarySuppressions>
</PropertyGroup>

ApiCompatPreserveUnnecessarySuppressions

ApiCompatPreserveUnnecessarySuppressions プロパティにより、抑制ファイルを再生成するときに不要な抑制を保持するかどうかが指定されます。 既存の抑制ファイルが再生成されるときは、その内容が読み取られ、一連の抑制に逆シリアル化された後、リストに格納されます。 非互換性が修正されている場合、一部の抑制は不要になる可能性があります。 抑制をディスクにシリアル化し直す場合は、このプロパティを true に設定することで、既存の (逆シリアル化された) 式を "すべて" 保持することができます。

既定値は、false です。

<PropertyGroup>
  <ApiCompatPreserveUnnecessarySuppressions>true</ApiCompatPreserveUnnecessarySuppressions>
</PropertyGroup>

ApiCompatRespectInternals

ApiCompatRespectInternals プロパティにより、public API に加えて、 internal API の互換性を確認する必要があるかどうかが指定されます。

<PropertyGroup>
  <ApiCompatRespectInternals>true</ApiCompatRespectInternals>
</PropertyGroup>

ApiCompatSuppressionFile

ApiCompatSuppressionFile 項目により、読み取る 1 つ以上の抑制ファイルへのパスが指定されます。 指定しない場合、抑制ファイル <project-directory>/CompatibilitySuppressions.xml が読み取られます (存在する場合)。

<ItemGroup>
  <ApiCompatSuppressionFile Include="CompatibilitySuppressions.xml;CompatibilitySuppressions.WasmThreads.xml" />
</ItemGroup>

ApiCompatSuppressionOutputFile

ApiCompatSuppressionOutputFile プロパティにより、<ApiCompatGenerateSuppressionFile> が true の場合に書き込む抑制ファイルへのパスが指定されます。 指定しないと、最初の ApiCompatSuppressionFile 項目が使われます。

EnablePackageValidation

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

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

EnableStrictModeForBaselineValidation

trueに設定すると、 EnableStrictModeForBaselineValidation プロパティにより、パッケージのベースライン チェックの厳格モードが有効になります。 既定値は、false です。

EnableStrictModeForCompatibleFrameworksInPackage

true に設定すると、EnableStrictModeForCompatibleFrameworksInPackage プロパティにより、ターゲット フレームワークに基づいて互換性のあるアセンブリの厳格モードが有効になります。 既定値は、false です。

EnableStrictModeForCompatibleTfms

true に設定すると、EnableStrictModeForCompatibleTfms プロパティにより、互換性のあるすべてのターゲット フレームワークのコントラクトおよび実装アセンブリの厳格モードが有効になります。 既定値は、true です。

NoWarn

NoWarn プロパティにより、抑制する診断 ID が指定されます。

<PropertyGroup>
  <NoWarn>$(NoWarn);PKV0001</NoWarn>
</PropertyGroup>

PackageValidationBaselineFrameworkToIgnore

PackageValidationBaselineFrameworkToIgnore 項目により、ベースライン パッケージから無視するターゲット フレームワークが指定されます。 フレームワーク文字列は、ベースライン パッケージ内のフォルダー名と正確に一致する必要があります。

<ItemGroup>
  <PackageValidationBaselineFrameworkToIgnore Include="netcoreapp2.1" />
</ItemGroup>

PackageValidationBaselineName

PackageValidationBaselineName プロパティにより、現在のパッケージを検証するベースライン パッケージの名前が指定されます。 指定しない場合は、PackageId 値が使用されます。

PackageValidationBaselineVersion

PackageValidationBaselineVersion プロパティにより、現在のパッケージを検証するベースライン パッケージのバージョンが指定されます。

PackageValidationReferencePath

PackageValidationReferencePath 項目により、TFM ごとに参照アセンブリが見つかるディレクトリ パスが指定されます。

<ItemGroup>
  <PackageValidationReferencePath Include="path/to/reference-assembly" TargetFramework="net7.0" />
</ItemGroup>

RoslynAssembliesPath

RoslynAssembliesPath プロパティにより、使用する Microsoft.CodeAnalysis アセンブリを含むディレクトリへのパスが指定されます。 このプロパティを設定する必要があるのは、SDK のコンパイラより新しいコンパイラでテストする場合のみです。

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

AppendTargetFrameworkToOutputPath

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

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

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

AppendRuntimeIdentifierToOutputPath

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

たとえば、.NET 5 アプリと RID の場合、次のwin-x64設定によって出力パスbin\Debug\net5.0\win-x64bin\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 で導入されました。

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 ファイルが必要なアプリの場合 (つまり、その OutputType が Exe である場合)、このプロパティの既定値は 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.CompileLibraries と DependencyContext.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 ドキュメント ファイルを生成するには、GenerateDocumentationFile を true に設定します。

PublishDocumentationFiles

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

PublishReferencesDocumentationFiles

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

PublishRelease

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

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

Note

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

PublishSelfContained

PublishSelfContained プロパティは、自己完結型アプリとしてアプリを発行するように dotnet publish に通知します。 このプロパティは、ソリューション レベルで発行する場合など、dotnet publish コマンドに --self-contained 引数を使用できない場合に便利です。 その場合は、PublishSelfContained MSBuild プロパティをプロジェクトまたは Directory.Build.Props ファイルに追加できます。

このプロパティは .NET 7 で導入されました。 これは、publish 動詞に固有である点を除いて、SelfContained プロパティに似ています。 SelfContained の代わりに PublishSelfContained を使用することが推奨されます。

<PropertyGroup>
  <PublishSelfContained>true</PublishSelfContained>
</PropertyGroup>

RollForward

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

<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>linux-x64</RuntimeIdentifier>
</PropertyGroup>

RuntimeIdentifiers

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

ヒント

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

<PropertyGroup>
  <RuntimeIdentifiers>win-x64;osx-x64;linux-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"""

SelfContained

SelfContained プロパティは、dotnet build と dotnet publish に、自己完結型アプリとしてアプリをビルドまたは発行するように通知します。 このプロパティは、ソリューション レベルで発行する場合など、dotnet コマンドで --self-contained 引数を使用できない場合に便利です。 その場合は、SelfContained MSBuild プロパティをプロジェクトまたは Directory.Build.Props ファイルに追加できます。

このプロパティは、PublishSelfContained プロパティに似ています。 可能な限り SelfContained の代わりに PublishSelfContained を使用することが推奨されます。

<PropertyGroup>
  <SelfContained>true</SelfContained>
</PropertyGroup>

UseAppHost

UseAppHost プロパティにより、デプロイ用にネイティブ実行可能ファイルを作成するかどうかが制御されます。 自己完結型の配置にはネイティブの実行可能ファイルが必要です。 フレームワークに依存する実行可能ファイルが既定で作成されます。 実行可能ファイルの生成を無効にするには、UseAppHost プロパティを false に設定します。

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

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

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

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

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

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

ContinuousIntegrationBuild

ContinuousIntegrationBuild プロパティは、ビルドが継続的インテグレーション (CI) サーバー上で実行されているかどうかを示します。 true に設定すると、このプロパティによって、開発者用マシン上のローカル ビルドではなく、公式ビルドにのみ適用される設定が有効になります。 たとえば、格納されたファイルのパスは公式ビルド用に正規化されます。 ただし、ローカル開発マシンでは、ファイル パスが正規化されている場合、デバッガーはローカル ソース ファイルを見つけることができません。

Note

現時点では、このプロパティを true に設定するのは、特定の SourceLink プロバイダー パッケージ参照または <SourceRoot Include="$(MyDirectory)" /> 項目を追加する場合にのみ機能します。 詳細については、dotnet/roslyn issue 55860 を参照してください。

CI システムの変数を使って、ContinuousIntegrationBuild プロパティを条件付きで設定することができます。 たとえば、Azure Pipelines の場合、変数名は TF_BUILDです。

<PropertyGroup Condition="'$(TF_BUILD)' == 'true'">
  <ContinuousIntegrationBuild>true</ContinuousIntegrationBuild>
</PropertyGroup>

GitHub Actions の場合、変数名は GITHUB_ACTIONS です。

<PropertyGroup Condition="'$(GITHUB_ACTIONS)' == 'true'">
  <ContinuousIntegrationBuild>true</ContinuousIntegrationBuild>
</PropertyGroup>

CopyDebugSymbolFilesFromPackages

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

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

CopyDocumentationFilesFromPackages

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

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

DisableImplicitFrameworkDefines

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

  • バージョンのないフレームワーク (NETFRAMEWORK、NETSTANDARD、NET)
  • バージョンのあるフレームワーク (NET48、NETSTANDARD2_0、NET6_0)
  • バージョンが最小バインドのフレームワーク (NET48_OR_GREATER、NETSTANDARD2_0_OR_GREATER、NET6_0_OR_GREATER)

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

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

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

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

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

DocumentationFile

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

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

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

EmbeddedResourceUseDependentUponConvention

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

注意

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

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

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

EnablePreviewFeatures

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

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

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

[assembly: RequiresPreviewFeatures]

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

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

EnableWindowsTargeting

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

注意

現在、このプロパティは、Windows 以外のプラットフォームでの開発を許可するために推奨されています。 ただし、アプリケーションをリリースする準備ができたら、Windows 上にビルドする必要があります。 Windows 以外のプラットフォームでビルドする場合、出力が Windows でビルドする場合と同じでない場合があります。 特に、実行可能ファイルが Windows アプリケーションとしてマークされず (これは常にコンソール ウィンドウが起動されることを意味します)、アイコンが埋め込まれていません。

<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 によって暗黙的なビルドがトリガーされます。 ただし、暗黙的なビルドは、TreatWarningsAsErrors が true ではない場合にのみ最適化されます。 TreatWarningsAsErrors を true に設定したが、暗黙的にトリガーされるビルドを引き続き最適化したい場合は、OptimizeImplicitlyTriggeredBuild を True に設定できます。 暗黙的にトリガーされるビルドに対してビルドの最適化を無効にする場合は、OptimizeImplicitlyTriggeredBuild を False に設定します。

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

DisableRuntimeMarshalling

DisableRuntimeMarshalling プロパティを指定すると、プロジェクトのランタイム マーシャリング サポートを無効にすることができます。 このプロパティを true に設定すると、DisableRuntimeMarshallingAttribute がアセンブリに追加され、P/Invoke またはデリゲート ベースの相互運用機能は、無効になっているランタイム マーシャリングの規則に従います。

<PropertyGroup>
    <DisableRuntimeMarshalling>True</DisableRuntimeMarshalling>
</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 8 にアップグレードしたが、既定のコード分析規則のセットを変更したくない場合は、AnalysisLevel を 7 に設定します。

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

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

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

既定値:

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

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

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

Note

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

AnalysisLevel<Category>

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

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

次の表で利用可能なオプションの値について説明します。 これらは、有効になる規則の数に従って昇順に一覧表示されています。

Value 説明
None すべてのルールが無効になっています。 個々の規則を選択的にオプトインして有効にすることができます。
Default 既定のモードでは、特定のルールがビルド警告として有効になり、特定のルールが Visual Studio IDE の提案として有効になり、残りは無効になります。
Minimum Default モードよりも積極的なモード。 ビルドの実施のために強く推奨される特定の提案が、ビルドの警告として有効になります。 これに含まれる規則を確認するには、%ProgramFiles%/dotnet/sdk/[version]/Sdks/Microsoft.NET.Sdk/analyzers/build/config/analysislevel_[level]_minimum.editorconfig ファイルを調べます。
Recommended Minimum モードよりも積極的なモードであり、より多くの規則がビルド警告として有効になります。 これに含まれる規則を確認するには、%ProgramFiles%/dotnet/sdk/[version]/Sdks/Microsoft.NET.Sdk/analyzers/build/config/analysislevel_[level]_recommended.editorconfig ファイルを調べます。
All すべての規則がビルド警告として有効になっています*。 個々のルールを選択的にオプトアウトして無効にすることができます。

* 次の規則は、AnalysisMode を All に設定するか、AnalysisLevel を latest-all に設定しても有効に "なりません": CA1017、CA1045、CA1005、CA1014、CA1060、CA1021、およびコード メトリック アナライザー規則 (CA1501、CA1502、CA1505、CA1506、CA1509)。 これらのレガシ規則は将来のバージョンで非推奨になる可能性があります。 ただし、dotnet_diagnostic.CAxxxx.severity = <severity> エントリを使って個別に有効にすることはできます。

Note

  • .NET 6 以降は、EnforceCodeStyleInBuild を true に設定した場合、このプロパティは (コード品質規則に加えて) コード スタイル (IDEXXXX) の規則にも影響します。
  • AnalysisLevel に複合値 (例: <AnalysisLevel>8-recommended</AnalysisLevel>) を使用する場合は、このプロパティを完全に省略できます。 ただし、両方のプロパティを指定した場合は、AnalysisLevel が AnalysisMode よりも優先されます。
  • このプロパティは、プロジェクト SDK を参照しないプロジェクト (たとえば、Microsoft. CodeAnalysis. NetAnalyzers NuGet パッケージを参照するレガシ .NET Framework プロジェクト) のコード分析には影響しません。

AnalysisMode<Category>

このプロパティは、コード分析規則の特定のカテゴリにのみ適用される点を除いて、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>

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

_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 パッケージのコード アナライザーのバージョンの使用を続けるには、プロジェクト ファイルで、_SkipUpgradeNetAnalyzersNuGetWarning を true に設定します。

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

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

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

AutoreleasePoolSupport

AutoreleasePoolSupport プロパティは、サポートされている macOS プラットフォームで実行されたときに、各マネージド スレッドが暗黙的な NSAutoreleasePool を受け取るかどうかを構成します。 詳細については、「マネージド スレッドでの AutoreleasePool」を参照してください。

<PropertyGroup>
  <AutoreleasePoolSupport>true</AutoreleasePoolSupport>
</PropertyGroup>

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>

TieredPGO

TieredPGO プロパティは、動的または階層化されたガイド付き最適化のプロファイル (PGO) を有効にするかどうかを制御します。 この値を true に設定すると、階層化された PGO が有効になります。 詳細については、「ガイド付き最適化のプロファイル」を参照してください。

<PropertyGroup>
  <TieredPGO>true</TieredPGO>
</PropertyGroup>

UseWindowsThreadPool

UseWindowsThreadPool プロパティは、スレッド プールのスレッド管理を Windows スレッド プールに委任するかどうかを構成します (Windows のみ)。 既定値は false です。この場合、.NET スレッド プールが使われます。 詳細については、「Windows スレッド プール」を参照してください。

<PropertyGroup>
  <UseWindowsThreadPool>true</UseWindowsThreadPool>
</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 を対象とする場合は、このプロパティによって、System や System.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>

ManagePackageVersionsCentrally

ManagePackageVersionsCentrally プロパティは.NET 7 で導入されました。 リポジトリのルートにある Directory.Packages.props ファイルでこれを true に設定すると、プロジェクト内の共通の依存関係を 1 か所で管理できます。 Directory.Packages.props ファイルの PackageVersion の項目を使って、共通のパッケージ依存関係のバージョンを追加します。 こうすると、個々のプロジェクト ファイルでは、一元管理されているパッケージを参照する PackageReference 項目から Version 属性を省略できるようになります。

Directory.Packages.props ファイルの例:

<PropertyGroup>
  <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
</PropertyGroup>
...
<ItemGroup>
  <PackageVersion Include="Microsoft.Extensions.Configuration" Version="7.0.0" />
</ItemGroup>

個々のプロジェクト ファイル:

<ItemGroup>
  <PackageReference Include="Microsoft.Extensions.Configuration" />
</ItemGroup>

詳細については、中央パッケージ管理 (CPM) に関する記事を参照してください。

参照されたパッケージを復元すると、その直接的な依存関係と間接的な依存関係がすべてインストールされます。 RestorePackagesPath や RestoreIgnoreFailedSources など、プロパティを指定することでパッケージ復元をカスタマイズできます。 以上のプロパティとその他のプロパティの詳細については、「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 サーバーが提供されることを示します。 EnableComHosting を true に設定することは、EnableDynamicLoading が true であることも意味します。

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

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

EnableDynamicLoading

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

  • " .runtimeconfig.json" ファイルが生成される。
  • RollForward は LatestMinor に設定されます。
  • 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 項目はビルド システムへの入力です。 項目は、要素名である型に従って指定されます。 たとえば、Compile と Reference は 2 つの一般的な項目の種類です。 .NET SDK では、次の追加の項目の種類を使用できます。

これらの項目には、標準の項目属性 (Include や Update など) を使用できます。 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) が使用可能な場合は、そのキーが使用されます。 それ以外の場合、属性に公開キーは追加されません。

FrameworkReference

FrameworkReference 項目は、.NET 共有フレームワークへの参照を定義します。

Include 属性は、フレームワーク ID を指定します。

次の例のプロジェクト ファイル スニペットは、Microsoft.AspNetCore.App 共有フレームワークを参照しています。

<ItemGroup>
  <FrameworkReference Include="Microsoft.AspNetCore.App" />
</ItemGroup>

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 によって含められるファイルがソリューション エクスプローラーにどのように表示されるかを示したものです。

Solution Explorer showing item with LinkBase metadata.

関連項目