Dokumentacja programu MSBuild dla projektów zestawu SDK platformy .NET

Ta strona jest odwołaniem do właściwości i elementów programu MSBuild, których można użyć do konfigurowania projektów platformy .NET.

Uwaga

Ta strona jest w toku i nie wyświetla wszystkich przydatnych właściwości programu MSBuild dla zestawu .NET SDK. Aby uzyskać listę typowych właściwości programu MSBuild, zobacz Typowe właściwości programu MSBuild.

Właściwości struktury

W tej sekcji opisano następujące właściwości programu MSBuild:

TargetFramework

Właściwość TargetFramework określa docelową wersję platformy dla aplikacji. Aby uzyskać listę prawidłowych szablonów platform docelowych, zobacz Platformy docelowe w projektach w stylu zestawu SDK.

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

Aby uzyskać więcej informacji, zobacz Platformy docelowe w projektach w stylu zestawu SDK.

TargetFrameworks

Użyj właściwości , TargetFrameworks jeśli aplikacja ma być docelowa dla wielu platform. Aby uzyskać listę prawidłowych szablonów platform docelowych, zobacz Platformy docelowe w projektach w stylu zestawu SDK.

Uwaga

Ta właściwość jest ignorowana, jeśli TargetFramework jest określona (pojedyncza).

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

Aby uzyskać więcej informacji, zobacz Platformy docelowe w projektach w stylu zestawu SDK.

NetStandardImplicitPackageVersion

Uwaga

Ta właściwość dotyczy tylko projektów przy użyciu polecenia netstandard1.x. Nie ma zastosowania do projektów korzystających z programu netstandard2.x.

NetStandardImplicitPackageVersion Użyj właściwości , jeśli chcesz określić wersję platformy, która jest niższa niż wersja metapackage. Plik projektu w poniższym przykładzie docelowymnetstandard1.3, ale używa wersji 1.6.0 .NETStandard.Library

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

Właściwości atrybutu zestawu

GenerateAssemblyInfo

Właściwość GenerateAssemblyInfo steruje AssemblyInfo generowaniem atrybutów dla projektu. Wartość domyślna to true. Użyj false polecenia , aby wyłączyć generowanie pliku:

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

Ustawienie GeneratedAssemblyInfoFile kontroluje nazwę wygenerowanego pliku.

GenerateAssemblyInfo Gdy wartość to true, właściwości projektu powiązanego z pakietem są przekształcane w atrybuty zestawu. W poniższej tabeli wymieniono właściwości projektu, które generują atrybuty. Zawiera również listę właściwości, których można użyć do wyłączenia tej generacji na podstawie atrybutu, na przykład:

<PropertyGroup>
  <GenerateNeutralResourcesLanguageAttribute>false</GenerateNeutralResourcesLanguageAttribute>
</PropertyGroup>
Właściwość MSBuild Atrybut zestawu Właściwość wyłączania generowania atrybutów
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

Uwagi dotyczące tych ustawień:

  • AssemblyVersion i FileVersion wartość domyślna wartości $(Version) bez sufiksu. Jeśli na przykład $(Version) to 1.2.3-beta.4, wartość to 1.2.3.
  • InformationalVersionwartość domyślna to .$(Version)
  • $(SourceRevisionId) Jeśli właściwość jest obecna, jest dołączona do InformationalVersionelementu . To zachowanie można wyłączyć przy użyciu polecenia IncludeSourceRevisionInInformationalVersion.
  • Copyright właściwości i Description są również używane dla metadanych NuGet.
  • Configuration, który domyślnie ma wartość , jest współużytkowany ze wszystkimi elementami docelowymi Debugprogramu MSBuild. Można ją ustawić za pomocą --configuration opcji dotnet poleceń, na przykład dotnet pack.
  • Niektóre właściwości są używane podczas tworzenia pakietu NuGet. Aby uzyskać więcej informacji, zobacz Właściwości pakietu.

Migrowanie z .NET Framework

.NET Framework szablony projektów tworzą plik kodu z zestawem tych atrybutów informacji o zestawie. Plik znajduje się zazwyczaj w folderze .\Properties\AssemblyInfo.cs lub .\Properties\AssemblyInfo.vb. Projekty w stylu zestawu SDK generują ten plik na podstawie ustawień projektu. Nie można mieć obu tych elementów. Podczas przenoszenia kodu do platformy .NET 5 (lub .NET Core 3.1) lub nowszej wykonaj jedną z następujących czynności:

  • Wyłącz generowanie tymczasowego pliku kodu zawierającego atrybuty informacji o zestawie, ustawiając wartość GenerateAssemblyInfo na false w pliku projektu. Dzięki temu można zachować plik AssemblyInfo .
  • Zmigruj AssemblyInfo ustawienia w pliku do pliku projektu, a następnie usuń AssemblyInfo plik.

GeneratedAssemblyInfoFile

Właściwość GeneratedAssemblyInfoFile definiuje względną lub bezwzględną ścieżkę wygenerowanego pliku informacji o zestawie. Domyślnie plik o nazwie [project-name]. AssemblyInfo. [cs|vb] w $(IntermediateOutputPath) katalogu (zwykle obj).

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

Właściwości pakietu

Możesz określić właściwości, takie jak PackageId, , PackageIconPackageVersion, Titlei, aby Description opisać pakiet, który zostanie utworzony na podstawie projektu. Aby uzyskać informacje o tych i innych właściwościach, zobacz Temat docelowy pakietu.

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

PackRelease

Właściwość jest podobna PackRelease do właściwości PublishRelease , z tą różnicą, że zmienia domyślne zachowanie elementu dotnet pack.

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

W tej sekcji opisano następujące właściwości programu MSBuild:

AppendTargetFrameworkToOutputPath

Właściwość AppendTargetFrameworkToOutputPath określa, czy obiekt docelowy moniker (TFM) jest dołączany do ścieżki wyjściowej (która jest zdefiniowana przez parametr OutputPath). Zestaw SDK platformy .NET automatycznie dołącza platformę docelową, a jeśli istnieje, identyfikator środowiska uruchomieniowego do ścieżki wyjściowej. Ustawienie AppendTargetFrameworkToOutputPath w celu false uniemożliwienia dołączania serwera TFM do ścieżki wyjściowej. Jednak bez serwera TFM w ścieżce wyjściowej wiele artefaktów kompilacji może zastąpić siebie nawzajem.

Na przykład w przypadku aplikacji .NET 5 ścieżka wyjściowa zmienia się z bin\Debug\net5.0 na bin\Debug za pomocą następującego ustawienia:

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

AppendRuntimeIdentifierToOutputPath

Właściwość AppendRuntimeIdentifierToOutputPath określa, czy identyfikator środowiska uruchomieniowego (RID) jest dołączany do ścieżki wyjściowej. Zestaw SDK platformy .NET automatycznie dołącza platformę docelową, a jeśli istnieje, identyfikator środowiska uruchomieniowego do ścieżki wyjściowej. Ustawienie AppendRuntimeIdentifierToOutputPath w celu false uniemożliwienia dołączania identyfikatora RID do ścieżki wyjściowej.

Na przykład w przypadku aplikacji .NET 5 i identyfikatora RID ścieżki wyjściowej win10-x64zmienia się z bin\Debug\net5.0\win10-x64 na bin\Debug\net5.0 za pomocą następującego ustawienia:

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

CopyLocalLockFileAssemblies

