Referenční informace k nástroji MSBuild pro projekty sady .NET SDK

Tato stránka je odkazem na vlastnosti a položky nástroje MSBuild, které můžete použít ke konfiguraci projektů .NET.

Poznámka

Tato stránka je probíhající práce a neobsahuje seznam všech užitečných vlastností nástroje MSBuild pro sadu .NET SDK. Seznam běžných vlastností nástroje MSBuild najdete v tématu Běžné vlastnosti nástroje MSBuild.

Vlastnosti architektury

Následující vlastnosti nástroje MSBuild jsou popsány v této části:

Targetframework

Vlastnost TargetFramework určuje cílovou verzi architektury pro aplikaci. Seznam platných monikerů cílové architektury najdete v tématu Cílové architektury v projektech ve stylu sady SDK.

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

Další informace najdete v tématu Cílové architektury v projektech ve stylu sady SDK.

TargetFrameworks

Vlastnost použijte, TargetFrameworks pokud chcete, aby vaše aplikace cílila na více platforem. Seznam platných monikerů cílové architektury najdete v tématu Cílové architektury v projektech ve stylu sady SDK.

Poznámka

Tato vlastnost je ignorována, pokud TargetFramework je zadán (singulární).

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

Další informace najdete v tématu Cílové architektury v projektech ve stylu sady SDK.

NetStandardImplicitPackageVersion

Poznámka

Tato vlastnost se vztahuje pouze na projekty používající netstandard1.x. Nevztahuje se na projekty, které používají netstandard2.x.

Vlastnost použijte, NetStandardImplicitPackageVersion pokud chcete zadat verzi architektury, která je nižší než verze metabalíku. Soubor projektu v následujícím příkladu cílí netstandard1.3 , ale používá verzi 1.6.0 nástroje NETStandard.Library.

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

Vlastnosti atributu sestavení

GenerateAssemblyInfo

Vlastnost GenerateAssemblyInfo řídí AssemblyInfo generování atributů pro projekt. Výchozí hodnota je true. Použití false k zakázání generování souboru:

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

Nastavení GeneratedAssemblyInfoFile řídí název vygenerovaného souboru.

Pokud je truehodnota GenerateAssemblyInfo , vlastnosti projektu související s balíčkem se transformují na atributy sestavení. Následující tabulka uvádí vlastnosti projektu, které generují atributy. Obsahuje také seznam vlastností, které můžete použít k zakázání generování pro jednotlivé atributy, například:

<PropertyGroup>
  <GenerateNeutralResourcesLanguageAttribute>false</GenerateNeutralResourcesLanguageAttribute>
</PropertyGroup>
Vlastnost MSBuild Atribut sestavení Vlastnost pro zakázání generování atributů
Company AssemblyCompanyAttribute GenerateAssemblyCompanyAttribute
Configuration AssemblyConfigurationAttribute GenerateAssemblyConfigurationAttribute
Copyright AssemblyCopyrightAttribute GenerateAssemblyCopyrightAttribute
Description AssemblyDescriptionAttribute GenerateAssemblyDescriptionAttribute
FileVersion AssemblyFileVersionAttribute GenerateAssemblyFileVersionAttribute
InformationalVersion AssemblyInformationalVersionAttribute GenerateAssemblyInformationalVersionAttribute
Product AssemblyProductAttribute GenerateAssemblyProductAttribute
AssemblyTitle AssemblyTitleAttribute GenerateAssemblyTitleAttribute
AssemblyVersion AssemblyVersionAttribute GenerateAssemblyVersionAttribute
NeutralLanguage NeutralResourcesLanguageAttribute GenerateNeutralResourcesLanguageAttribute

Poznámky k těmto nastavením:

  • AssemblyVersion a FileVersion ve výchozím nastavení na hodnotu $(Version) bez přípony. Pokud $(Version) je 1.2.3-beta.4například , hodnota by byla 1.2.3.
  • InformationalVersionvýchozí hodnota je .$(Version)
  • Pokud vlastnost $(SourceRevisionId) existuje, připojí se k InformationalVersion. Toto chování můžete zakázat pomocí .IncludeSourceRevisionInInformationalVersion
  • Copyright vlastnosti a Description se používají také pro metadata NuGet.
  • Configuration, který má výchozí hodnotu Debug, se sdílí se všemi cíli NÁSTROJE MSBuild. Můžete ho dotnet nastavit pomocí --configuration možnosti příkazů, například dotnet pack.
  • Některé z vlastností se používají při vytváření balíčku NuGet. Další informace najdete v tématu Vlastnosti balíčku.

Migrace z rozhraní .NET Framework

Šablony projektů rozhraní .NET Framework vytvoří soubor kódu s těmito atributy informací o sestavení. Soubor se obvykle nachází na adrese .\Properties\AssemblyInfo.cs nebo .\Properties\AssemblyInfo.vb. Projekty ve stylu sady SDK vygenerují tento soubor za vás na základě nastavení projektu. Nemůžete mít obojí. Při přenosu kódu do .NET 5 (nebo .NET Core 3.1) nebo novějšího proveďte jednu z těchto věcí:

  • Zakažte generování dočasného souboru kódu, který obsahuje atributy informací o sestavení, nastavením GenerateAssemblyInfo na hodnotu false v souboru projektu. To vám umožní zachovat soubor AssemblyInfo .
  • Migrujte nastavení v AssemblyInfo souboru do souboru projektu a pak soubor odstraňte AssemblyInfo .

GeneratedAssemblyInfoFile

Vlastnost GeneratedAssemblyInfoFile definuje relativní nebo absolutní cestu vygenerovaného souboru s informacemi o sestavení. Výchozí hodnota je soubor s názvem [název_projektu]. Assemblyinfo. [cs|vb] v adresáři $(IntermediateOutputPath) (obvykle obj).

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

Vlastnosti balíčku

Popisné vlastnosti

Můžete zadat vlastnosti, jako PackageIdjsou , PackageVersion, PackageIconTitlea Description a k popisu balíčku, který se vytvoří z projektu. Informace o těchto a dalších vlastnostech najdete v tématu Cíl balíčku.

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

BalíčekRelease

Vlastnost PackRelease je podobná vlastnosti PublishRelease s tím rozdílem, že mění výchozí chování objektu dotnet pack.

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

Poznámka

Pokud chcete použít PackRelease v projektu, který je součástí řešení sady Visual Studio, musíte nastavit proměnnou DOTNET_CLI_ENABLE_PACK_RELEASE_FOR_SOLUTIONS prostředí na true hodnotu (nebo jinou hodnotu). Nastavením této proměnné se zvýší doba potřebná k zabalení řešení s mnoha projekty.

Následující vlastnosti nástroje MSBuild jsou popsány v této části:

AppendTargetFrameworkToOutputPath

Vlastnost AppendTargetFrameworkToOutputPath určuje, jestli se k výstupní cestě (definované pomocí OutputPath) připojí cílový moniker architektury (TFM). Sada .NET SDK automaticky připojí k výstupní cestě cílovou architekturu a pokud je k dispozici identifikátor modulu runtime. Nastavení AppendTargetFrameworkToOutputPath na zabrání false připojení TFM k výstupní cestě. Bez TFM ve výstupní cestě se však může navzájem přepsat několik artefaktů sestavení.

Například u aplikace .NET 5 se výstupní cesta změní z bin\Debug\net5.0 na bin\Debug s následujícím nastavením:

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

AppendRuntimeIdentifierToOutputPath

Vlastnost AppendRuntimeIdentifierToOutputPath určuje, jestli se identifikátor modulu runtime (RID) připojí k výstupní cestě. Sada .NET SDK automaticky připojí k výstupní cestě cílovou architekturu a pokud je k dispozici identifikátor modulu runtime. Nastavení AppendRuntimeIdentifierToOutputPath na false hodnotu brání připojení identifikátoru RID k výstupní cestě.

