.NET SDK プロジェクトの MSBuild リファレンス
このページは、.NET プロジェクトの構成に使用できる、MSBuild のプロパティと項目のリファレンスです。
注意
このページの編集は進行中であり、.NET SDK の便利な MSBuild プロパティがすべて記載されている訳ではありません。 一般的な MSBuild プロパティの一覧については、「MSBuild プロジェクトの共通プロパティ」を参照してください。
アセンブリ検証プロパティ
これらのプロパティと項目は、ValidateAssemblies
タスクに渡されます。 アセンブリの検証の詳細については、「アセンブリの検証」を参照してください。
このセクションでは、次の MSBuild プロパティについて説明します。
さらに、「パッケージ検証プロパティ」に記載されている次のプロパティは、アセンブリの検証にも適用されます。
- ApiCompatEnableRuleAttributesMustMatch
- ApiCompatEnableRuleCannotChangeParameterName
- ApiCompatExcludeAttributesFile
- ApiCompatGenerateSuppressionFile
- ApiCompatPermitUnnecessarySuppressions
- ApiCompatPreserveUnnecessarySuppressions
- ApiCompatRespectInternals
- ApiCompatSuppressionFile
- ApiCompatSuppressionOutputFile
- NoWarn
- RoslynAssembliesPath
ApiCompatStrictMode
true
プロパティに設定すると、API 互換性チェックをApiCompatStrictMode
で実行する必要があることが プロパティにより指定されます。
<PropertyGroup>
<ApiCompatStrictMode>true</ApiCompatStrictMode>
</PropertyGroup>
ApiCompatValidateAssemblies
ApiCompatValidateAssemblies
プロパティを使用すると、指定したアセンブリに対して一連の検証を実行できます。 詳細については、「アセンブリ検証」を参照してください。
<PropertyGroup>
<ApiCompatValidateAssemblies>true</ApiCompatValidateAssemblies>
</PropertyGroup>
アセンブリの属性プロパティ
GenerateAssemblyInfo
GenerateAssemblyInfo
プロパティによってプロジェクトの AssemblyInfo
属性の生成を制御できます。 既定値は true
です。 ファイルの生成を無効にするには、false
を使用します。
<PropertyGroup>
<GenerateAssemblyInfo>false</GenerateAssemblyInfo>
</PropertyGroup>
GeneratedAssemblyInfoFile 設定は、生成されるファイルの名前を制御します。
GenerateAssemblyInfo
値が true
の場合、パッケージ関連のプロジェクト プロパティがアセンブリ属性に変換されます。
プロジェクト ファイルを使用してアセンブリ属性を生成する方法の詳細については、「プロジェクト ファイルでアセンブリ属性を設定する」を参照してください。
GeneratedAssemblyInfoFile
GeneratedAssemblyInfoFile
プロパティによって、生成されるアセンブリ情報ファイルの相対パスまたは絶対パスを定義します。 既定値は、 (通常は $(IntermediateOutputPath)
) ディレクトリ内の [プロジェクト名].AssemblyInfo.[cs|vb] という名前のファイルです。
<PropertyGroup>
<GeneratedAssemblyInfoFile>assemblyinfo.cs</GeneratedAssemblyInfoFile>
</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>
パッケージのプロパティ
説明プロパティ
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>
注意
- .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
- ApiCompatEnableRuleCannotChangeParameterName
- ApiCompatExcludeAttributesFile
- ApiCompatGenerateSuppressionFile
- ApiCompatPermitUnnecessarySuppressions
- ApiCompatPreserveUnnecessarySuppressions
- ApiCompatRespectInternals
- ApiCompatSuppressionFile
- ApiCompatSuppressionOutputFile
- EnablePackageValidation
- EnableStrictModeForBaselineValidation
- EnableStrictModeForCompatibleFrameworksInPackage
- EnableStrictModeForCompatibleTfms
- NoWarn
- PackageValidationBaselineFrameworkToIgnore
- PackageValidationBaselineName
- PackageValidationBaselineVersion
- PackageValidationReferencePath
- RoslynAssembliesPath
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
プロパティにより、internal
API に加えて、 public
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 プロパティについて説明します。
- AppendRuntimeIdentifierToOutputPath
- AppendTargetFrameworkToOutputPath
- CopyLocalLockFileAssemblies
- ErrorOnDuplicatePublishOutputFiles
- GenerateRuntimeConfigDevFile
- GenerateRuntimeConfigurationFiles
- GenerateSatelliteAssembliesForCore
- IsPublishable
- PreserveCompilationContext
- PreserveCompilationReferences
- ProduceReferenceAssemblyInOutDir
- PublishDocumentationFile
- PublishDocumentationFiles
- PublishReferencesDocumentationFiles
- PublishRelease
- PublishSelfContained
- RollForward
- RuntimeFrameworkVersion
- RuntimeIdentifier
- RuntimeIdentifiers
- SatelliteResourceLanguages
- SelfContained
- UseAppHost
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 アプリと win-x64
の RID の場合、次の設定では出力パスが bin\Debug\net5.0\win-x64
から bin\Debug\net5.0
に変更されます。
<PropertyGroup>
<AppendRuntimeIdentifierToOutputPath>false</AppendRuntimeIdentifierToOutputPath>
</PropertyGroup>
CopyLocalLockFileAssemblies
CopyLocalLockFileAssemblies
プロパティは、他のライブラリに依存しているプラグイン プロジェクトにとって便利です。 このプロパティを true
に設定すると、推移的な NuGet パッケージの依存関係が出力ディレクトリにコピーされます。 つまり、dotnet build
の出力を使用し、任意のコンピューターでプラグインを実行できます。
<PropertyGroup>
<CopyLocalLockFileAssemblies>true</CopyLocalLockFileAssemblies>
</PropertyGroup>
CopyLocalLockFileAssemblies
の既定値は、出力の種類によって異なる場合があります。 たとえば、クラス ライブラリの場合、既定値は false
、コンソール アプリケーションの場合、既定値は true
。 必要に応じて、このプロパティを明示的に指定して既定値をオーバーライドできます。
ヒント
あるいは、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 を使うと、次の状況で有利になる場合があります。
- C# コンパイラの
deterministic
オプションを使用する必要がある。 - al.exe はパブリック署名をサポートせず、AssemblyInformationalVersionAttribute を適切に処理できないという事実によって制限されている。
<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
ディレクトリにのみ書き込まれます。 参照アセンブリを true
ディレクトリに書き込むには、値を OutDir
に設定します。
<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
プロパティは、既定で dotnet publish
構成の代わりに Release
構成を使用するように Debug
に通知します。 このプロパティは .NET 7 で導入されました。
<PropertyGroup>
<PublishRelease>true</PublishRelease>
</PropertyGroup>
注意
- .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
としてアプリを発行するように に通知します。 このプロパティは、ソリューション レベルで発行する場合など、--self-contained
コマンドに 引数を使用できない場合に便利です。 その場合は、PublishSelfContained
MSBuild プロパティをプロジェクトまたは Directory.Build.Props ファイルに追加できます。
このプロパティは .NET 7 で導入されました。 これは、 動詞に固有である点を除いて、publish
プロパティに似ています。
PublishSelfContained
の代わりに SelfContained
を使用することが推奨されます。
<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
に、自己完結型アプリとしてアプリをビルドまたは発行するように通知します。 このプロパティは、ソリューション レベルで発行する場合など、--self-contained
コマンドで 引数を使用できない場合に便利です。 その場合は、SelfContained
MSBuild プロパティをプロジェクトまたは Directory.Build.Props ファイルに追加できます。
このプロパティは、PublishSelfContained プロパティに似ています。 可能な限り PublishSelfContained
の代わりに SelfContained
を使用することが推奨されます。
<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 |
トリミングの警告をエラーとして扱うかどうかを制御します。 たとえば、false が TreatWarningsAsErrors に設定されている場合は、このプロパティを true に設定することができます。 |
TrimmerSingleWarn |
true または false |
アセンブリごとに 1 つの警告を表示するか、すべての警告を表示するかを制御します。 |
TrimmerRemoveSymbols |
true または false |
トリミングされたアプリケーションからすべてのシンボルを削除するかどうかを制御します。 |
ビルド関連のプロパティ
このセクションでは、次の MSBuild プロパティについて説明します。
- ContinuousIntegrationBuild
- CopyDebugSymbolFilesFromPackages
- CopyDocumentationFilesFromPackages
- DisableImplicitFrameworkDefines
- DocumentationFile
- EmbeddedResourceUseDependentUponConvention
- EnablePreviewFeatures
- EnableWindowsTargeting
- GenerateDocumentationFile
- GenerateRequiresPreviewFeaturesAttribute
- OptimizeImplicitlyTriggeredBuild
- DisableRuntimeMarshalling
LangVersion
や Nullable
などの C# コンパイラ オプションは、プロジェクト ファイルの MSBuild プロパティとして指定することもできます。 詳細については、「C# コンパイラ オプション」を参照してください。
ContinuousIntegrationBuild
ContinuousIntegrationBuild
プロパティは、ビルドが継続的インテグレーション (CI) サーバー上で実行されているかどうかを示します。
true
に設定すると、このプロパティによって、開発者用マシン上のローカル ビルドではなく、公式ビルドにのみ適用される設定が有効になります。 たとえば、格納されたファイルのパスは公式ビルド用に正規化されます。 ただし、ローカル開発マシンでは、ファイル パスが正規化されている場合、デバッガーはローカル ソース ファイルを見つけることができません。
注意
現時点では、このプロパティを 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
に設定され、かつプロジェクト ファイルの LogicalName
項目に ManifestResourceName
、DependentUpon
、EmbeddedResource
のメタデータがどれも指定されていない場合、リソース マニフェストのファイル名は、プロジェクトのルート名前空間と、 .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 プロパティについて説明します。
- DefaultItemExcludesInProjectFolder
- DefaultItemExcludes
- EnableDefaultCompileItems
- EnableDefaultEmbeddedResourceItems
- EnableDefaultItems
- EnableDefaultNoneItems
詳細については、「既定で含まれるものと除外されるもの」を参照してください。
DefaultItemExcludes
DefaultItemExcludes
プロパティを使用して、含まれる、除外される、および削除の glob から除外するファイルとフォルダーの glob パターンを定義します。 既定では、 ./bin および ./obj フォルダーは、glob パターンから除外されます。
<PropertyGroup>
<DefaultItemExcludes>$(DefaultItemExcludes);**/*.myextension</DefaultItemExcludes>
</PropertyGroup>
DefaultItemExcludesInProjectFolder
DefaultItemExcludesInProjectFolder
プロパティを使用して、含まれる、除外される、および削除の glob から除外する、プロジェクト フォルダーのファイルとフォルダーの glob パターンを定義します。 既定では、ピリオド (.
) で始まるフォルダー ( .git や .vs など) は、glob パターンから除外されます。
このプロパティは、プロジェクト フォルダー内のファイルとフォルダーのみが考慮される点を除いて、DefaultItemExcludes
プロパティとよく似ています。 glob パターンが意図せずにプロジェクト フォルダー外の項目と相対パスを照合する場合は、DefaultItemExcludesInProjectFolder
プロパティの代わりに DefaultItemExcludes
プロパティを使用します。
<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<Category>
- AnalysisMode
- AnalysisMode<Category>
- CodeAnalysisTreatWarningsAsErrors
- EnableNETAnalyzers
- EnforceCodeStyleInBuild
- _SkipUpgradeNetAnalyzersNuGetWarning
AnalysisLevel
AnalysisLevel
プロパティを使用すると、.NET リリースに従って実行するコード アナライザーのセットを指定できます。 各 .NET リリースには、一連のコード分析規則があります。 そのセットのうち、そのリリースで既定で有効になっているルールによって、コードが分析されます。 たとえば、.NET 8 から .NET 9 にアップグレードしても、コード分析規則の既定のセットを変更したくない場合は、 AnalysisLevel
を 8
に設定します。
<PropertyGroup>
<AnalysisLevel>8</AnalysisLevel>
</PropertyGroup>
必要に応じて、このプロパティの複合値を指定して、ルールを有効にするアグレッシブな方法を指定することもできます。 複合値は、<version>-<mode>
という形式になります。ここで、<mode>
値は、AnalysisMode 値の 1 つです。 次の例では、コード アナライザーの preview
バージョンを使用し、 recommended
ルールのセットを有効にします。
<PropertyGroup>
<AnalysisLevel>preview-recommended</AnalysisLevel>
</PropertyGroup>
既定値:
- プロジェクトのターゲットが .NET 5.0 以降の場合、または AnalysisMode プロパティを追加した場合、既定値は
latest
になります。 - それ以外の場合、このプロパティは、プロジェクト ファイルに明示的に追加されていない限り省略されます。
次の表は、指定できる値を示しています。
値 | 説明 |
---|---|
latest |
リリースされている最新のコード アナライザーが使用されます。 既定値です。 |
latest-<mode> |
リリースされている最新のコード アナライザーが使用されます。
<mode> 値によって、有効になる規則が決まります。 |
preview |
最新のコード アナライザーが、プレビュー段階であっても使用されます。 |
preview-<mode> |
最新のコード アナライザーが、プレビュー段階であっても使用されます。
<mode> 値によって、有効になる規則が決まります。 |
9.0 |
新しいルールが使用可能な場合でも、.NET 9 リリースで使用できる一連のルールが使用されます。 |
9.0-<mode> |
新しいルールが使用可能な場合でも、.NET 9 リリースで使用できる一連のルールが使用されます。
<mode> 値によって、有効になる規則が決まります。 |
9 |
新しいルールが使用可能な場合でも、.NET 9 リリースで使用できる一連のルールが使用されます。 |
9-<mode> |
新しいルールが使用可能な場合でも、.NET 9 リリースで使用できる一連のルールが使用されます。
<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> 値によって、有効になる規則が決まります。 |
注意
-
EnforceCodeStyleInBuild を
true
に設定した場合、このプロパティは (コード品質規則に加えて) code-style (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>
次の表で利用可能なオプションの値について説明します。 これらは、有効になる規則の数に従って昇順に一覧表示されています。
値 | 説明 |
---|---|
None |
すべてのルールが無効になっています。 個々の規則を選択的にオプトインして有効にすることができます。 |
Default |
既定のモードでは、特定のルールがビルド警告として有効になり、特定のルールが Visual Studio IDE の提案として有効になり、残りは無効になります。 |
Minimum |
Default モードよりも積極的なモード。 ビルドの実施のために強く推奨される特定の提案が、ビルドの警告として有効になります。 これに含まれる規則を確認するには、%ProgramFiles%/dotnet/sdk/[version]/Sdks/Microsoft.NET.Sdk/analyzers/build/config/analysislevel_[level]_minimum.globalconfig ファイルを調べます。 (.NET 7 以前のバージョンの場合、ファイル拡張子は .editorconfig |
Recommended |
Minimum モードよりも積極的なモードであり、より多くの規則がビルド警告として有効になります。 これに含まれる規則を確認するには、%ProgramFiles%/dotnet/sdk/[version]/Sdks/Microsoft.NET.Sdk/analyzers/build/config/analysislevel_[level]_recommended.globalconfig ファイルを調べます。 (.NET 7 以前のバージョンの場合、ファイル拡張子は .editorconfig |
All |
すべての規則がビルド警告として有効になっています*。 個々のルールを選択的にオプトアウトして無効にすることができます。 * 次の規則は、 を AnalysisMode に設定するか、All を AnalysisLevel に設定しても有効に "なりません": CA1017、CA1045、CA1005、CA1014、CA1060、CA1021、およびコード メトリック アナライザー規則 (CA1501、CA1502、CA1505、CA1506、CA1509)。latest-all これらのレガシ規則は将来のバージョンで非推奨になる可能性があります。 ただし、dotnet_diagnostic.CAxxxx.severity = <severity> エントリを使って個別に有効にすることはできます。 |
注意
-
EnforceCodeStyleInBuild を
true
に設定した場合、このプロパティは (コード品質規則に加えて) code-style (IDEXXXX) ルールに影響します。 -
AnalysisLevel に複合値 (例:
<AnalysisLevel>9-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
- ConcurrentGarbageCollection
- InvariantGlobalization
- PredefinedCulturesOnly
- RetainVMGarbageCollection
- ServerGarbageCollection
- ThreadPoolMaxThreads
- ThreadPoolMinThreads
- TieredCompilation
- TieredCompilationQuickJit
- TieredCompilationQuickJitForLoops
- TieredPGO
- UseWindowsThreadPool
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
- DisableImplicitFrameworkReferences
- DisableTransitiveFrameworkReferenceDownloads
- DisableTransitiveProjectReferences
- ManagePackageVersionsCentrally
- 復元関連のプロパティ
- UseMauiEssentials
- ValidateExecutableReferencesMatchSelfContained
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
プロパティにより、暗黙的なプロジェクト参照を制御できます。 暗黙的な true
の項目を無効にするには、このプロパティを ProjectReference
に設定します。 暗黙的なプロジェクト参照を無効にすると、レガシ プロジェクト システムに似た非推移的な動作になります。
このプロパティを true
にすると、依存しているプロジェクトのすべての依存関係に対して PrivateAssets="All"
を設定するのと同様の効果があります。
このプロパティを true
に設定すると、必要なプロジェクトだけに明示的な参照を追加できます。
<PropertyGroup>
<DisableTransitiveProjectReferences>true</DisableTransitiveProjectReferences>
</PropertyGroup>
ManagePackageVersionsCentrally
ManagePackageVersionsCentrally
プロパティは.NET 7 で導入されました。 リポジトリのルートにある true
ファイルでこれを に設定すると、プロジェクト内の共通の依存関係を 1 か所で管理できます。
PackageVersion
ファイルの の項目を使って、共通のパッケージ依存関係のバージョンを追加します。 こうすると、個々のプロジェクト ファイルでは、一元管理されているパッケージを参照する Version
項目から PackageReference
属性を省略できるようになります。
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>
SDK 関連のプロパティ
このセクションでは、次の MSBuild プロパティについて説明します。
SdkAnalysisLevel
.NET 9 で導入された SdkAnalysisLevel
プロパティを使用して、SDK ツールの構成できます。
このプロパティで使用できる値は、8.0.100 や 8.0.400 などの SDK 機能バンドです。 この値の既定値は、実行中の SDK の SDK 機能バンドです。 たとえば、SDK 9.0.102 の場合、値は 9.0.100 になります。 (.NET SDK のバージョン管理方法については、 を参照してください。.NET のバージョン管理方法.)
<PropertyGroup>
<SdkAnalysisLevel>8.0.400</SdkAnalysisLevel>
</PropertyGroup>
詳細については、「 SDK 分析レベルのプロパティと使用法を参照してください。
テストプロジェクト関連のプロパティ
このセクションでは、次の MSBuild プロパティについて説明します。
- IsTestProject
- IsTestingPlatformApplication
- Enable[NugetPackageNameWithoutDots]
- EnableAspireTesting
- EnablePlaywright
- EnableMSTestRunner
- EnableNUnitRunner
- GenerateTestingPlatformEntryPoint
- TestingPlatformCaptureOutput
- TestingPlatformCommandLineArguments
- TestingPlatformDotnetTestSupport
- TestingPlatformShowTestsFailure
- TestingExtensionsProfile
- UseVSTest
IsTestProject
IsTestProject
プロパティは、プロジェクトがテスト プロジェクトであることを示します。 このプロパティを true
に設定すると、プロジェクトが自己完結型実行可能ファイルを参照しているかどうかを確認するための検証が無効になります。 これは、テスト プロジェクトにはOutputType
のExe
がありますが、通常は実行を試みるのではなく、参照先の実行可能ファイルで API を呼び出すからです。 さらに、 IsTestProject
が true
に設定されているプロジェクトをプロジェクトが参照している場合、テスト プロジェクトは実行可能ファイル参照として検証されません。
このプロパティは主に dotnet test
シナリオに必要であり、 vstest.console.exeを使用する場合には影響しません。
注意
プロジェクトで MSTest SDK を指定する場合は、このプロパティを設定する必要はありません。 これは自動的に設定されます。 同様に、このプロパティは、VSTest にリンクされている Microsoft.NET.Test.Sdk NuGet パッケージを参照するプロジェクトに対して自動的に設定されます。
IsTestingPlatformApplication
プロジェクトで Microsoft.Testing.Platform.MSBuild パッケージを参照する場合、 IsTestingPlatformApplication
を true
(指定しない場合は既定値) に設定すると、次の処理が実行されます。
- テスト プロジェクトへのエントリ ポイントを生成します。
- 構成ファイルを生成します。
- 拡張機能を検出します。
プロパティを false
に設定すると、パッケージへの推移的な依存関係が無効になります。
一時的な依存関係は特定のパッケージを参照する別のプロジェクトを参照するプロジェクトが、itがパッケージを参照しているかのように動作する場合です。 通常、このプロパティは、テスト プロジェクトを参照する非テスト プロジェクトで false
するように設定します。 詳細については、「 error CS8892を参照してください。
テスト プロジェクトが MSTest、NUnit、または xUnit を参照している場合、このプロパティは EnableMSTestRunner、 EnableNUnitRunner、または UseMicrosoftTestingPlatformRunner
(xUnit の場合) と同じ値に設定されます。
Enable[NugetPackageNameWithoutDots]
Microsoft.Testing.Platform 拡張機能を有効または無効にするには、パターン Enable[NugetPackageNameWithoutDots]
のプロパティを使用します。
たとえば、クラッシュ ダンプ拡張機能 (NuGet パッケージ Microsoft.Testing.Extensions.CrashDump) を有効にするには、 EnableMicrosoftTestingExtensionsCrashDump
を true
に設定します。
詳細については、「 拡張機能を有効または無効にするを参照してください。
EnableAspireTesting
MSTest プロジェクト SDK を使用する場合は、EnableAspireTesting
プロパティを使用して、using
とAspire
でテストするために必要なすべての依存関係と既定のMSTest
ディレクティブを取り込むことができます。 このプロパティは、MSTest 3.4 以降のバージョンで使用できます。
詳細については、「 Test with .NET Aspire」を参照してください。
EnablePlaywright
MSTest プロジェクト SDK を使用する場合は、EnablePlaywright
プロパティを使用して、using
とPlaywright
でテストするために必要なすべての依存関係と既定のMSTest
ディレクティブを取り込むことができます。このプロパティは、MSTest 3.4 以降のバージョンで使用できます。
詳細については、「 Playwright」を参照してください。
EnableMSTestRunner
EnableMSTestRunner
プロパティは、MSTest ランナーの使用を有効または無効にします。 MSTest ランナーは、VSTest の軽量で移植可能な代替手段です。 このプロパティは、MSTest 3.2 以降のバージョンで使用できます。
注意
プロジェクトで MSTest SDK を指定する場合は、このプロパティを設定する必要はありません。 これは自動的に設定されます。
EnableNUnitRunner
EnableNUnitRunner
プロパティは、NUnit ランナーの使用を有効または無効にします。 NUnit ランナーは、VSTest の軽量で移植可能な代替手段です。 このプロパティは、バージョン 5.0 以降の NUnit3TestAdapter で使用できます。
GenerateTestingPlatformEntryPoint
GenerateTestingPlatformEntryPoint
プロパティを false
に設定すると、MSTest、NUnit、または xUnit テスト プロジェクトのプログラム エントリ ポイントの自動生成が無効になります。 このプロパティは、エントリ ポイントを手動で定義するとき、またはエントリ ポイントも含まれる実行可能ファイルからテスト プロジェクトを参照するときに、 false
に設定できます。
詳細については、「 error CS8892を参照してください。
VSTest プロジェクトのエントリ ポイントの生成を制御するには、 GenerateProgramFile
プロパティを使用します。
TestingPlatformCaptureOutput
TestingPlatformCaptureOutput
プロパティは、dotnet test
を使用してテストを実行するときに、テスト実行可能ファイルが書き込むすべてのコンソール出力をキャプチャして非表示にするかどうかを制御Microsoft.Testing.Platform
。 既定では、コンソール出力は非表示になっています。 この出力には、バナー、バージョン情報、および書式設定されたテスト情報が含まれます。 MSBuild 出力と共にこの情報を表示するには、このプロパティを false
に設定します。
詳細については、「 Show の完全なプラットフォーム出力を参照してください。
TestingPlatformCommandLineArguments
TestingPlatformCaptureOutput
プロパティを使用すると、dotnet test
を使用してテストを実行するときに、テスト アプリにコマンド ライン引数Microsoft.Testing.Platform
指定できます。 次のプロジェクト ファイル スニペットは、例を示しています。
<PropertyGroup>
...
<TestingPlatformCommandLineArguments>--minimum-expected-tests 10</TestingPlatformCommandLineArguments>
</PropertyGroup>
TestingPlatformDotnetTestSupport
TestingPlatformDotnetTestSupport
プロパティを使用すると、dotnet test
を使用してテストを実行するときに VSTest を使用するかどうかを指定できます。 このプロパティを true
に設定すると、VSTest は無効になり、すべての Microsoft.Testing.Platform
テストが直接実行されます。
VSTest テスト プロジェクトと MSTest、NUnit、または XUnit プロジェクトを含むソリューションがある場合は、モードごとに 1 つの呼び出しを行う必要があります (つまり、 dotnet test
は VSTest と新しいプラットフォームの両方から 1 回の呼び出しでテストを実行しません)。
TestingPlatformShowTestsFailure
TestingPlatformShowTestsFailure
プロパティを使用すると、dotnet test
を使用してテストを実行するときに、単一のエラーまたは失敗したテストのすべてのエラーを報告するかどうかを制御できます。 デフォルトでは、テストの失敗は .log ファイルにまとめられ、テスト プロジェクトごとに 1 つの失敗が MSBuild に報告されます。 失敗したテストごとのエラーを表示するには、このプロパティをプロジェクト ファイルで true
に設定します。
TestingExtensionsProfile
MSTest プロジェクト SDK を使用すると、TestingExtensionsProfile
プロパティを使用して、使用するプロファイルを選択できます。 次の表に、許容値を示します。
値 | 説明 |
---|---|
Default |
このバージョンの MSTest.SDK に推奨される拡張機能を有効にします。 |
None |
拡張機能は有効になっていません。 |
AllMicrosoft |
Microsoft から出荷されるすべての拡張機能 (制限付きライセンスを含む) を有効にします。 |
詳細については、 MSTest ランナー プロファイルを参照してください。
UseVSTest
UseVSTest
を使用する場合に MSTest ランナーから true
ランナーに切り替えるには、 プロパティを に設定します。
ホスティング関連のプロパティ
このセクションでは、次の MSBuild プロパティについて説明します。
AppHostDotNetSearch
AppHostDotNetSearch
プロパティはアプリケーション用に生成されたネイティブ実行可能ファイルが .NET インストールを検索する方法を構成します。 このプロパティは、ビルドではなく、発行時に生成された実行可能ファイルにのみ影響します。
<PropertyGroup>
<AppHostDotNetSearch>Global</AppHostDotNetSearch>
</PropertyGroup>
次の表に、有効な値を示します。 複数の値をセミコロンで区切って指定できます。
値 | 説明 |
---|---|
AppLocal |
アプリの実行可能ファイルのフォルダー |
AppRelative |
AppHostRelativeDotNet で指定されたアプリ実行可能ファイルに対する相対パス |
EnvironmentVariables |
DOTNET_ROOT[_<arch>] 環境変数の値 |
Global |
登録 と 既定 グローバル インストールの場所 |
このプロパティは .NET 9 で導入されました。
AppHostRelativeDotNet
AppHostRelativeDotNet
プロパティを使用すると、.NET のインストールを検索するアプリ実行可能ファイルの相対パスを指定構成されます。
AppHostRelativeDotNet
プロパティを設定すると、AppHostDotNetSearch
がAppRelative
。 このプロパティは、ビルドではなく、発行時に生成された実行可能ファイルにのみ影響します。
<PropertyGroup>
<AppHostRelativeDotNet>./relative/path/to/runtime</AppHostRelativeDotNet>
</PropertyGroup>
このプロパティは .NET 9 で導入されました。
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
ディレクティブが追加されます。 暗黙的な true
ディレクティブを有効にするには、このプロパティを enable
または global using
に設定します。 暗黙的な 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 によって含められるファイルがソリューション エクスプローラーにどのように表示されるかを示したものです。
関連項目
.NET