Właściwość jest przydatna CopyLocalLockFileAssemblies w przypadku projektów wtyczek, które mają zależności od innych bibliotek. Jeśli ta właściwość zostanie ustawiona na truewartość , wszystkie zależności pakietu NuGet zostaną skopiowane do katalogu wyjściowego. Oznacza to, że możesz użyć danych wyjściowych polecenia dotnet build , aby uruchomić wtyczkę na dowolnej maszynie.

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

Porada

Alternatywnie możesz użyć dotnet publish polecenia , aby opublikować bibliotekę klas. Aby uzyskać więcej informacji, zobacz dotnet publish (Publikowanie w witrynie dotnet).

ErrorOnDuplicatePublishOutputFiles

Właściwość ErrorOnDuplicatePublishOutputFiles odnosi się do tego, czy zestaw SDK generuje błąd NETSDK1148, gdy program MSBuild wykrywa zduplikowane pliki w danych wyjściowych publikowania, ale nie może określić, które pliki mają być usuwane. ErrorOnDuplicatePublishOutputFiles Ustaw właściwość na false wartość , jeśli nie chcesz, aby błąd został wygenerowany.

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

Ta właściwość została wprowadzona na platformie .NET 6.

EnablePackageValidation

Właściwość EnablePackageValidation włącza serię walidacji pakietu po pack zadaniu. Aby uzyskać więcej informacji, zobacz walidację pakietu.

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

Ta właściwość została wprowadzona na platformie .NET 6.

GenerateRuntimeConfigDevFile

Począwszy od zestawu .NET 6 SDK, plik [Appname].runtimesettings.dev.jsonnie jest już domyślnie generowany w czasie kompilacji. Jeśli nadal chcesz wygenerować ten plik, ustaw GenerateRuntimeConfigDevFile właściwość na true.

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

GenerateRuntimeConfigurationFiles

Właściwość GenerateRuntimeConfigurationFiles określa, czy opcje konfiguracji środowiska uruchomieniowego są kopiowane z pliku runtimeconfig.template.json do pliku [appname].runtimeconfig.json . W przypadku aplikacji, które wymagają pliku runtimeconfig.json , czyli tych, których OutputType wartość to Exe, ta właściwość jest domyślnie ustawiona na true.

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

GenerateSatelliteAssembliesForCore

Właściwość GenerateSatelliteAssembliesForCore określa, czy zestawy satelitarne są generowane przy użyciu csc.exe lub Al.exe (Assembly Linker) w projektach .NET Framework. (Projekty .NET Core i .NET 5+ zawsze używają csc.exe do generowania zestawów satelitarnych). W przypadku projektów .NET Framework zestawy satelitarne są tworzone domyślnie przezal.exe. GenerateSatelliteAssembliesForCore Ustawiając właściwość na true, zestawy satelitarne są tworzone przez csc.exe zamiast tego. Korzystanie z csc.exe może być korzystne w następujących sytuacjach:

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

IsPublishable

Właściwość IsPublishable umożliwia Publish uruchamianie obiektu docelowego. Ta właściwość dotyczy tylko procesów, które używają plików .*proj i Publish obiektu docelowego, na przykład polecenia dotnet publish . Nie ma to wpływu na publikowanie w programie Visual Studio, który używa PublishOnly elementu docelowego. Wartość domyślna to true.

Ta właściwość jest przydatna w przypadku uruchamiania dotnet publish w pliku rozwiązania, ponieważ umożliwia automatyczne wybieranie projektów, które powinny zostać opublikowane.

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

PreserveCompilationContext

Właściwość PreserveCompilationContext umożliwia skompilowanie lub opublikowanie aplikacji większej liczby kodu w czasie wykonywania przy użyciu tych samych ustawień, które były używane w czasie kompilacji. Zestawy przywoływane w czasie kompilacji zostaną skopiowane do podkatalogu ref katalogu wyjściowego. Nazwy zestawów odwołań są przechowywane w pliku .deps.json aplikacji wraz z opcjami przekazanymi do kompilatora. Te informacje można pobrać przy użyciu DependencyContext.CompileLibraries właściwości i DependencyContext.CompilationOptions .

Ta funkcja jest najczęściej używana wewnętrznie przez strony MVC i Razor ASP.NET Core do obsługi kompilacji plików Razor w czasie wykonywania.

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

PreserveCompilationReferences

Właściwość jest podobna PreserveCompilationReferences do właściwości PreserveCompilationContext , z tą różnicą, że kopiuje tylko przywoływalne zestawy do katalogu publikowania, a nie plik deps.json .

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

Aby uzyskać więcej informacji, zobacz Właściwości zestawu SDK Razor.

ProduceReferenceAssemblyInOutDir

W wersjach platformy .NET 5 i starszych zestawy referencyjne są zawsze zapisywane w OutDir katalogu. W programach .NET 6 i nowszych można użyć ProduceReferenceAssemblyInOutDir właściwości , aby kontrolować, czy zestawy odwołań są zapisywane w OutDir katalogu. Wartość domyślna to false, a zestawy odwołań są zapisywane tylko w IntermediateOutputPath katalogu. Ustaw wartość na wartość , aby true zapisywać zestawy odwołań do OutDir katalogu.

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

Aby uzyskać więcej informacji, zobacz Zapisywanie zestawów odwołań do danych wyjściowych pośrednich.

Publikowanie wersji

Właściwość PublishRelease informuje dotnet publish o użyciu Release konfiguracji zamiast Debug konfiguracji. Zalecamy dodanie tej właściwości do Directory.Build.props pliku zamiast pliku projektu, aby była oceniana na tyle wcześnie, aby zmiana konfiguracji została rozpropagowana.

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

Uwaga

Ta właściwość nie ma wpływu na zachowanie elementu dotnet build /t:Publish.

RollForward

Właściwość RollForward określa sposób, w jaki aplikacja wybiera środowisko uruchomieniowe, gdy dostępnych jest wiele wersji środowiska uruchomieniowego. Ta wartość jest wynikiem wyjściowym pliku runtimeconfig.json jako rollForward ustawienia.

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

Ustaw RollForward na jedną z następujących wartości:

Wartość Opis
Minor Wartość domyślna , jeśli nie zostanie określona.
Przerzuć do najniższej wyższej wersji pomocniczej, jeśli nie ma żądanej wersji pomocniczej. Jeśli żądana wersja pomocnicza jest obecna, LatestPatch zostaną użyte zasady.
Major Przejdź do następnej dostępnej nowszej wersji głównej i najniższej wersji pomocniczej, jeśli zażądano wersji głównej. Jeśli żądana wersja główna jest obecna, Minor zostaną użyte zasady.
LatestPatch Przerzucanie do najwyższej wersji poprawki. Ta wartość wyłącza wycofywanie wersji pomocniczej.
LatestMinor Przerzucanie do najwyższej wersji pomocniczej, nawet jeśli zażądano wersji pomocniczej.
LatestMajor Przerzucanie do najwyższej wersji głównej i najwyższej wersji pomocniczej, nawet jeśli jest wymagane główne.
Disable Nie przesyłaj dalej, powiąż tylko z określoną wersją. Te zasady nie są zalecane do użytku ogólnego, ponieważ wyłącza możliwość przesyłania dalej do najnowszych poprawek. Ta wartość jest zalecana tylko do testowania.

Aby uzyskać więcej informacji, zobacz Sterowanie zachowaniem wycofywania.

RuntimeFrameworkVersion

Właściwość RuntimeFrameworkVersion określa wersję środowiska uruchomieniowego do użycia podczas publikowania. Określ wersję środowiska uruchomieniowego:

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

Podczas publikowania aplikacji zależnej od platformy ta wartość określa wymaganą minimalną wersję. Podczas publikowania aplikacji samodzielnej ta wartość określa dokładną wymaganą wersję.