Například pro aplikaci .NET 5 a identifikátor RID se win10-x64výstupní cesta změní z bin\Debug\net5.0\win10-x64 na bin\Debug\net5.0 s následujícím nastavením:

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

CopyLocalLockFileAssemblies

Vlastnost CopyLocalLockFileAssemblies je užitečná pro projekty modulů plug-in, které mají závislosti na jiných knihovnách. Pokud tuto vlastnost nastavíte na true, zkopírují se do výstupního adresáře všechny závislosti balíčků NuGet. To znamená, že výstup dotnet build můžete použít ke spuštění modulu plug-in na libovolném počítači.

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

Tip

Případně můžete použít k dotnet publish publikování knihovny tříd. Další informace najdete v tématu dotnet publish.

ErrorOnDuplicatePublishOutputFiles

Vlastnost ErrorOnDuplicatePublishOutputFiles souvisí s tím, jestli sada SDK vygeneruje chybu NETSDK1148, když nástroj MSBuild zjistí ve výstupu publikování duplicitní soubory, ale nemůže určit, které soubory se mají odebrat. ErrorOnDuplicatePublishOutputFiles Pokud nechcete, aby se chyba vygenerovala, nastavte vlastnost na false hodnotu .

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

Tato vlastnost byla zavedena v .NET 6.

EnablePackageValidation

Vlastnost EnablePackageValidation povoluje řadu ověření v balíčku po pack provedení úlohy. Další informace najdete v tématu Ověření balíčku.

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

Tato vlastnost byla zavedena v .NET 6.

GenerateRuntimeConfigDevFile

Počínaje sadou .NET 6 SDK se soubor [Appname].runtimesettings.dev.json už při kompilaci ve výchozím nastavení negeneruje . Pokud chcete, aby se tento soubor stále vygeneroval, nastavte GenerateRuntimeConfigDevFile vlastnost na true.

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

GenerateRuntimeConfigurationFiles

Vlastnost GenerateRuntimeConfigurationFiles určuje, jestli se možnosti konfigurace modulu runtime zkopírují ze souboru runtimeconfig.template.json do souboru [název_aplikace].runtimeconfig.json . U aplikací, které vyžadují soubor runtimeconfig.json , tedy těch, jejichž OutputType je Exe, se tato vlastnost ve výchozím nastavení nastaví na true.

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

GenerateSatelliteAssembliesForCore

Vlastnost GenerateSatelliteAssembliesForCore určuje, zda jsou satelitní sestavení generována pomocí csc.exe nebo Al.exe (Assembly Linker) v projektech rozhraní .NET Framework. (Projekty .NET Core a .NET 5+ vždy používají csc.exe ke generování satelitních sestavení.) U projektů rozhraní .NET Framework jsou satelitní sestavení ve výchozím nastavení vytvářena al.exe. GenerateSatelliteAssembliesForCore Nastavením vlastnosti na truejsou satelitní sestavení vytvářena csc.exe místo toho. Použití csc.exe může být výhodné v následujících situacích:

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

IsPublishable

Vlastnost IsPublishable umožňuje Publish spuštění cíle. Tato vlastnost ovlivňuje pouze procesy, které používají soubory .*proj a Publish cíl, například příkaz dotnet publish . Nemá vliv na publikování v sadě Visual Studio, která používá PublishOnly cíl. Výchozí hodnota je true.

Tato vlastnost je užitečná, pokud spouštíte dotnet publish soubor řešení, protože umožňuje automatický výběr projektů, které mají být publikovány.

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

PreserveCompilationContext

Vlastnost PreserveCompilationContext umožňuje sestavené nebo publikované aplikaci kompilovat více kódu za běhu pomocí stejných nastavení, která byla použita při sestavení. Sestavení odkazovaná při sestavení budou zkopírována do podadresáře ref výstupního adresáře. Názvy referenčních sestavení jsou uloženy v souboru .deps.json aplikace spolu s možnostmi předanými kompilátoru. Tyto informace můžete načíst pomocí DependencyContext.CompileLibraries vlastností a DependencyContext.CompilationOptions .

Tuto funkci nejčastěji interně používají ASP.NET Core MVC a Razor Pages k podpoře kompilace souborů Razor za běhu.

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

PreserveCompilationReferences

Vlastnost PreserveCompilationReferences je podobná vlastnosti PreserveCompilationContext s tím rozdílem, že kopíruje pouze odkazovaná sestavení do adresáře publish, a ne do souboru .deps.json .

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

Další informace najdete v tématu Vlastnosti sady Razor SDK.

ProduceReferenceAssemblyInOutDir

V .NET 5 a starších verzích se referenční sestavení vždy zapisují do OutDir adresáře . V rozhraní .NET 6 a novějších verzích můžete pomocí ProduceReferenceAssemblyInOutDir vlastnosti řídit, zda jsou referenční sestavení zapsána do OutDir adresáře. Výchozí hodnota je falsea referenční sestavení se zapisují pouze do IntermediateOutputPath adresáře . Nastavte hodnotu na pro true zápis referenčních sestavení do OutDir adresáře.

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

Další informace najdete v tématu Zápis referenčních sestavení do zprostředkujícího výstupu.

PublishDocumentationFile

Pokud je truetato vlastnost , soubor dokumentace XML pro projekt, pokud je vygenerován, je součástí výstupu publikování projektu. Výchozí hodnota této vlastnosti je true.

Tip

Pokud chcete vygenerovat soubor dokumentace XML při kompilaci, true nastavte GenerateDocumentationFile na hodnotu .

PublishDocumentationFiles

Tato vlastnost je příznak povolení pro několik dalších vlastností, které řídí, zda jsou různé druhy souborů dokumentace XML zkopírovány do adresáře publish ve výchozím nastavení, konkrétně PublishDocumentationFile a PublishReferencesDocumentationFiles. Pokud jsou tyto vlastnosti nenastavěné a tato vlastnost je nastavená, budou tyto vlastnosti ve výchozím nastavení nastaveny na true. Výchozí hodnota této vlastnosti je true.

PublishReferencesDocumentationFiles

Pokud je truetato vlastnost nastavená na , soubory dokumentace XML pro odkazy projektu se zkopírují do adresáře publish místo jen prostředků za běhu, jako jsou soubory DLL. Výchozí hodnota této vlastnosti je true.

PublikovatRelease

Vlastnost PublishRelease informuje, dotnet publish že se má použít Release konfigurace ve výchozím nastavení místo Debug konfigurace.

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

Poznámka

  • Tato vlastnost nemá vliv na chování dotnet build /t:Publish a mění konfiguraci pouze při publikování přes .NET CLI.
  • Pokud chcete použít PublishRelease v projektu, který je součástí řešení sady Visual Studio, musíte nastavit proměnnou DOTNET_CLI_ENABLE_PUBLISH_RELEASE_FOR_SOLUTIONS prostředí na true (nebo jinou hodnotu). Tím se zkrátí čas potřebný k publikování řešení, která mají mnoho projektů. Při publikování řešení s povolenou touto proměnnou má přednost hodnota spustitelného projektu PublishRelease a přenese novou výchozí konfiguraci do všech ostatních projektů v řešení. Pokud řešení obsahuje více spustitelných projektů nebo projektů nejvyšší úrovně s různými hodnotami PublishRelease, řešení se úspěšně nepublikuje.

RollForward

Vlastnost RollForward určuje, jak aplikace zvolí modul runtime, když je k dispozici více verzí modulu runtime. Tato hodnota je výstupem do souboru .runtimeconfig.json jako rollForward nastavení.

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

Nastavte RollForward jednu z následujících hodnot:

Hodnota Popis
Minor Výchozí hodnota, pokud není zadána.
Pokud chybí požadovaná podverze, přejděte k nejnižší vyšší podverzi. Pokud požadovaná podverze existuje, použije se LatestPatch zásada.
Major Pokud požadovaná hlavní verze chybí, přejděte na další dostupnou vyšší hlavní verzi a nejnižší podverzi. Pokud je požadovaná hlavní verze k dispozici, použijí se Minor zásady.
LatestPatch Přejděte k nejvyšší verzi opravy. Tato hodnota zakáže přechod do dalšího stavu podverze.
LatestMinor Přechod na nejvyšší podverzi, a to i v případě, že požadovaná podverze existuje.
LatestMajor Přechod na nejvyšší hlavní a nejvyšší podverzi, a to i v případě, že je požadovaná hlavní verze k dispozici.
Disable Nepřecházejte dopředu, pouze vazbu na zadanou verzi. Tato zásada se nedoporučuje používat obecně, protože zakazuje přechod k nejnovějším opravám. Tato hodnota se doporučuje pouze pro testování.

Další informace najdete v tématu Řízení chování při postupném posouvání.

RuntimeFrameworkVersion

Vlastnost RuntimeFrameworkVersion určuje verzi modulu runtime, který se má použít při publikování. Zadejte verzi modulu runtime:

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

Při publikování aplikace závislé na architektuře tato hodnota určuje minimální požadovanou verzi. Při publikování samostatné aplikace určuje tato hodnota přesnou požadovanou verzi.

Identifikátor modulu runtime

Vlastnost RuntimeIdentifier umožňuje zadat jeden identifikátor modulu runtime (RID) pro projekt. Identifikátor RID umožňuje publikování samostatného nasazení.

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

RuntimeIdentifiers

Vlastnost RuntimeIdentifiers umožňuje zadat seznam identifikátorů modulu runtime (RID) oddělených středníkem pro projekt. Tuto vlastnost použijte, pokud potřebujete publikovat pro více modulů runtime. RuntimeIdentifiers se používá v době obnovení, aby se zajistilo, že jsou v grafu správné prostředky.

Tip

RuntimeIdentifier (jednotné číslo) může poskytovat rychlejší sestavení, když je vyžadován pouze jeden modul runtime.

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

SatelliteResourceLanguages

Vlastnost SatelliteResourceLanguages umožňuje určit, které jazyky chcete během sestavování a publikování zachovat pro sestavení satelitních prostředků. Mnoho balíčků NuGet obsahuje lokalizovaná satelitní sestavení prostředků v hlavním balíčku. U projektů, které odkazují na tyto balíčky NuGet, které nevyžadují lokalizované prostředky, mohou lokalizovaná sestavení zbytečně nafukovat velikost výstupu sestavení a publikování. Přidáním SatelliteResourceLanguages vlastnosti do souboru projektu budou do výstupu sestavení a publikování zahrnuta pouze lokalizovaná sestavení pro jazyky, které zadáte. Například v následujícím souboru projektu budou zachována pouze anglická (US) a německá (Německo) satelitní sestavení zdrojů.

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

Poznámka

  • Tuto vlastnost musíte zadat v projektu, který odkazuje na balíček NuGet s lokalizovanými satelitními sestaveními prostředků.

  • Pokud chcete jako argument zadat více jazyků, dotnet publishmusíte přidat tři dvojice uvozovek kolem identifikátorů jazyka. Příklad:

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

PoužítAppHost

Vlastnost UseAppHost určuje, jestli se pro nasazení vytvoří nativní spustitelný soubor. Pro samostatná nasazení se vyžaduje nativní spustitelný soubor.

V .NET Core 3.0 a novějších verzích se ve výchozím nastavení vytvoří spustitelný soubor závislý na architektuře. UseAppHost Pokud chcete zakázat generování spustitelného souboru, nastavte vlastnost na false hodnotu .

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

Další informace o nasazení najdete v tématu Nasazení aplikace .NET.

Pro vyladění ořezávání je k dispozici mnoho vlastností nástroje MSBuild, což je funkce, která ořízá nepoužívaný kód z samostatných nasazení. Tyto možnosti jsou podrobně popsány v tématu Možnosti oříznutí. Následující tabulka obsahuje stručný přehled.

Vlastnost Hodnoty Popis
PublishTrimmed true nebo false Určuje, jestli je během publikování povolené oříznutí.
TrimMode full nebo partial Výchozí je full. Řídí členitost oříznutí.
SuppressTrimAnalysisWarnings true nebo false Určuje, jestli se vytvářejí upozornění analýzy oříznutí.
EnableTrimAnalyzer true nebo false Určuje, jestli se vytvoří podmnožina upozornění analýzy oříznutí. Analýzu můžete povolit, i když PublishTrimmed je nastavená na false.
ILLinkTreatWarningsAsErrors true nebo false Určuje, jestli se upozornění na oříznutí považují za chyby. Tuto vlastnost můžete například chtít nastavit na false hodnotu , když TreatWarningsAsErrors je nastavená na truehodnotu .
TrimmerSingleWarn true nebo false Určuje, zda se zobrazí jedno upozornění na sestavení nebo všechna upozornění.
TrimmerRemoveSymbols true nebo false Určuje, jestli se z oříznuté aplikace odeberou všechny symboly.

V této části jsou popsány následující vlastnosti nástroje MSBuild:

Možnosti kompilátoru jazyka C#, například LangVersion a Nullable, lze také zadat jako vlastnosti nástroje MSBuild v souboru projektu. Další informace najdete v tématu Možnosti kompilátoru jazyka C#.

CopyDebugSymbolFilesFromPackages

Pokud je tato vlastnost nastavená na truehodnotu , zkopírují se do výstupu sestavení všechny soubory symbolů (označované také jako soubory PDB) z PackageReference položek v projektu. Tyto soubory poskytují informativnější trasování zásobníku pro výjimky a usnadňují pochopení výpisů paměti a trasování spuštěné aplikace. Pokud ale tyto soubory zahrnete, zvětší se velikost sady nasazení.

Tato vlastnost byla zavedena v sadě .NET SDK 7.0.100, i když se ve výchozím nastavení nezadá.

CopyDocumentationFilesFromPackages

Pokud je tato vlastnost nastavena na truehodnotu , všechny vygenerované soubory dokumentace XML z PackageReference položek v projektu se zkopírují do výstupu sestavení. Upozorňujeme, že povolením této funkce se zvětší velikost sady nasazení.

Tato vlastnost byla zavedena v sadě .NET SDK 7.0.100, i když se ve výchozím nastavení nezadá.

DisableImplicitFrameworkDefines

Vlastnost DisableImplicitFrameworkDefines určuje, jestli sada SDK generuje symboly preprocesoru pro cílovou architekturu a platformu pro projekt .NET. Pokud je tato vlastnost nastavená na false hodnotu nebo není nastavená (což je výchozí hodnota), vygenerují se symboly preprocesoru pro:

  • Architektura bez verze (NETFRAMEWORK, NETSTANDARD, NET)
  • Architektura s verzí (NET48, NETSTANDARD2_0, NET6_0)
  • Architektura s minimální vazbou verze (NET48_OR_GREATER, NETSTANDARD2_0_OR_GREATER, NET6_0_OR_GREATER)

Další informace o cílových rozhraních a těchto implicitních symbolech preprocesoru najdete v tématu Cílové architektury.

Pokud navíc v projektu zadáte cílovou architekturu specifickou pro operační systém (například net6.0-android), vygenerují se následující symboly preprocesoru:

  • Platforma bez verze (ANDROID, IOS, WINDOWS)
  • Platforma s verzí (IOS15_1)
  • Platforma s minimální vazbou verze (IOS15_1_OR_GREATER)

Další informace o možnostech cílových architektur specifických pro operační systém najdete v tématu TFM specifické pro operační systém.

A konečně, pokud cílová architektura předpokládá podporu starších cílových architektur, vygenerují se symboly preprocesoru pro tyto starší architektury. Například net6.0implikuje podporu pro net5.0 a tak dále celou cestu zpět na .netcoreapp1.0. Pro každou z těchto cílových architektur se tedy definuje architektura se symbolem minimální vazby verze .

Soubor dokumentace

Vlastnost DocumentationFile umožňuje zadat název souboru XML, který obsahuje dokumentaci pro vaši knihovnu. Aby technologie IntelliSense fungovala správně s dokumentací, musí být název souboru stejný jako název sestavení a musí být ve stejném adresáři jako sestavení. Pokud tuto vlastnost nezadáte, ale nastavíte GenerateDocumentationFile na truehodnotu , název souboru dokumentace bude ve výchozím nastavení název sestavení, ale s příponou souboru.xml . Z tohoto důvodu je často jednodušší tuto vlastnost vynechat a místo toho použít vlastnost GenerateDocumentationFile .

Pokud zadáte tuto vlastnost, ale nastavíte GenerateDocumentationFile na false, kompilátor negeneruje soubor dokumentace. Pokud zadáte tuto vlastnost a vynecháte GenerateDocumentationFile vlastnost, kompilátor vygeneruje soubor dokumentace.

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

EmbeddedResourceUseDependentUponConvention

Vlastnost EmbeddedResourceUseDependentUponConvention definuje, jestli jsou názvy souborů manifestu prostředků generovány z informací o typu ve zdrojových souborech, které jsou umístěny společně se soubory prostředků. Pokud je například Form1.resx ve stejné složce jako Form1.cs a EmbeddedResourceUseDependentUponConvention je nastavený na true, vygenerovaný soubor .resources převezme název od prvního typu definovaného v souboru Form1.cs. Pokud MyNamespace.Form1 je například první typ definovaný v souboru Form1.cs, název vygenerovaného souboru je MyNamespace.Form1.resources.

Poznámka

Pokud LogicalNamejsou pro EmbeddedResource položku zadána metadata , ManifestResourceNamenebo DependentUpon , je název vygenerovaného souboru manifestu pro tento soubor prostředků založený na metadatech.

Ve výchozím nastavení je v novém projektu .NET tato vlastnost nastavená na truehodnotu . Pokud je pro EmbeddedResource položku v souboru projektu nastavená falsehodnota , a DependentUpon pro LogicalNameManifestResourceNamepoložku v souboru projektu nejsou zadána žádná metadata, název souboru manifestu prostředku vychází z kořenového oboru názvů projektu a relativní cesty k souboru .resx. Další informace najdete v tématu Název souborů manifestu prostředků.

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

EnablePreviewFeatures

Vlastnost EnablePreviewFeatures definuje, jestli projekt závisí na jakýchkoli rozhraních API nebo sestaveních, která jsou opatřena atributem RequiresPreviewFeaturesAttribute . Tento atribut se používá k označení, že rozhraní API nebo sestavení používá funkce, které jsou považovány za ve verzi Preview pro verzi sady SDK, kterou používáte. Funkce Preview nejsou podporované a v budoucí verzi je možné je odebrat. Pokud chcete povolit použití funkcí Preview, nastavte vlastnost na True.

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

Pokud projekt obsahuje tuto vlastnost nastavenou na Truehodnotu , přidá se do souboru AssemblyInfo.cs následující atribut na úrovni sestavení:

[assembly: RequiresPreviewFeatures]

Analyzátor upozorní, pokud tento atribut existuje u závislostí pro projekty, u kterých EnablePreviewFeatures není nastavená hodnota True.

Autoři knihoven, kteří mají v úmyslu dodávat sestavení verze Preview, by měli tuto vlastnost nastavit na True. Pokud se sestavení musí dodávat se kombinací rozhraní API verze Preview a jiných než Preview, přečtěte si část GenerateRequiresPreviewFeaturesAttribute níže.

EnableWindowsTargeting

EnableWindowsTargeting Pokud chcete vytvářet aplikace pro Windows (například model Windows Forms nebo Windows Presentation Foundation aplikace) na jiné platformě než Windows, nastavte vlastnost true na hodnotu . Pokud tuto vlastnost nenastavíte na true, zobrazí se upozornění na sestavení NETSDK1100. K této chybě dochází, protože cílení a balíčky runtime se automaticky nestáhnou na nepodporovaných platformách. Nastavením této vlastnosti se tyto balíčky stáhnou při křížovému cílení.

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

GenerateDocumentationFile

Vlastnost GenerateDocumentationFile určuje, jestli kompilátor vygeneruje soubor dokumentace XML pro vaši knihovnu. Pokud nastavíte tuto vlastnost na true a nezadáte název souboru prostřednictvím vlastnosti DocumentationFile, vygenerovaný soubor XML se umístí do stejného výstupního adresáře jako sestavení a má stejný název souboru (ale s příponou .xml ).

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