RuntimeIdentifier

Właściwość RuntimeIdentifier umożliwia określenie pojedynczego identyfikatora środowiska uruchomieniowego (RID) dla projektu. Identyfikator RID umożliwia publikowanie wdrożenia samodzielnego.

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

RuntimeIdentifiers

Właściwość RuntimeIdentifiers umożliwia określenie rozdzielanej średnikami listy identyfikatorów środowiska uruchomieniowego (RID) dla projektu. Użyj tej właściwości, jeśli musisz opublikować wiele środowisk uruchomieniowych. RuntimeIdentifiers jest używany w czasie przywracania, aby upewnić się, że odpowiednie zasoby znajdują się na grafie.

Porada

RuntimeIdentifier (pojedyncza) może zapewnić szybsze kompilacje, gdy wymagane jest tylko jedno środowisko uruchomieniowe.

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

SatelliteResourceLanguages

Właściwość SatelliteResourceLanguages umożliwia określenie języków, dla których chcesz zachować zestawy zasobów satelitarnych podczas kompilowania i publikowania. Wiele pakietów NuGet obejmuje zlokalizowane zestawy satelitarne zasobów w pakiecie głównym. W przypadku projektów odwołujących się do tych pakietów NuGet, które nie wymagają zlokalizowanych zasobów, zlokalizowane zestawy mogą niepotrzebnie zwiększać rozmiar kompilacji i publikowania danych wyjściowych. SatelliteResourceLanguages Dodając właściwość do pliku projektu, tylko zlokalizowane zestawy dla podanych języków zostaną uwzględnione w danych wyjściowych kompilacji i publikowania. Na przykład w poniższym pliku projektu zostaną zachowane tylko zestawy satelitarne zasobów angielskich (USA).

<PropertyGroup>
  <SatelliteResourceLanguages>en-US</SatelliteResourceLanguages>
</PropertyGroup>

Uwaga

Tę właściwość należy określić w projekcie, który odwołuje się do pakietu NuGet z zlokalizowanymi zestawami satelitarnymi zasobów.

UseAppHost

Właściwość UseAppHost określa, czy na potrzeby wdrożenia jest tworzony natywny plik wykonywalny. Natywny plik wykonywalny jest wymagany w przypadku wdrożeń samodzielnie zawartych.

W programie .NET Core 3.0 i nowszych wersjach plik wykonywalny zależny od platformy jest domyślnie tworzony. UseAppHost Ustaw właściwość na wartość , false aby wyłączyć generowanie pliku wykonywalnego.

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

Aby uzyskać więcej informacji na temat wdrażania, zobacz Wdrażanie aplikacji platformy .NET.

Dostępnych jest wiele właściwości programu MSBuild w celu dostosowania przycinania, co jest funkcją, która przycina nieużywany kod z wdrożeń samodzielnie zawartych. Te opcje zostały szczegółowo omówione w temacie Opcje przycinania. Poniższa tabela zawiera szybką dokumentację.

Właściwość Wartości Opis
PublishTrimmed true lub false Określa, czy przycinanie jest włączone podczas publikowania.
TrimMode full lub partial Wartość domyślna to full. Kontroluje stopień szczegółowości przycinania.
SuppressTrimAnalysisWarnings true lub false Określa, czy są generowane ostrzeżenia analizy przycinania.
EnableTrimAnalyzer true lub false Określa, czy jest generowany podzbiór ostrzeżeń analizy przycinania. Analizę można włączyć nawet wtedy, gdy PublishTrimmed jest ustawiona wartość false.
ILLinkTreatWarningsAsErrors true lub false Określa, czy ostrzeżenia przycinania są traktowane jako błędy. Na przykład możesz ustawić tę właściwość na false wartość , gdy TreatWarningsAsErrors jest ustawiona wartość true.
TrimmerSingleWarn true lub false Określa, czy jest wyświetlane pojedyncze ostrzeżenie dla zestawu, czy wszystkie ostrzeżenia.
TrimmerRemoveSymbols true lub false Określa, czy wszystkie symbole są usuwane z przyciętej aplikacji.

Następujące właściwości programu MSBuild zostały opisane w tej sekcji:

Opcje kompilatora języka C#, takie jak LangVersion i Nullable, można również określić jako właściwości programu MSBuild w pliku projektu. Aby uzyskać więcej informacji, zobacz Opcje kompilatora języka C#.

DisableImplicitFrameworkDefines

Właściwość DisableImplicitFrameworkDefines określa, czy zestaw SDK generuje symbole preprocesora dla platformy docelowej i platformy dla projektu .NET. Gdy ta właściwość jest ustawiona na false lub nie jest ustawiona (czyli wartość domyślna) symbole preprocesora są generowane dla:

  • Struktura bez wersji (NETFRAMEWORK, NETSTANDARD, NET)
  • Struktura z wersją (NET48, NETSTANDARD2_0, NET6_0)
  • Struktura z minimalną granicą wersji (NET48_OR_GREATER, NETSTANDARD2_0_OR_GREATER, NET6_0_OR_GREATER)

Aby uzyskać więcej informacji na temat obiektów monikerów platform docelowych i tych niejawnych symboli preprocesora, zobacz Platformy docelowe.

Ponadto, jeśli określisz platformę docelową specyficzną dla systemu operacyjnego w projekcie (na przykład net6.0-android), zostaną wygenerowane następujące symbole preprocesora:

  • Platforma bez wersji (ANDROID, IOS, WINDOWS)
  • Platforma z wersją (IOS15_1)
  • Platforma z minimalną granicą wersji (IOS15_1_OR_GREATER)

Aby uzyskać więcej informacji na temat programu monikers platform docelowych specyficznych dla systemu operacyjnego, zobacz Informacje o serwerach TFM specyficznych dla systemu operacyjnego.

Jeśli platforma docelowa oznacza obsługę starszych platform docelowych, emitowane są symbole preprocesora dla tych starszych struktur. Na przykład net6.0oznacza obsługę net5.0 polecenia i tak dalej w drodze powrotnej do .netcoreapp1.0. Dlatego dla każdej z tych platform docelowych zostanie zdefiniowany symbol platformy z minimalną granicą wersji .

DocumentationFile

Właściwość DocumentationFile umożliwia określenie nazwy pliku XML zawierającego dokumentację biblioteki. Aby funkcja IntelliSense działała poprawnie w dokumentacji, nazwa pliku musi być taka sama jak nazwa zestawu i musi znajdować się w tym samym katalogu co zestaw. Jeśli nie określisz tej właściwości, ale ustawisz właściwość GenerateDocumentationFile na truewartość , nazwa pliku dokumentacji domyślnie będzie mieć nazwę zestawu, ale z rozszerzeniem .xml pliku. Z tego powodu często łatwiej jest pominąć tę właściwość i zamiast tego użyć właściwości GenerateDocumentationFile .

Jeśli określisz tę właściwość, ale ustawisz właściwość GenerateDocumentationFile na falsewartość , kompilator nie wygeneruje pliku dokumentacji. Jeśli określisz tę właściwość i pominięto właściwość GenerateDocumentationFile, kompilator wygeneruje plik dokumentacji.

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

EmbeddedResourceUseDependentUponConvention

Właściwość EmbeddedResourceUseDependentUponConvention określa, czy nazwy plików manifestu zasobu są generowane na podstawie informacji o typie w plikach źródłowych, które są współlokowane z plikami zasobów. Jeśli na przykład plik Form1.resx znajduje się w tym samym folderze co Form1.cs i EmbeddedResourceUseDependentUponConvention jest ustawiony na truewartość , wygenerowany plik resources przyjmuje nazwę z pierwszego typu zdefiniowanego w formularzu Form1.cs. Jeśli na przykład MyNamespace.Form1 jest pierwszym typem zdefiniowanym w form1.cs, wygenerowana nazwa pliku to MyNamespace.Form1.resources.

Uwaga

Jeśli LogicalNamedla elementu określono EmbeddedResource wartość , ManifestResourceNamelub DependentUpon metadanych, wygenerowana nazwa pliku manifestu dla tego pliku zasobu jest oparta na tych metadanych.

Domyślnie w nowym projekcie platformy .NET ta właściwość jest ustawiona na truewartość . Jeśli dla elementu w pliku projektu określono wartość false, a dla elementu w pliku projektu nie LogicalNameDependentUponManifestResourceNameokreślono EmbeddedResource żadnych metadanych, nazwa pliku manifestu zasobu jest oparta na głównej przestrzeni nazw projektu i względnej ścieżce pliku do pliku resx. Aby uzyskać więcej informacji, zobacz How resource manifest files are named (Jak nazwane są pliki manifestu zasobu).

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

EnablePreviewFeatures

Właściwość EnablePreviewFeatures określa, czy projekt zależy od jakichkolwiek interfejsów API lub zestawów, które są ozdobione atrybutem RequiresPreviewFeaturesAttribute . Ten atrybut służy do oznaczania, że interfejs API lub zestaw używa funkcji, które są uważane za w wersji zapoznawczej dla używanej wersji zestawu SDK. Funkcje w wersji zapoznawczej nie są obsługiwane i mogą zostać usunięte w przyszłej wersji. Aby włączyć korzystanie z funkcji w wersji zapoznawczej, ustaw właściwość na Truewartość .

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

Gdy projekt zawiera tę właściwość ustawioną na Truewartość , do pliku AssemblyInfo zostanie dodany następujący atrybut poziomu zestawu.cs:

[assembly: RequiresPreviewFeatures]

Analizator ostrzega, czy ten atrybut jest obecny w zależnościach dla projektów, w których EnablePreviewFeatures nie ustawiono wartości True.

Autorzy bibliotek, którzy zamierzają dostarczać zestawy w wersji zapoznawczej, powinni ustawić tę właściwość na Truewartość . Jeśli zestaw musi być dostarczony z kombinacją interfejsów API w wersji zapoznawczej i bez wersji zapoznawczej, zobacz sekcję GenerateRequiresPreviewFeaturesAttribute poniżej.

GenerateDocumentationFile

Właściwość GenerateDocumentationFile określa, czy kompilator generuje plik dokumentacji XML dla biblioteki. Jeśli ustawisz tę właściwość true na i nie określisz nazwy pliku za pośrednictwem właściwości DocumentationFile, wygenerowany plik XML zostanie umieszczony w tym samym katalogu wyjściowym co zestaw i ma taką samą nazwę pliku (ale z rozszerzeniem .xml ).

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