Další informace o generování dokumentace z komentářů ke kódu najdete v tématech Komentáře dokumentace XML (C#),Dokumentujte kód pomocí XML (Visual Basic) nebo Dokumentujte kód pomocí XML (F#).

GenerateRequiresPreviewFeaturesAttribute

Vlastnost GenerateRequiresPreviewFeaturesAttribute úzce souvisí s vlastností EnablePreviewFeatures . Pokud vaše knihovna používá funkce ve verzi Preview, ale nechcete, aby bylo celé sestavení označeno atributem RequiresPreviewFeaturesAttribute , který by vyžadoval povolení funkcí ve verzi Preview pro všechny uživatele, nastavte tuto vlastnost na Falsehodnotu .

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

Důležité

Pokud vlastnost nastavíte GenerateRequiresPreviewFeaturesAttribute na False, musíte si být jistí, že vyzdobit všechna veřejná rozhraní API, která využívají funkce Preview s RequiresPreviewFeaturesAttributenástrojem .

OptimizeImplicitlyTriggeredBuild

Aby se urychlila doba sestavení, přeskočí sestavení, která jsou implicitně aktivovaná sadou Visual Studio, analýzu kódu, včetně analýzy s možnou hodnotou null. Visual Studio například při spuštění testů aktivuje implicitní sestavení. Implicitní sestavení se ale optimalizují jenom v případě, že TreatWarningsAsErrors není true. Pokud jste nastavili TreatWarningsAsErrors na true , ale přesto chcete, aby se implicitně aktivovaná sestavení optimalizovala, můžete nastavit OptimizeImplicitlyTriggeredBuild na True. Pokud chcete vypnout optimalizaci sestavení pro implicitně aktivovaná sestavení, nastavte OptimizeImplicitlyTriggeredBuild na False.

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

Výchozí vlastnosti zahrnutí položek

V této části jsou popsány následující vlastnosti nástroje MSBuild:

Další informace najdete v tématu Výchozí zahrnutí a vyloučení.

DefaultItemExcludes

DefaultItemExcludes Pomocí vlastnosti definujte vzory globů pro soubory a složky, které by měly být vyloučeny z zahrnutí, vyloučení a odebrání globů. Ve výchozím nastavení jsou složky ./bin a ./obj vyloučené ze vzorů globů.

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

DefaultItemExcludesInProjectFolder

DefaultItemExcludesInProjectFolder Vlastnost slouží k definování vzorů globů pro soubory a složky ve složce projektu, které by měly být vyloučeny z zahrnutí, vyloučení a odebrání globů. Ve výchozím nastavení jsou složky, které začínají tečkou (.), jako jsou .git a .vs, vyloučené ze vzorů globů.

Tato vlastnost je velmi podobná vlastnosti s tím rozdílem DefaultItemExcludes , že bere v úvahu pouze soubory a složky ve složce projektu. Pokud by vzor globu neúmyslně spároval položky mimo složku projektu s relativní cestou, použijte DefaultItemExcludesInProjectFolder místo DefaultItemExcludes vlastnosti vlastnost .

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

EnableDefaultItems

Vlastnost EnableDefaultItems určuje, jestli jsou do projektu implicitně zahrnuty položky kompilace, vložené položky prostředků a None položky. Výchozí hodnota je true. EnableDefaultItems Nastavením vlastnosti na hodnotu false zakážete všechna implicitní zahrnutí souborů.

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

EnableDefaultCompileItems

Vlastnost EnableDefaultCompileItems určuje, jestli jsou položky kompilace implicitně zahrnuty do projektu. Výchozí hodnota je true. Nastavením vlastnosti na EnableDefaultCompileItems zakážete false implicitní zahrnutí souboru *.cs a dalších souborů s příponou jazyka.

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

EnableDefaultEmbeddedResourceItems

Vlastnost EnableDefaultEmbeddedResourceItems určuje, jestli jsou vložené položky prostředků implicitně zahrnuty do projektu. Výchozí hodnota je true. EnableDefaultEmbeddedResourceItems Pokud chcete zakázat implicitní zahrnutí vložených souborů prostředků, nastavte vlastnost na false hodnotu .

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

EnableDefaultNoneItems

Vlastnost EnableDefaultNoneItems určuje, jestli None jsou položky (soubory, které nemají v procesu sestavení žádnou roli) implicitně zahrnuty do projektu. Výchozí hodnota je true. EnableDefaultNoneItems Pokud chcete zakázat implicitní None zahrnutí položek, nastavte vlastnost na false hodnotu .

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

Vlastnosti analýzy kódu

V této části jsou popsány následující vlastnosti nástroje MSBuild:

AnalysisLevel

Vlastnost AnalysisLevel umožňuje určit sadu analyzátorů kódu, které se mají spustit podle verze .NET. Každá verze .NET, počínaje verzí .NET 5, obsahuje sadu pravidel analýzy kódu. Z této sady budou kód analyzovat pravidla, která jsou ve výchozím nastavení pro danou verzi povolená. Pokud například upgradujete na .NET 7, ale nechcete, aby se výchozí sada pravidel analýzy kódu změnila, nastavte AnalysisLevel na 6.

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

Volitelně můžete od verze .NET 6 zadat složenou hodnotu pro tuto vlastnost, která také určuje, jak agresivně povolit pravidla. Složené hodnoty mají tvar <version>-<mode>, kde <mode> hodnota je jednou z hodnot AnalysisMode . Následující příklad používá verzi Preview analyzátorů kódu a povoluje doporučenou sadu pravidel.

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

Poznámka

Pokud nastavíte AnalysisLevel nebo 5-<mode>5.0-<mode> a pak nainstalujete sadu .NET 6 SDK a projekt znovu zkompilujete, můžou se zobrazit neočekávaná upozornění na nové sestavení. Další informace najdete v tématu dotnet/roslyn-analyzers#5679.

Výchozí hodnota:

  • Pokud projekt cílí na .NET 5 nebo novější nebo pokud jste přidali vlastnost AnalysisMode , výchozí hodnota je latest.
  • V opačném případě je tato vlastnost vynechána, pokud ji explicitně nepřidáte do souboru projektu.

Následující tabulka uvádí hodnoty, které můžete zadat.

Hodnota Význam
latest Používají se nejnovější analyzátory kódu, které byly vydány. Tato možnost je výchozí.
latest-<mode> Používají se nejnovější analyzátory kódu, které byly vydány. Hodnota <mode> určuje, která pravidla jsou povolená.
preview Používají se nejnovější analyzátory kódu, i když jsou ve verzi Preview.
preview-<mode> Používají se nejnovější analyzátory kódu, i když jsou ve verzi Preview. Hodnota <mode> určuje, která pravidla jsou povolená.
7.0 Použije se sada pravidel, která byla k dispozici pro verzi .NET 7, i když jsou k dispozici novější pravidla.
7.0-<mode> Použije se sada pravidel, která byla k dispozici pro verzi .NET 7, i když jsou k dispozici novější pravidla. Hodnota <mode> určuje, která pravidla jsou povolená.
7 Použije se sada pravidel, která byla k dispozici pro verzi .NET 7, i když jsou k dispozici novější pravidla.
7-<mode> Použije se sada pravidel, která byla k dispozici pro verzi .NET 7, i když jsou k dispozici novější pravidla. Hodnota <mode> určuje, která pravidla jsou povolená.
6.0 Používá se sada pravidel, která byla k dispozici pro verzi .NET 6, i když jsou k dispozici novější pravidla.
6.0-<mode> Používá se sada pravidel, která byla k dispozici pro verzi .NET 6, i když jsou k dispozici novější pravidla. Hodnota <mode> určuje, která pravidla jsou povolená.
6 Používá se sada pravidel, která byla k dispozici pro verzi .NET 6, i když jsou k dispozici novější pravidla.
6-<mode> Používá se sada pravidel, která byla k dispozici pro verzi .NET 6, i když jsou k dispozici novější pravidla. Hodnota <mode> určuje, která pravidla jsou povolená.
5.0 Používá se sada pravidel, která byla k dispozici pro verzi .NET 5, i když jsou k dispozici novější pravidla.
5.0-<mode> Používá se sada pravidel, která byla k dispozici pro verzi .NET 5, i když jsou k dispozici novější pravidla. Hodnota <mode> určuje, která pravidla jsou povolená.
5 Používá se sada pravidel, která byla k dispozici pro verzi .NET 5, i když jsou k dispozici novější pravidla.
5-<mode> Používá se sada pravidel, která byla k dispozici pro verzi .NET 5, i když jsou k dispozici novější pravidla. Hodnota <mode> určuje, která pravidla jsou povolená.

Poznámka

  • V .NET 5 a starších verzích tato vlastnost ovlivňuje pouze pravidla pro kvalitu kódu (CAXXXX). Počínaje verzí .NET 6, pokud nastavíte EnforceCodeStyleInBuild na true, tato vlastnost ovlivňuje také pravidla stylu kódu (IDEXXXX).
  • Pokud nastavíte složenou hodnotu pro AnalysisLevel, nemusíte zadávat AnalysisMode. Pokud to ale uděláte, AnalysisLevel bude mít přednost před AnalysisMode.
  • Tato vlastnost nemá žádný vliv na analýzu kódu v projektech, které neodkazují na sadu SDK projektu, například na starší projekty rozhraní .NET Framework, které odkazují na balíček NuGet Microsoft.CodeAnalysis.NetAnalyzers.

AnalysisLevel<Category>

V .NET 6 je tato vlastnost stejná jako AnalysisLevel s tím rozdílem, že se vztahuje pouze na konkrétní kategorii pravidel analýzy kódu. Tato vlastnost umožňuje použít jinou verzi analyzátorů kódu pro konkrétní kategorii nebo povolit nebo zakázat pravidla na jiné úrovni než ostatní kategorie pravidel. Pokud tuto vlastnost vynecháte pro konkrétní kategorii pravidel, bude výchozí hodnota AnalysisLevel . Dostupné hodnoty jsou stejné jako pro AnalysisLevel.

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

V následující tabulce jsou uvedeny názvy vlastností pro každou kategorii pravidel.

Název vlastnosti Kategorie pravidel
<AnalysisLevelDesign> Pravidla návrhu
<AnalysisLevelDocumentation> Pravidla dokumentace
<AnalysisLevelGlobalization> Pravidla globalizace
<AnalysisLevelInteroperability> Pravidla přenositelnosti a interoperability
<AnalysisLevelMaintainability> Pravidla udržovatelnosti
<AnalysisLevelNaming> Pravidla pojmenování
<AnalysisLevelPerformance> Pravidla výkonu
<AnalysisLevelSingleFile> Pravidla jednosouborové aplikace
<AnalysisLevelReliability> Pravidla spolehlivosti
<AnalysisLevelSecurity> Pravidla zabezpečení
<AnalysisLevelStyle> Pravidla ve stylu kódu (IDEXXXX)
<AnalysisLevelUsage> Pravidla používání

AnalysisMode

Počínaje verzí .NET 5 se sada .NET SDK dodává se všemi pravidly pro kvalitu kódu certifikační autority. Ve výchozím nastavení jsou v každé vydané verzi .NET jako upozornění na sestavení povolená jenom některá pravidla . Vlastnost AnalysisMode umožňuje přizpůsobit sadu pravidel, která je ve výchozím nastavení povolená. Můžete buď přepnout na režim agresivnější analýzy, ve kterém se můžete z pravidel odhlásit jednotlivě, nebo na konzervativnější režim analýzy, ve kterém se můžete přihlásit ke konkrétním pravidlům. Pokud například chcete povolit všechna pravidla jako upozornění sestavení, nastavte hodnotu na All.

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

Následující tabulka uvádí dostupné hodnoty možností v .NET 5 a novějších verzích. Jsou uvedeny v rostoucím pořadí podle počtu pravidel, která povolují.

Hodnota .NET 6+ Hodnota .NET 5 Význam
None AllDisabledByDefault Všechna pravidla jsou zakázaná. Pokud je chcete povolit, můžete selektivně přihlásit k jednotlivým pravidlům.
Default Default Výchozí režim, kdy jsou určitá pravidla povolená jako upozornění sestavení, určitá pravidla jsou povolená jako návrhy integrovaného vývojového prostředí sady Visual Studio a zbývající pravidla jsou zakázaná.
Minimum Agresivnější režim než režim Default . Některé návrhy, které se důrazně doporučují pro vynucování sestavení, jsou povolené jako upozornění sestavení.
Recommended Agresivnější režim než Minimum režim, ve kterém se jako upozornění sestavení povoluje více pravidel.
All AllEnabledByDefault Všechna pravidla jsou povolená jako upozornění sestavení. Pokud chcete jednotlivá pravidla zakázat, můžete selektivně odhlásit .

Poznámka

  • V .NET 5 tato vlastnost ovlivňuje pouze pravidla kvality kódu (CAXXXX). Počínaje verzí .NET 6, pokud nastavíte EnforceCodeStyleInBuild na true, tato vlastnost ovlivňuje také pravidla stylu kódu (IDEXXXX).
  • Pokud pro AnalysisLevel použijete složenou hodnotu, <AnalysisLevel>5-recommended</AnalysisLevel>například , můžete tuto vlastnost zcela vynechat. Pokud ale zadáte obě vlastnosti, AnalysisLevel bude mít přednost před AnalysisMode.
  • Pokud AnalysisMode je nastavená hodnota AllEnabledByDefault a AnalysisLevel je nastavena na 5 nebo 5.0a pak nainstalujete sadu .NET 6 SDK a znovu zkompilujete projekt, můžou se zobrazit neočekávaná upozornění na nové sestavení. Další informace najdete v tématu dotnet/roslyn-analyzers#5679.
  • Tato vlastnost nemá žádný vliv na analýzu kódu v projektech, které neodkazují na sadu SDK projektu, například na starší projekty rozhraní .NET Framework, které odkazují na balíček NuGet Microsoft.CodeAnalysis.NetAnalyzers.

AnalysisMode<Category>

Tato vlastnost byla zavedena v .NET 6 a je stejná jako AnalysisMode s tím rozdílem, že se vztahuje pouze na konkrétní kategorii pravidel analýzy kódu. Tato vlastnost umožňuje povolit nebo zakázat pravidla na jiné úrovni než ostatní kategorie pravidel. Pokud tuto vlastnost vynecháte pro určitou kategorii pravidel, bude výchozí hodnota AnalysisMode . Dostupné hodnoty jsou stejné jako pro AnalysisMode.

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

V následující tabulce jsou uvedeny názvy vlastností pro každou kategorii pravidel.

Název vlastnosti Kategorie pravidel
<AnalysisModeDesign> Pravidla návrhu
<AnalysisModeDocumentation> Pravidla dokumentace
<AnalysisModeGlobalization> Pravidla globalizace
<AnalysisModeInteroperability> Pravidla přenositelnosti a interoperability
<AnalysisModeMaintainability> Pravidla udržovatelnosti
<AnalysisModeNaming> Pravidla pojmenování
<AnalysisModePerformance> Pravidla výkonu
<AnalysisModeSingleFile> Pravidla jednosouborové aplikace
<AnalysisModeReliability> Pravidla spolehlivosti
<AnalysisModeSecurity> Pravidla zabezpečení
<AnalysisModeStyle> Pravidla ve stylu kódu (IDEXXXX)
<AnalysisModeUsage> Pravidla používání

CodeAnalysisTreatWarningsAsErrors

Vlastnost CodeAnalysisTreatWarningsAsErrors umožňuje nakonfigurovat, jestli se mají upozornění analýzy kvality kódu (CAxxxx) považovat za upozornění a narušit sestavení. Pokud při sestavování projektů použijete -warnaserror příznak, za chyby se považují také upozornění analýzy kvality kódu .NET . Pokud nechcete, aby se upozornění analýzy kvality kódu považovala za chyby, můžete v souboru projektu nastavit CodeAnalysisTreatWarningsAsErrors vlastnost MSBuild na false .

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

EnableNETAnalyzers

Analýza kvality kódu .NET je ve výchozím nastavení povolená pro projekty, které cílí na .NET 5 nebo novější verzi. Pokud vyvíjíte pomocí sady .NET 5+ SDK, můžete povolit analýzu kódu .NET pro projekty ve stylu sady SDK, které cílí na starší verze rozhraní .NET nastavením EnableNETAnalyzers vlastnosti na true. Pokud chcete zakázat analýzu kódu v libovolném projektu, nastavte tuto vlastnost na false.

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

Poznámka

Tato vlastnost platí konkrétně pro integrované analyzátory v sadě .NET 5+ SDK. Neměl by se používat při instalaci balíčku pro analýzu kódu NuGet.

EnforceCodeStyleInBuild

Analýza stylu kódu .NET je ve výchozím nastavení zakázaná při sestavování pro všechny projekty .NET. Analýzu stylu kódu pro projekty .NET můžete povolit nastavením EnforceCodeStyleInBuild vlastnosti na true.

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

Všechna pravidla stylu kódu, která jsou nakonfigurována tak, aby byla upozorněními nebo chybami, se spustí při sestavení a hlášení porušení.

Poznámka

Pokud nainstalujete .NET 6 (nebo Visual Studio 2022, která obsahuje .NET 6), ale chcete vytvořit projekt pomocí sady Visual Studio 2019, může se zobrazit nová upozornění CS8032 , pokud máte vlastnost nastavenou EnforceCodeStyleInBuild na true. Pokud chcete tato upozornění vyřešit, můžete přidáním položky global.json zadat verzi sady .NET SDK pro sestavení projektu (v tomto případě něco jako 5.0.404).

_SkipUpgradeNetAnalyzersNuGetWarning

Vlastnost _SkipUpgradeNetAnalyzersNuGetWarning umožňuje nakonfigurovat, jestli se zobrazí upozornění, pokud používáte analyzátory kódu z balíčku NuGet, který je zastaralý v porovnání s analyzátory kódu v nejnovější sadě .NET SDK. Upozornění vypadá přibližně takto:

Sada .NET SDK obsahuje novější analyzátory s verzí 6.0.0, než jakou poskytuje verze 5.0.3 balíčku Microsoft.CodeAnalysis.NetAnalyzers. Aktualizujte nebo odeberte tento odkaz na balíček.

Pokud chcete toto upozornění odebrat a dál používat verzi analyzátorů kódu v balíčku NuGet, nastavte _SkipUpgradeNetAnalyzersNuGetWarning v souboru projektu na hodnotu na true .

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

Vlastnosti konfigurace modulu runtime

Některá chování za běhu můžete nakonfigurovat tak, že v souboru projektu aplikace zadáte vlastnosti NÁSTROJE MSBuild. Informace o dalších způsobech konfigurace chování za běhu najdete v tématu Nastavení konfigurace modulu runtime.

ConcurrentGarbageCollection

Vlastnost ConcurrentGarbageCollection konfiguruje, jestli je povolené uvolňování paměti na pozadí (souběžné ). Pokud chcete zakázat uvolňování paměti na pozadí, nastavte hodnotu na false hodnotu . Další informace najdete v tématu GC na pozadí.

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

InvariantGlobalization

Vlastnost InvariantGlobalization konfiguruje, jestli aplikace běží v režimu globalization-invariant , což znamená, že nemá přístup k datům specifickým pro jazykovou verzi. Nastavte hodnotu na pro true spuštění v režimu globalization-invariant. Další informace najdete v tématu o invariantní režimu.

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

PředdefinovanéculturesOnly

V .NET 6 a novějších verzích vlastnost konfiguruje, PredefinedCulturesOnly jestli aplikace můžou vytvářet jiné jazykové verze, než je invariantní jazyková verze, pokud je povolen režim globalization-invariant . Výchozí formát je true. Nastavte hodnotu na, false aby bylo možné vytvářet libovolnou novou jazykovou verzi v režimu invariantní globalizace.

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

Další informace najdete v tématu Vytvoření jazykové verze a mapování případů v režimu invariantní globalizace.

RetainVMGarbageCollection

Vlastnost RetainVMGarbageCollection konfiguruje uvolňování paměti tak, aby se odstraněné segmenty paměti umístily do pohotovostního seznamu pro budoucí použití nebo jejich uvolnění. Nastavení hodnoty tak, aby true systém uvolňování paměti řekl, že má segmenty umístit do pohotovostního seznamu. Další informace najdete v tématu Zachování virtuálního počítače.

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

ServerGarbageCollection

Vlastnost ServerGarbageCollection konfiguruje, zda aplikace používá uvolňování paměti pracovní stanice nebo uvolňování paměti serveru. Nastavte hodnotu na hodnotu pro true použití uvolňování paměti serveru. Další informace najdete v tématu Pracovní stanice vs. server.

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

ThreadPoolMaxThreads

Vlastnost ThreadPoolMaxThreads konfiguruje maximální počet vláken pro fond pracovních vláken. Další informace najdete v tématu Maximální počet vláken.

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

ThreadPoolMinThreads

Vlastnost ThreadPoolMinThreads konfiguruje minimální počet vláken pro fond pracovních vláken. Další informace najdete v tématu Minimální počet vláken.

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

Vrstvenécompilation

Vlastnost TieredCompilation konfiguruje, jestli kompilátor za běhu (JIT) používá vrstvenou kompilaci. Pokud chcete zakázat vrstvené kompilace, nastavte hodnotu na false hodnotu . Další informace najdete v tématu Vrstvené kompilace.

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

TieredCompilationQuickJit

Vlastnost TieredCompilationQuickJit konfiguruje, jestli kompilátor JIT používá rychlé JIT. Pokud chcete zakázat rychlé jiT, nastavte hodnotu na false hodnotu . Další informace najdete v tématu Quick JIT.

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

TieredCompilationQuickJitForLoops

Vlastnost TieredCompilationQuickJitForLoops konfiguruje, zda kompilátor JIT používá rychlé JIT u metod, které obsahují smyčky. Nastavením hodnoty na hodnotu na true povolte rychlé JIT u metod, které obsahují smyčky. Další informace najdete v tématu Rychlé jit pro smyčky.

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

Následující vlastnosti nástroje MSBuild jsou popsány v této části:

AssetTargetFallback

Vlastnost AssetTargetFallback umožňuje zadat další kompatibilní verze architektury pro odkazy na projekt a balíčky NuGet. Pokud například zadáte závislost balíčku pomocí, PackageReference ale balíček neobsahuje prostředky, které jsou kompatibilní s vašimi projekty TargetFramework, AssetTargetFallback vlastnost se spustí. Kompatibilita odkazovaného balíčku se znovu zkontroluje pomocí každé cílové architektury zadané v AssetTargetFallbacknástroji . Tato vlastnost nahrazuje zastaralou vlastnost PackageTargetFallback.

Vlastnost můžete nastavit AssetTargetFallback na jednu nebo více verzí cílové architektury.

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

DisableImplicitFrameworkReferences

Vlastnost DisableImplicitFrameworkReferences řídí implicitní FrameworkReference položky při cílení na .NET Core 3.0 a novější verze. Při cílení na .NET Core 2.1 nebo .NET Standard 2.0 a starší verze řídí implicitní položky PackageReference na balíčky v metabalíču. (Metabalít je balíček založený na architektuře, který se skládá pouze ze závislostí na jiných balíčcích.) Tato vlastnost také řídí implicitní odkazy, například System a System.Core při cílení na rozhraní .NET Framework.

Pokud chcete zakázat implicitní FrameworkReference položky nebo PackageReference, nastavte tuto vlastnost na true hodnotu . Pokud tuto vlastnost nastavíte na true, můžete přidat explicitní odkazy jenom na architektury nebo balíčky, které potřebujete.

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

DisableTransitiveFrameworkReferenceDownloads

DisableTransitiveFrameworkReferenceDownloads Nastavte vlastnost na, true abyste se vyhnuli stahování dalších modulů runtime a cílení balíčků, na které váš projekt přímo neodkazuje.

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

DisableTransitiveProjectReferences

Vlastnost DisableTransitiveProjectReferences řídí implicitní odkazy na projekt. Pokud chcete zakázat implicitní ProjectReference položky, nastavte tuto vlastnost na true hodnotu . Zakázání implicitních odkazů na projekt má za následek nepřenosné chování podobné staršímu systému projektu.

Pokud je truetato vlastnost , má podobný účinek jako nastavení PrivateAssets="All" u všech závislostí závislého projektu.

Pokud tuto vlastnost nastavíte na true, můžete přidat explicitní odkazy jenom na projekty, které potřebujete.

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

Obnovením odkazovaného balíčku se nainstalují všechny jeho přímé závislosti a všechny závislosti těchto závislostí. Obnovení balíčku můžete přizpůsobit zadáním vlastností, jako RestorePackagesPath jsou a RestoreIgnoreFailedSources. Další informace o těchto a dalších vlastnostech najdete v tématu obnovení cíle.

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

PoužitíMauiEssentials

UseMauiEssentials Nastavením vlastnosti na hodnotu true deklarujte explicitní odkaz na projekt nebo balíček, který závisí na MAUI Essentials. Toto nastavení zajistí, že projekt stáhne správný známý odkaz na architekturu pro MAUI Essentials. Pokud váš projekt odkazuje na projekt, který používá MAUI Essentials, ale nenastavíte tuto vlastnost na true, může se zobrazit upozornění NETSDK1186na sestavení .

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

ValidateExecutableReferencesMatchSelfContained

Vlastnost ValidateExecutableReferencesMatchSelfContained lze použít k zakázání chyb souvisejících se spustitelnými odkazy na projekt. Pokud rozhraní .NET zjistí, že samostatný spustitelný projekt odkazuje na spustitelný projekt závislý na architektuře nebo naopak, vygeneruje chyby NETSDK1150 a NETSDK1151 v uvedeném pořadí. Chcete-li se vyhnout těmto chybám, pokud je odkaz úmyslný, nastavte ValidateExecutableReferencesMatchSelfContained vlastnost na false.

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

WindowsSdkPackageVersion

Vlastnost WindowsSdkPackageVersion lze použít k přepsání verze cílového balíčku sady Windows SDK. Tato vlastnost byla zavedena v .NET 5 a nahrazuje použití FrameworkReference položky pro tento účel.

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

Poznámka

Nedoporučujeme přepisovat verzi sady Windows SDK, protože balíčky pro cílení sady Windows SDK jsou součástí sady .NET 5+ SDK. Pokud chcete odkazovat na nejnovější balíček sady Windows SDK, aktualizujte svoji verzi sady .NET SDK. Tato vlastnost by se měla používat jenom ve výjimečných případech, jako je použití balíčků preview nebo potřeba přepsat verzi C#/WinRT.

Následující vlastnosti se používají ke spuštění aplikace pomocí dotnet run příkazu :

RunArguments

Vlastnost RunArguments definuje argumenty, které se předávají aplikaci při jejím spuštění.

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

Tip

Další argumenty, které se mají aplikaci předat, můžete zadat pomocí -- možnosti pro dotnet run.

RunWorkingDirectory

Vlastnost RunWorkingDirectory definuje pracovní adresář pro proces aplikace, ve které se má spustit. Může to být absolutní cesta nebo cesta relativní k adresáři projektu. Pokud nezadáte adresář, OutDir použije se jako pracovní adresář.

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

Následující vlastnosti nástroje MSBuild jsou popsány v této části:

EnableComHosting

Vlastnost EnableComHosting označuje, že sestavení poskytuje server COM. Nastavení parametru EnableComHosting na true také znamená, že EnableDynamicLoading je true.

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

Další informace najdete v tématu Zveřejnění komponent .NET pro com.

EnableDynamicLoading

Vlastnost EnableDynamicLoading označuje, že sestavení je dynamicky načtená komponenta. Komponentou může být knihovna modelu COM nebo jiná knihovna než knihovna COM, kterou lze použít z nativního hostitele nebo jako modul plug-in. Nastavení této vlastnosti na má true následující účinky:

  • Vygeneruje se soubor .runtimeconfig.json .
  • Funkce RollForward je nastavená na LatestMinorhodnotu .
  • Odkazy NuGet se kopírují místně.
<PropertyGroup>
  <EnableDynamicLoading>true</EnableDynamicLoading>
</PropertyGroup>

Vlastnosti vygenerovaného souboru

Následující vlastnosti se týkají kódu ve generovaných souborech:

DisableImplicitNamespaceImports

Vlastnost DisableImplicitNamespaceImports lze použít k zakázání implicitních importů oboru názvů v projektech Jazyka Visual Basic, které cílí na .NET 6 nebo novější verzi. Implicitní obory názvů jsou výchozí obory názvů, které jsou importovány globálně v projektu jazyka Visual Basic. Pokud chcete zakázat implicitní importy oborů názvů, nastavte tuto vlastnost na true hodnotu .

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

Implicitní použužování

Vlastnost ImplicitUsings lze použít k povolení a zakázání implicitních global using direktiv v projektech C#, které cílí na .NET 6 nebo novější verzi a C# 10 nebo novější verzi. Pokud je tato funkce povolená, sada .NET SDK přidá global using direktivy pro sadu výchozích oborů názvů na základě typu sady SDK projektu. Pokud chcete povolit implicitní global using direktivy, nastavte tuto vlastnost na true neboenable. Pokud chcete zakázat implicitní global using direktivy, odeberte vlastnost nebo ji nastavte na false nebo disable.

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

Poznámka

Šablony pro nové projekty C#, které cílí na .NET 6 nebo novější, jsou ImplicitUsings ve výchozím nastavení nastavené na enable .

Pokud chcete definovat explicitní global using direktivu, přidejte položku Using .

Položky

Položky NÁSTROJE MSBuild jsou vstupy do systému sestavení. Položky se zadají podle jejich typu, což je název prvku. Například Compile a Reference jsou dva běžné typy položek. Sada .NET SDK obsahuje následující další typy položek:

U těchto položek můžete použít kterýkoli ze standardních atributů položky, Include například a Update. Slouží Include k přidání nové položky a k Update úpravě existující položky. Často se například Update používá k úpravě položky, která byla implicitně přidána sadou .NET SDK.

AssemblyMetadata

Položka AssemblyMetadata určuje atribut sestavení páru AssemblyMetadataAttribute klíč-hodnota. Metadata Include se stanou klíčem a Value metadata se stanou hodnotou.

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

InternalsVisibleTo

Položka InternalsVisibleTo vygeneruje InternalsVisibleToAttribute atribut sestavení pro zadané přátelské sestavení.

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

Pokud je přátelské sestavení podepsáno, můžete zadat volitelná Key metadata a zadat jeho úplný veřejný klíč. Pokud nezadáte Key metadata a $(PublicKey) je k dispozici, použije se tento klíč. V opačném případě se do atributu nepřidá žádný veřejný klíč.

PackageReference

Položka PackageReference definuje odkaz na balíček NuGet.

Atribut Include určuje ID balíčku. Atribut Version určuje verzi nebo rozsah verzí. Informace o tom, jak zadat minimální verzi, maximální verzi, rozsah nebo přesnou shodu, najdete v tématu Rozsahy verzí.

Fragment kódu souboru projektu v následujícím příkladu odkazuje na balíček System.Runtime .

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

Prostředky závislostí můžete řídit také pomocí metadat, jako PrivateAssetsje .

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

Další informace najdete v tématu Odkazy na balíčky v souborech projektu.

TrimmerRootAssembly

Položka TrimmerRootAssembly umožňuje vyloučit sestavení z oříznutí. Oříznutí je proces odebrání nepoužívaných částí modulu runtime z zabalené aplikace. V některých případech může oříznutí nesprávně odebrat požadované odkazy.

Následující kód XML vyloučí System.Security sestavení z oříznutí.

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

Další informace najdete v tématu Možnosti oříznutí.

Použití

Položka Using umožňuje globálně zahrnout obor názvů do projektu jazyka C#, abyste nemuseli přidávat using direktivu pro obor názvů v horní části zdrojových souborů. Tato položka je podobná Import položce, kterou lze použít pro stejný účel v projektech jazyka Visual Basic. Tato vlastnost je k dispozici od verze .NET 6.

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

Položku můžete také použít Using k definování globálních using <alias> a using static <type> direktiv.

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

Příklad:

  • <Using Include="Microsoft.AspNetCore.Http.Results" Alias="Results" /> Vydává global using Results = global::Microsoft.AspNetCore.Http.Results;
  • <Using Include="Microsoft.AspNetCore.Http.Results" Static="True" /> Vydává global using static global::Microsoft.AspNetCore.Http.Results;

Další informace najdete v tématu Direktivy a direktivy s aliasyusing.using static <type>

Metadata položky

Kromě standardních atributů položek MSBuild jsou sadou .NET SDK k dispozici následující značky metadat položek:

CopyToPublishDirectory

Metadata CopyToPublishDirectory položky nástroje MSBuild řídí, když je položka zkopírována do adresáře publish. Povolené hodnoty jsou PreserveNewest, které kopírují pouze položku, pokud se změnila, Always, která vždy zkopíruje položku a Never, která položku nikdy nezkopírovala. Z hlediska výkonu je vhodnější, PreserveNewest protože umožňuje přírůstkové sestavení.

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

Propojení

U položky, která je mimo adresář projektu a jeho podadresáře, cíl publikování používá metadata odkazu položky k určení, kam se má položka zkopírovat. Linkurčuje také způsob zobrazení položek mimo strom projektu v okně Průzkumník řešení sady Visual Studio.

Pokud Link není zadán pro položku, která je mimo kužel projektu, výchozí hodnota %(LinkBase)\%(RecursiveDir)%(Filename)%(Extension)je . LinkBase umožňuje zadat rozumnou základní složku pro položky mimo kužel projektu. Hierarchie složek v základní složce se zachová přes RecursiveDir. Pokud LinkBase není zadaný, v cestě Link se vynechá.

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

Následující obrázek ukazuje, jak se v Průzkumník řešení zobrazí soubor, který je součástí globu předchozí položkyInclude.

Průzkumník řešení zobrazující položku s metadaty LinkBase.

Viz také