Aby uzyskać więcej informacji na temat generowania dokumentacji z komentarzy kodu, zobacz Komentarze dokumentacji XML (C#), Dokumentowanie kodu przy użyciu języka XML (Visual Basic) lub Dokumentowanie kodu przy użyciu języka XML (F#).

GenerateRequiresPreviewFeaturesAttribute

Właściwość GenerateRequiresPreviewFeaturesAttribute jest ściśle powiązana z właściwością EnablePreviewFeatures . Jeśli biblioteka używa funkcji w wersji zapoznawczej, ale nie chcesz, aby cały zestaw był oznaczony atrybutem RequiresPreviewFeaturesAttribute , co wymagałoby od użytkowników włączenia funkcji w wersji zapoznawczej, ustaw tę właściwość na Falsewartość .

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

Ważne

Jeśli ustawisz GenerateRequiresPreviewFeaturesAttribute właściwość na Falsewartość , musisz mieć pewność, że wszystkie publiczne interfejsy API, które opierają się na funkcjach w wersji zapoznawczej z .RequiresPreviewFeaturesAttribute

OptimizeImplicitlyTriggeredBuild

Aby przyspieszyć czas kompilacji, kompilacje, które są niejawnie wyzwalane przez program Visual Studio, pomijają analizę kodu, w tym analizę dopuszczaną do wartości null. Program Visual Studio wyzwala niejawną kompilację podczas uruchamiania testów, na przykład. Jednak niejawne kompilacje są optymalizowane tylko wtedy, gdy TreatWarningsAsErrors nie truejest . Jeśli ustawiono TreatWarningsAsErrors wartość , true ale nadal chcesz, aby kompilacje wyzwalane niejawnie zostały zoptymalizowane, możesz ustawić Truewartość OptimizeImplicitlyTriggeredBuild . Aby wyłączyć optymalizację kompilacji dla niejawnie wyzwolonych kompilacji, ustaw wartość OptimizeImplicitlyTriggeredBuildFalse.

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

Domyślne właściwości dołączania elementów

Następujące właściwości programu MSBuild zostały opisane w tej sekcji:

Aby uzyskać więcej informacji, zobacz Domyślne dołączanie i wykluczanie.

DefaultItemExcludes

Użyj właściwości , DefaultItemExcludes aby zdefiniować wzorce globu dla plików i folderów, które powinny zostać wykluczone z elementów dołączania, wykluczania i usuwania globów. Domyślnie foldery ./bin i ./obj są wykluczane z wzorców globu.

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

DefaultItemExcludesInProjectFolder

Użyj właściwości , DefaultItemExcludesInProjectFolder aby zdefiniować wzorce globu dla plików i folderów w folderze projektu, które powinny być wykluczone z elementów dołączania, wykluczania i usuwania globów. Domyślnie foldery rozpoczynające się od kropki (.), takie jak .git i .vs, są wykluczane z wzorców globu.

Ta właściwość jest bardzo podobna DefaultItemExcludes do właściwości, z tą różnicą, że uwzględnia tylko pliki i foldery w folderze projektu. Gdy wzorzec globu przypadkowo pasuje do elementów spoza folderu projektu ze ścieżką względną, użyj DefaultItemExcludesInProjectFolder właściwości zamiast DefaultItemExcludes właściwości .

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

EnableDefaultItems

Właściwość EnableDefaultItems określa, czy elementy kompilowania, osadzone elementy zasobów i None elementy są niejawnie uwzględnione w projekcie. Wartość domyślna to true. EnableDefaultItems Ustaw właściwość na wartość , aby false wyłączyć wszystkie niejawne dołączanie plików.

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

EnableDefaultCompileItems

Właściwość EnableDefaultCompileItems określa, czy elementy kompilacji są niejawnie uwzględnione w projekcie. Wartość domyślna to true. EnableDefaultCompileItems Ustaw właściwość na wartość , aby false wyłączyć niejawne dołączanie *.cs i innych plików rozszerzeń języka.

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

EnableDefaultEmbeddedResourceItems

Właściwość EnableDefaultEmbeddedResourceItems określa, czy osadzone elementy zasobów są niejawnie uwzględnione w projekcie. Wartość domyślna to true. EnableDefaultEmbeddedResourceItems Ustaw właściwość na wartość , aby false wyłączyć niejawne dołączanie osadzonych plików zasobów.

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

EnableDefaultNoneItems

Właściwość EnableDefaultNoneItems określa, czy None elementy (pliki, które nie mają roli w procesie kompilacji) są niejawnie uwzględnione w projekcie. Wartość domyślna to true. EnableDefaultNoneItems Ustaw właściwość na wartość , aby false wyłączyć niejawne dołączanie None elementów.

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

Właściwości analizy kodu

W tej sekcji opisano następujące właściwości programu MSBuild:

AnalysisLevel

Właściwość AnalysisLevel umożliwia określenie zestawu analizatorów kodu do uruchomienia zgodnie z wersją platformy .NET. Każda wersja platformy .NET, począwszy od platformy .NET 5, ma zestaw reguł analizy kodu. W tym zestawie reguły, które są domyślnie włączone dla tej wersji, będą analizować kod. Jeśli na przykład uaktualnisz program do platformy .NET 6, ale nie chcesz, aby domyślny zestaw reguł analizy kodu został zmieniony, ustaw wartość AnalysisLevel5.

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

Opcjonalnie, począwszy od platformy .NET 6, można określić wartość złożoną dla tej właściwości, która określa również, jak agresywnie włączyć reguły. Wartości złożone przyjmują postać <version>-<mode>, gdzie <mode> wartość jest jedną z wartości AnalysisMode . W poniższym przykładzie użyto wersji zapoznawczej analizatorów kodu i włączono zalecany zestaw reguł.

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

Uwaga

Jeśli ustawiono wartość AnalysisLevel5-<mode> lub 5.0-<mode> , a następnie zainstalujesz zestaw .NET 6 SDK i ponownie skompilujesz projekt, mogą pojawić się nieoczekiwane nowe ostrzeżenia dotyczące kompilacji. Aby uzyskać więcej informacji, zobacz dotnet/roslyn-analyzers#5679.

Wartość domyślna:

  • Jeśli projekt jest przeznaczony dla platformy .NET 5 lub nowszej lub jeśli dodano właściwość AnalysisMode , wartość domyślna to latest.
  • W przeciwnym razie ta właściwość zostanie pominięta, chyba że jawnie dodasz ją do pliku projektu.

W poniższej tabeli przedstawiono wartości, które można określić.

Wartość Znaczenie
latest Używane są najnowsze analizatory kodu, które zostały wydane. Jest to opcja domyślna.
latest-<mode> Używane są najnowsze analizatory kodu, które zostały wydane. Wartość <mode> określa, które reguły są włączone.
preview Używane są najnowsze analizatory kodu, nawet jeśli są w wersji zapoznawczej.
preview-<mode> Używane są najnowsze analizatory kodu, nawet jeśli są w wersji zapoznawczej. Wartość <mode> określa, które reguły są włączone.
6.0 Używany jest zestaw reguł, które były dostępne dla wersji .NET 6, nawet jeśli są dostępne nowsze reguły.
6.0-<mode> Używany jest zestaw reguł, które były dostępne dla wersji .NET 6, nawet jeśli są dostępne nowsze reguły. Wartość <mode> określa, które reguły są włączone.
6 Używany jest zestaw reguł, które były dostępne dla wersji .NET 6, nawet jeśli są dostępne nowsze reguły.
6-<mode> Używany jest zestaw reguł, które były dostępne dla wersji .NET 6, nawet jeśli są dostępne nowsze reguły. Wartość <mode> określa, które reguły są włączone.
5.0 Używany jest zestaw reguł, które były dostępne dla wersji .NET 5, nawet jeśli są dostępne nowsze reguły.
5.0-<mode> Używany jest zestaw reguł, które były dostępne dla wersji .NET 5, nawet jeśli są dostępne nowsze reguły. Wartość <mode> określa, które reguły są włączone.
5 Używany jest zestaw reguł, które były dostępne dla wersji .NET 5, nawet jeśli są dostępne nowsze reguły.
5-<mode> Używany jest zestaw reguł, które były dostępne dla wersji .NET 5, nawet jeśli są dostępne nowsze reguły. Wartość <mode> określa, które reguły są włączone.

Uwaga

  • W programach .NET 5 i starszych ta właściwość ma wpływ tylko na reguły jakości kodu (CAXXXX). Począwszy od platformy .NET 6, jeśli ustawisz wartość EnforceCodeStyleInBuildtruena , ta właściwość wpływa również na reguły stylu kodu (IDEXXXX).
  • Jeśli ustawisz wartość złożoną dla AnalysisLevelelementu , nie musisz określać elementu AnalysisMode. Jeśli jednak to zrobisz, AnalysisLevel pierwszeństwo ma wartość AnalysisMode.
  • Ta właściwość nie ma wpływu na analizę kodu w projektach, które nie odwołują się do zestawu SDK projektu, na przykład starsze projekty .NET Framework odwołujące się do pakietu NuGet Microsoft.CodeAnalysis.NetAnalyzers.

AnalysisLevel<, kategoria>

Wprowadzona na platformie .NET 6 ta właściwość jest taka sama jak AnalysisLevel, z tą różnicą, że ma zastosowanie tylko do określonej kategorii reguł analizy kodu. Ta właściwość umożliwia używanie innej wersji analizatorów kodu dla określonej kategorii lub włączania lub wyłączania reguł na innym poziomie do innych kategorii reguł. Jeśli pominiesz tę właściwość dla określonej kategorii reguł, domyślnie zostanie ustawiona wartość AnalysisLevel . Dostępne wartości są takie same jak w przypadku elementu AnalysisLevel.

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

W poniższej tabeli wymieniono nazwę właściwości dla każdej kategorii reguł.

Nazwa właściwości Kategoria reguł
<AnalysisLevelDesign> Reguły projektowania
<AnalysisLevelDocumentation> Reguły dokumentacji
<AnalysisLevelGlobalization> Reguły globalizacji
<AnalysisLevelInteroperability> Reguły dotyczące przenośności i współdziałania
<AnalysisLevelMaintainability> Reguły utrzymania kodu
<AnalysisLevelNaming> Reguły nazewnictwa
<AnalysisLevelPerformance> Reguły wydajności
<AnalysisLevelSingleFile> Reguły aplikacji jednoplikowych
<AnalysisLevelReliability> Reguły dotyczące niezawodności
<AnalysisLevelSecurity> Reguły zabezpieczeń
<AnalysisLevelStyle> Reguły stylu kodu (IDEXXXXXX)
<AnalysisLevelUsage> Reguły użycia

AnalysisMode

Począwszy od platformy .NET 5, zestaw SDK platformy .NET jest dostarczany ze wszystkimi regułami jakości kodu "CA". Domyślnie tylko niektóre reguły są włączone jako ostrzeżenia kompilacji w każdej wersji platformy .NET. Właściwość AnalysisMode umożliwia dostosowanie zestawu reguł, które są domyślnie włączone. Możesz przełączyć się na bardziej agresywny tryb analizy, w którym możesz zrezygnować z reguł pojedynczo lub bardziej konserwatywny tryb analizy, w którym możesz wyrazić zgodę na określone reguły. Jeśli na przykład chcesz włączyć wszystkie reguły jako ostrzeżenia kompilacji, ustaw wartość na All.

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

W poniższej tabeli przedstawiono dostępne wartości opcji na platformie .NET 5 i .NET 6. Są one wymienione w kolejności rosnącej liczby reguł, które włączają.

Wartość .NET 6+ Wartość .NET 5 Znaczenie
None AllDisabledByDefault Wszystkie reguły są wyłączone. Możesz selektywnie wyrazić zgodę na poszczególne reguły, aby je włączyć.
Default Default Tryb domyślny, w którym niektóre reguły są włączone jako ostrzeżenia kompilacji, niektóre reguły są włączone jako sugestie ide programu Visual Studio, a pozostałe są wyłączone.
Minimum Nie dotyczy Tryb bardziej agresywny Default niż tryb. Niektóre sugestie, które są zdecydowanie zalecane w przypadku wymuszania kompilacji, są włączone jako ostrzeżenia kompilacji.
Recommended Nie dotyczy Bardziej agresywny tryb niż Minimum tryb, w którym więcej reguł jest włączanych jako ostrzeżenia kompilacji.
All AllEnabledByDefault Wszystkie reguły są włączone jako ostrzeżenia kompilacji. Możesz selektywnie zrezygnować z poszczególnych reguł, aby je wyłączyć.

Uwaga

  • Na platformie .NET 5 ta właściwość ma wpływ tylko na reguły jakości kodu (CAXXXX). Począwszy od platformy .NET 6, jeśli ustawisz wartość EnforceCodeStyleInBuild na truewartość , ta właściwość również wpływa na reguły stylu kodu (IDEXXXX).
  • Jeśli używasz wartości złożonej dla elementu AnalysisLevel, <AnalysisLevel>5-recommended</AnalysisLevel>na przykład , możesz całkowicie pominąć tę właściwość. Jeśli jednak określisz obie właściwości, AnalysisLevel pierwszeństwo AnalysisModema wartość .
  • Jeśli AnalysisMode ustawiono wartość AllEnabledByDefault i AnalysisLevel jest ustawiona na 5.05 lub , a następnie zainstalujesz zestaw SDK platformy .NET 6 i ponownie skompilujesz projekt, mogą zostać wyświetlone nieoczekiwane ostrzeżenia dotyczące nowej kompilacji. Aby uzyskać więcej informacji, zobacz dotnet/roslyn-analyzers#5679.
  • Ta właściwość nie ma wpływu na analizę kodu w projektach, które nie odwołują się do zestawu SDK projektu, na przykład starsze projekty .NET Framework odwołujące się do pakietu NuGet Microsoft.CodeAnalysis.NetAnalyzers.

Kategoria AnalysisMode<>

Wprowadzona na platformie .NET 6 ta właściwość jest taka sama jak funkcja AnalysisMode, z tą różnicą, że dotyczy tylko określonej kategorii reguł analizy kodu. Ta właściwość umożliwia włączanie lub wyłączanie reguł na innym poziomie do innych kategorii reguł. Jeśli pominiesz tę właściwość dla określonej kategorii reguł, domyślnie zostanie ustawiona wartość AnalysisMode . Dostępne wartości są takie same jak w przypadku funkcji AnalysisMode.

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

W poniższej tabeli wymieniono nazwę właściwości dla każdej kategorii reguł.

Nazwa właściwości Kategoria reguły
<AnalysisModeDesign> Reguły projektowania
<AnalysisModeDocumentation> Reguły dokumentacji
<AnalysisModeGlobalization> Reguły globalizacji
<AnalysisModeInteroperability> Reguły dotyczące przenośności i współdziałania
<AnalysisModeMaintainability> Reguły utrzymania kodu
<AnalysisModeNaming> Reguły nazewnictwa
<AnalysisModePerformance> Reguły wydajności
<AnalysisModeSingleFile> Reguły aplikacji jednoplikowych
<AnalysisModeReliability> Reguły dotyczące niezawodności
<AnalysisModeSecurity> Reguły zabezpieczeń
<AnalysisModeStyle> Reguły stylu kodu (IDEXXXX)
<AnalysisModeUsage> Reguły użycia

CodeAnalysisTreatWarningsAsErrors

Właściwość CodeAnalysisTreatWarningsAsErrors umożliwia skonfigurowanie, czy ostrzeżenia analizy jakości kodu (CAxxxx) powinny być traktowane jako ostrzeżenia i przerwać kompilację. Jeśli używasz flagi -warnaserror podczas tworzenia projektów, ostrzeżenia analizy jakości kodu platformy .NET są również traktowane jako błędy. Jeśli nie chcesz, aby ostrzeżenia analizy jakości kodu były traktowane jako błędy, możesz ustawić CodeAnalysisTreatWarningsAsErrors właściwość MSBuild na false wartość w pliku projektu.

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

EnableNETAnalyzers

Analiza jakości kodu platformy .NET jest domyślnie włączona dla projektów przeznaczonych dla platformy .NET 5 lub nowszej. Jeśli programujesz przy użyciu zestawu .NET 5+ SDK, możesz włączyć analizę kodu platformy .NET dla projektów w stylu zestawu SDK przeznaczonych dla wcześniejszych wersji platformy .NET, ustawiając EnableNETAnalyzers właściwość na true. Aby wyłączyć analizę kodu w dowolnym projekcie, ustaw tę właściwość na falsewartość .

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

Uwaga

Ta właściwość ma zastosowanie specjalnie do wbudowanych analizatorów w zestawie SDK platformy .NET 5+. Nie należy jej używać podczas instalowania pakietu analizy kodu NuGet.

EnforceCodeStyleInBuild

Analiza stylu kodu platformy .NET jest domyślnie wyłączona podczas kompilacji dla wszystkich projektów platformy .NET. Analizę stylu kodu dla projektów platformy .NET można włączyć, ustawiając EnforceCodeStyleInBuild właściwość na true.

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

Wszystkie reguły stylu kodu, które są skonfigurowane jako ostrzeżenia lub błędy, będą wykonywane w przypadku naruszeń kompilacji i raportowania.

Uwaga

Jeśli zainstalujesz program .NET 6 (lub Visual Studio 2022, który obejmuje platformę .NET 6), ale chcesz skompilować projekt przy użyciu programu Visual Studio 2019, może zostać wyświetlone nowe ostrzeżenia CS8032 , jeśli właściwość jest ustawiona EnforceCodeStyleInBuild na true. Aby rozwiązać problemy z ostrzeżeniami, możesz określić wersję zestawu .NET SDK do skompilowania projektu za pomocą polecenia (w tym przypadku coś podobnego 5.0.404do ) przez dodanie wpisu global.json.

_SkipUpgradeNetAnalyzersNuGetWarning

Właściwość _SkipUpgradeNetAnalyzersNuGetWarning umożliwia skonfigurowanie, czy jest wyświetlane ostrzeżenie, jeśli używasz analizatorów kodu z pakietu NuGet, który jest nieaktualny w porównaniu z analizatorami kodu w najnowszym zestawie SDK platformy .NET. Ostrzeżenie wygląda podobnie do następującego:

Zestaw .NET SDK ma nowsze analizatory w wersji "6.0.0" niż w wersji "5.0.3" pakietu "Microsoft.CodeAnalysis.NetAnalyzers". Zaktualizuj lub usuń to odwołanie do pakietu.

Aby usunąć to ostrzeżenie i nadal używać wersji analizatorów kodu w pakiecie NuGet, ustaw wartość _SkipUpgradeNetAnalyzersNuGetWarning na true w pliku projektu.

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

Właściwości konfiguracji środowiska uruchomieniowego

Niektóre zachowania czasu wykonywania można skonfigurować, określając właściwości programu MSBuild w pliku projektu aplikacji. Aby uzyskać informacje o innych sposobach konfigurowania zachowania środowiska uruchomieniowego, zobacz Ustawienia konfiguracji środowiska uruchomieniowego.

ConcurrentGarbageCollection

Właściwość ConcurrentGarbageCollection określa, czy funkcja odzyskiwania pamięci w tle (współbieżna) jest włączona. Ustaw wartość , aby false wyłączyć odzyskiwanie pamięci w tle. Aby uzyskać więcej informacji, zobacz Tło GC.

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

Niezmienna globalizacja

Właściwość InvariantGlobalization określa, czy aplikacja działa w trybie niezmiennym globalizacji , co oznacza, że nie ma dostępu do danych specyficznych dla kultury. Ustaw wartość na , aby true uruchomić w trybie niezmiennym globalizacji. Aby uzyskać więcej informacji, zobacz Tryb niezmienny.

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

PredefinedCulturesOnly

W programie .NET 6 i nowszych wersjach właściwość określa, PredefinedCulturesOnly czy aplikacje mogą tworzyć kultury inne niż niezmienna kultura, gdy jest włączony tryb niezmienny globalizacji . Wartość domyślna to true. Ustaw wartość , aby false umożliwić tworzenie dowolnej nowej kultury w trybie niezmiennym globalizacji.

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

Aby uzyskać więcej informacji, zobacz Tworzenie kultury i mapowanie wielkości liter w trybie niezmiennym globalizacji.

RetainVMGarbageCollection

Właściwość RetainVMGarbageCollection umożliwia skonfigurowanie modułu odśmiecającego do umieszczania usuniętych segmentów pamięci na liście rezerwowej na potrzeby ich przyszłego użycia lub zwolnienia. Ustawienie wartości , aby true informuje moduł odśmieceń pamięci, aby umieścić segmenty na liście rezerwowej. Aby uzyskać więcej informacji, zobacz Zachowywanie maszyny wirtualnej.

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

ServerGarbageCollection

Właściwość ServerGarbageCollection określa, czy aplikacja używa odzyskiwania pamięci stacji roboczej, czy odzyskiwania pamięci serwera. Ustaw wartość na , aby true używać odzyskiwania pamięci serwera. Aby uzyskać więcej informacji, zobacz Stacja robocza a serwer.

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

ThreadPoolMaxThreads

Właściwość ThreadPoolMaxThreads konfiguruje maksymalną liczbę wątków dla puli wątków roboczych. Aby uzyskać więcej informacji, zobacz Maksymalna liczba wątków.

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

ThreadPoolMinThreads

Właściwość ThreadPoolMinThreads konfiguruje minimalną liczbę wątków dla puli wątków roboczych. Aby uzyskać więcej informacji, zobacz Minimalne wątki.

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

TieredCompilation

Właściwość TieredCompilation określa, czy kompilator just in time (JIT) używa kompilacji warstwowej. Ustaw wartość na wartość , false aby wyłączyć kompilację warstwową. Aby uzyskać więcej informacji, zobacz Kompilacja warstwowa.

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

TieredCompilationQuickJit

Właściwość TieredCompilationQuickJit określa, czy kompilator JIT używa szybkiego trybu JIT. Ustaw wartość , aby false wyłączyć szybki dostęp JIT. Aby uzyskać więcej informacji, zobacz Szybki dostęp JIT.

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

TieredCompilationQuickJitForLoops

Właściwość TieredCompilationQuickJitForLoops określa, czy kompilator JIT używa szybkiego dostępu JIT w metodach zawierających pętle. Ustaw wartość , aby true włączyć szybki dostęp JIT dla metod, które zawierają pętle. Aby uzyskać więcej informacji, zobacz Quick JIT for loops (Szybki dostęp JIT dla pętli).

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

Właściwości odwołania

Następujące właściwości programu MSBuild zostały opisane w tej sekcji:

AssetTargetFallback

Właściwość AssetTargetFallback umożliwia określenie dodatkowych zgodnych wersji platformy dla odwołań do projektu i pakietów NuGet. Jeśli na przykład określisz zależność pakietu przy użyciu polecenia PackageReference , ale ten pakiet nie zawiera zasobów, które są zgodne z projektami TargetFramework, AssetTargetFallback właściwość wchodzi w grę. Zgodność przywoływanego pakietu jest ponownie zaznaczona przy użyciu każdej platformy docelowej określonej w elemencie AssetTargetFallback. Ta właściwość zastępuje przestarzałą właściwość PackageTargetFallback.

Właściwość można ustawić AssetTargetFallback na co najmniej jedną wersję platformy docelowej.

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

DisableImplicitFrameworkReferences

Właściwość DisableImplicitFrameworkReferences kontroluje niejawne FrameworkReference elementy podczas określania wartości docelowej dla platformy .NET Core 3.0 i nowszych wersji. W przypadku określania wartości docelowej dla platformy .NET Core 2.1 lub .NET Standard 2.0 i starszych wersji kontroluje niejawne elementy PackageReference do pakietów w metapakiecie. (Metapakiet to pakiet oparty na strukturze, który składa się tylko z zależności od innych pakietów). Ta właściwość kontroluje również niejawne odwołania, takie jak System i System.Core podczas określania wartości docelowej .NET Framework.

Ustaw tę właściwość na wartość , aby true wyłączyć elementy niejawne FrameworkReference lub PackageReference . Jeśli ustawisz tę właściwość na truewartość , możesz dodać jawne odwołania tylko do potrzebnych struktur lub pakietów.

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

DisableTransitiveProjectReferences

Właściwość DisableTransitiveProjectReferences kontroluje niejawne odwołania do projektu. Ustaw tę właściwość na wartość , aby true wyłączyć niejawne ProjectReference elementy. Wyłączenie niejawnych odwołań do projektu powoduje zachowanie nie przechodnie podobne do starszego systemu projektu.

Gdy ta właściwość ma truewartość , ma podobny wpływ na ustawienie PrivateAssets="All" dla wszystkich zależności projektu zależnego.

Jeśli ustawisz tę właściwość na truewartość , możesz dodać jawne odwołania tylko do potrzebnych projektów.

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

Przywrócenie pakietu, do których odwołuje się odwołanie, instaluje wszystkie jego bezpośrednie zależności i wszystkie zależności tych zależności. Przywracanie pakietów można dostosować, określając właściwości, takie jak RestorePackagesPath i RestoreIgnoreFailedSources. Aby uzyskać więcej informacji na temat tych i innych właściwości, zobacz przywracanie obiektu docelowego.

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

ValidateExecutableReferencesMatchSelfContained

Właściwość ValidateExecutableReferencesMatchSelfContained może służyć do wyłączania błędów związanych z odwołaniami do projektu wykonywalnego. Jeśli platforma .NET wykryje, że samodzielny projekt wykonywalny odwołuje się do projektu wykonywalnego zależnego od struktury lub odwrotnie, generuje on błędy NETSDK1150 i NETSDK1151. Aby uniknąć tych błędów, gdy odwołanie jest zamierzone, ustaw ValidateExecutableReferencesMatchSelfContained właściwość na falsewartość .

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

WindowsSdkPackageVersion

Właściwość WindowsSdkPackageVersion może służyć do zastępowania wersji pakietu określania wartości docelowej zestawu Windows SDK. Ta właściwość została wprowadzona na platformie .NET 5 i zastępuje w tym celu użycie FrameworkReference elementu.

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

Uwaga

Nie zalecamy zastępowania wersji zestawu Windows SDK, ponieważ pakiety przeznaczone dla zestawu SDK systemu Windows są dołączone do zestawu .NET 5+ SDK. Zamiast tego, aby odwołać się do najnowszego pakietu zestawu Windows SDK, zaktualizuj wersję zestawu .NET SDK. Tej właściwości należy używać tylko w rzadkich przypadkach, takich jak używanie pakietów w wersji zapoznawczej lub konieczność zastąpienia wersji C#/WinRT.

Następujące właściwości są używane do uruchamiania aplikacji za dotnet run pomocą polecenia :

RunArguments

Właściwość RunArguments definiuje argumenty przekazywane do aplikacji podczas jej uruchamiania.

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

Porada

Możesz określić dodatkowe argumenty, które mają zostać przekazane do aplikacji, używając -- opcji .dotnet run

RunWorkingDirectory

Właściwość RunWorkingDirectory definiuje katalog roboczy, w ramach których ma zostać uruchomiony proces aplikacji. Może to być ścieżka bezwzględna lub ścieżka względna względem katalogu projektu. Jeśli nie określisz katalogu, OutDir zostanie użyty jako katalog roboczy.

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

Następujące właściwości programu MSBuild zostały opisane w tej sekcji:

EnableComHosting

Właściwość EnableComHosting wskazuje, że zestaw udostępnia serwer COM. Ustawienie parametru na EnableComHostingtrue wartość oznacza również, że parametr EnableDynamicLoading to true.

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

Aby uzyskać więcej informacji, zobacz Uwidacznij składniki platformy .NET w modelu COM.

EnableDynamicLoading

Właściwość EnableDynamicLoading wskazuje, że zestaw jest dynamicznie ładowanym składnikiem. Składnik może być biblioteką COM lub biblioteką inną niż COM, która może być używana z hosta natywnego lub używana jako wtyczka. Ustawienie tej właściwości na true ma następujące efekty:

  • Zostanie wygenerowany plik runtimeconfig.json .
  • Właściwość RollForward jest ustawiona na LatestMinorwartość .
  • Odwołania nuGet są kopiowane lokalnie.
<PropertyGroup>
  <EnableDynamicLoading>true</EnableDynamicLoading>
</PropertyGroup>

Wygenerowane właściwości pliku

Następujące właściwości dotyczą kodu w wygenerowanych plikach:

DisableImplicitNamespaceImports

Właściwość DisableImplicitNamespaceImports może służyć do wyłączania niejawnych importów przestrzeni nazw w projektach Visual Basic przeznaczonych dla platformy .NET 6 lub nowszej. Niejawne przestrzenie nazw to domyślne przestrzenie nazw importowane globalnie w projekcie Visual Basic. Ustaw tę właściwość na wartość , aby true wyłączyć niejawne importy przestrzeni nazw.

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

Niejawne jednostki organizacyjne

Właściwość może służyć do włączania ImplicitUsings i wyłączania niejawnych global using dyrektyw w projektach języka C#, które są przeznaczone dla platformy .NET 6 lub nowszej wersji oraz języka C# 10 lub nowszej. Po włączeniu tej funkcji zestaw SDK platformy .NET dodaje global using dyrektywy dla zestawu domyślnych przestrzeni nazw na podstawie typu zestawu SDK projektu. Ustaw tę właściwość na true lub enable , aby włączyć niejawne global using dyrektywy. Aby wyłączyć niejawne global using dyrektywy, usuń właściwość lub ustaw ją na false lub disable.

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

Uwaga

Szablony dla nowych projektów języka C#, które są przeznaczone dla platformy .NET 6 lub nowszej, domyślnie mają ImplicitUsings ustawioną enable wartość .

Aby zdefiniować jawną global using dyrektywę, dodaj element Using .

Elementy

Elementy programu MSBuild są danymi wejściowymi w systemie kompilacji. Elementy są określane zgodnie z ich typem, czyli nazwą elementu. Na przykład Compile i Reference są dwoma typowymi typami elementów. Następujące dodatkowe typy elementów są udostępniane przez zestaw .NET SDK:

W tych elementach można użyć dowolnego ze standardowych atrybutów elementu, Include na przykład i Update. Służy Include do dodawania nowego elementu i modyfikowania istniejącego elementu za pomocą polecenia Update . Na przykład Update jest często używany do modyfikowania elementu, który został niejawnie dodany przez zestaw SDK platformy .NET.

AssemblyMetadata

Element AssemblyMetadata określa atrybut zestawu pary AssemblyMetadataAttribute klucz-wartość. Metadane Include stają się kluczem, a Value metadane stają się wartością.

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

InternalsVisibleTo

Element InternalsVisibleTo generuje InternalsVisibleToAttribute atrybut zestawu dla określonego zestawu zaprzyjaźnionego.

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

Jeśli zestaw znajomy jest podpisany, możesz określić opcjonalne Key metadane, aby określić jego pełny klucz publiczny. Jeśli nie określisz Key metadanych i $(PublicKey) parametr jest dostępny, zostanie użyty ten klucz. W przeciwnym razie do atrybutu nie zostanie dodany żaden klucz publiczny.

PackageReference

Element PackageReference definiuje odwołanie do pakietu NuGet.

Atrybut Include określa identyfikator pakietu. Atrybut Version określa wersję lub zakres wersji. Aby uzyskać informacje na temat określania minimalnej wersji, maksymalnej wersji, zakresu lub dokładnego dopasowania, zobacz Zakresy wersji.

Fragment pliku projektu w poniższym przykładzie odwołuje się do pakietu System.Runtime .

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

Możesz również kontrolować zasoby zależności przy użyciu metadanych, takich jak PrivateAssets.

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

Aby uzyskać więcej informacji, zobacz Odwołania do pakietów w plikach projektu.

TrimmerRootAssembly

Element TrimmerRootAssembly umożliwia wykluczenie zestawu z przycinania. Przycinanie to proces usuwania nieużywanych części środowiska uruchomieniowego z spakowanej aplikacji. W niektórych przypadkach przycinanie może niepoprawnie usunąć wymagane odwołania.

Poniższy kod XML wyklucza System.Security zestaw z przycinania.

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

Aby uzyskać więcej informacji, zobacz Opcje przycinania.

Używanie

Element Using umożliwia globalne dołączenie przestrzeni nazw w projekcie języka C#, tak aby nie trzeba było dodawać using dyrektywy dla przestrzeni nazw w górnej części plików źródłowych. Ten element jest podobny do Import elementu, który może być używany do tego samego celu w projektach Visual Basic. Ta właściwość jest dostępna od platformy .NET 6.

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

Element można również użyć Using do zdefiniowania globalnych using <alias> dyrektyw i using static <type> .

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

Przykład:

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

Aby uzyskać więcej informacji na temat dyrektyw i using static <type> dyrektyw aliasówusing, zobacz using directive (Używanie dyrektywy).

Metadane elementu

Oprócz standardowych atrybutów elementu MSBuild następujące tagi metadanych elementu są udostępniane przez zestaw SDK platformy .NET:

CopyToPublishDirectory

Metadane CopyToPublishDirectory elementu MSBuild steruje kopiowaniem elementu do katalogu publikowania. Dozwolone wartości to PreserveNewest, które kopiują tylko element, jeśli został zmieniony, Always, który zawsze kopiuje element i Never, który nigdy nie kopiuje elementu. Z punktu widzenia wydajności jest preferowane, PreserveNewest ponieważ umożliwia kompilację przyrostową.

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

LinkBase

W przypadku elementu spoza katalogu projektu i jego podkatalogów element docelowy publikowania używa metadanych Link elementu w celu określenia, gdzie skopiować element. LinkOkreśla również sposób wyświetlania elementów spoza drzewa projektu w oknie Eksplorator rozwiązań programu Visual Studio.

Jeśli Link nie określono elementu spoza stożka projektu, wartość domyślna to %(LinkBase)\%(RecursiveDir)%(Filename)%(Extension). LinkBase Umożliwia określenie rozsądnego folderu podstawowego dla elementów spoza stożka projektu. Hierarchia folderów w folderze podstawowym jest zachowywana za pomocą polecenia RecursiveDir. Jeśli LinkBase nie zostanie określony, zostanie pominięty ze ścieżki Link .

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

Na poniższej ilustracji przedstawiono sposób wyświetlania pliku dołączonego za pośrednictwem poprzedniego elementu Include glob w Eksplorator rozwiązań.

Eksplorator rozwiązań elementu z metadanymi LinkBase.

Zobacz też