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
Następujące właściwości programu MSBuild zostały opisane w tej sekcji:
TargetFramework
Właściwość TargetFramework
określa wersję platformy docelowej dla aplikacji. Aby uzyskać listę prawidłowych szablonów platform docelowych, zobacz Target frameworks in SDK-style projects (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
TargetFrameworks
Użyj właściwości , jeśli aplikacja ma być docelowa dla wielu platform. Aby uzyskać listę prawidłowych szablonów platform docelowych, zobacz Target frameworks in SDK-style projects (Platformy docelowe w projektach w stylu zestawu SDK).
Uwaga
Ta właściwość jest ignorowana, jeśli TargetFramework
określono (pojedynczą).
<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ść ma zastosowanie tylko do projektów przy użyciu polecenia netstandard1.x
. Nie dotyczy projektów korzystających z programu netstandard2.x
.
NetStandardImplicitPackageVersion
Użyj właściwości , jeśli chcesz określić wersję platformy niższą niż wersja metapakiet. Plik projektu w poniższych przykładowych miejscach docelowych netstandard1.3
, ale używa wersji 1.6.0 programu 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 steruje nazwą wygenerowanego pliku.
Gdy wartość to GenerateAssemblyInfo
true
, właściwości projektu związane 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 dla poszczególnych atrybutów, 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
iFileVersion
domyślnie wartość bez$(Version)
sufiksu. Jeśli na przykład$(Version)
wartość to1.2.3-beta.4
, wartość to1.2.3
.InformationalVersion
wartość domyślna to .$(Version)
$(SourceRevisionId)
Jeśli właściwość jest obecna, zostanie ona dołączona do elementuInformationalVersion
. To zachowanie można wyłączyć przy użyciu poleceniaIncludeSourceRevisionInInformationalVersion
.Copyright
właściwości iDescription
są również używane dla metadanych NuGet.Configuration
, który domyślnie ma wartość , jest współużytkowany ze wszystkimi elementami docelowymiDebug
programu MSBuild. Można go ustawić za pomocą--configuration
opcjidotnet
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 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 pliku kodu tymczasowego zawierającego atrybuty informacji o zestawie, ustawiając wartość
GenerateAssemblyInfo
nafalse
w pliku projektu. Dzięki temu można zachować plik AssemblyInfo . - Przeprowadź migrację ustawień w
AssemblyInfo
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 jest to plik o nazwie [project-name]. Assemblyinfo. [cs|vb]$(IntermediateOutputPath)
w katalogu (zwykle obj).
<PropertyGroup>
<GeneratedAssemblyInfoFile>assemblyinfo.cs</GeneratedAssemblyInfoFile>
</PropertyGroup>
Właściwości pakietu
Właściwości opisowe
Można określić właściwości, takie jak PackageId
, PackageVersion
, PackageIcon
, Title
i Description
, w celu opisania pakietu tworzonego na podstawie projektu. Aby uzyskać informacje o tych i innych właściwościach, zobacz pack target (Element 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
. Ta właściwość została wprowadzona na platformie .NET 7.
<PropertyGroup>
<PackRelease>true</PackRelease>
</PropertyGroup>
Uwaga
- Począwszy od zestawu .NET 8 SDK,
PackRelease
wartość domyślna totrue
. Aby uzyskać więcej informacji, zobacz temat "dotnet pack" używa konfiguracji wydania. - Tylko zestaw SDK platformy .NET 7: aby użyć
PackRelease
w projekcie, który jest częścią rozwiązania programu Visual Studio, musisz ustawić zmienną środowiskowąDOTNET_CLI_ENABLE_PACK_RELEASE_FOR_SOLUTIONS
natrue
(lub dowolną inną wartość). W przypadku rozwiązań, które mają wiele projektów, ustawienie tej zmiennej zwiększa czas wymagany do spakowania.
Właściwości związane z publikowaniem
Następujące właściwości programu MSBuild zostały opisane w tej sekcji:
- AppendRuntimeIdentifierToOutputPath
- AppendTargetFrameworkToOutputPath
- CopyLocalLockFileAssemblies
- EnablePackageValidation
- ErrorOnDuplicatePublishOutputFiles
- GenerateRuntimeConfigDevFile
- GenerateRuntimeConfigurationFiles
- GenerateSatelliteAssembliesForCore
- IsPublishable
- PreserveCompilationContext
- PreserveCompilationReferences
- ProduceReferenceAssemblyInOutDir
- PublishDocumentationFile
- PublishDocumentationFiles
- PublishReferencesDocumentationFiles
- Publikowanie wersji
- RollForward
- RuntimeFrameworkVersion
- RuntimeIdentifier
- RuntimeIdentifiers
- SatelliteResourceLanguages
- UseAppHost
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-x64
zmienia 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 true
wartość , 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:
- Chcesz użyć opcji kompilatora
deterministic
języka C#. - Ogranicza Cię fakt, że al.exe nie ma poparcia dla podpisywania publicznego i radzi AssemblyInformationalVersionAttribute sobie słabo.
<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.
PublishDocumentationFile
Gdy ta właściwość to true
, plik dokumentacji XML dla projektu, jeśli został wygenerowany, jest uwzględniony w danych wyjściowych publikowania dla projektu. Ta właściwość jest domyślnie ustawiona na true
.
Porada
Ustaw wartość GenerateDocumentationFile , aby true
wygenerować plik dokumentacji XML w czasie kompilacji.
PublishDocumentationFiles
Ta właściwość jest flagą włączania dla kilku innych właściwości, które kontrolują, czy różne rodzaje plików dokumentacji XML są domyślnie kopiowane do katalogu publikowania, a mianowicie PublishDocumentationFile i PublishReferencesDocumentationFiles. Jeśli te właściwości nie są ustawione, a ta właściwość jest ustawiona, te właściwości będą domyślnie ustawione na true
. Ta właściwość jest domyślnie ustawiona na true
.
PublishReferencesDocumentationFiles
Gdy ta właściwość to true
, pliki dokumentacji XML dla odwołań projektu są kopiowane do katalogu publikowania, a nie tylko zasoby środowiska uruchomieniowego, takie jak pliki DLL. Ta właściwość jest domyślnie ustawiona na true
.
Publikowanie wersji
Właściwość PublishRelease
informuje dotnet publish
o domyślnym Release
użyciu konfiguracji zamiast Debug
konfiguracji. Ta właściwość została wprowadzona na platformie .NET 7.
<PropertyGroup>
<PublishRelease>true</PublishRelease>
</PropertyGroup>
Uwaga
- Począwszy od zestawu .NET 8 SDK,
PublishRelease
domyślnie jest to przeznaczonetrue
dla projektów przeznaczonych dla platformy .NET 8 lub nowszej. Aby uzyskać więcej informacji, zobacz "dotnet publish" używa konfiguracji wydania. - Ta właściwość nie ma wpływu na zachowanie
dotnet build /t:Publish
programu i zmienia konfigurację tylko podczas publikowania za pośrednictwem interfejsu wiersza polecenia platformy .NET. - Tylko zestaw SDK platformy .NET 7: aby użyć
PublishRelease
w projekcie, który jest częścią rozwiązania programu Visual Studio, musisz ustawić zmiennąDOTNET_CLI_ENABLE_PUBLISH_RELEASE_FOR_SOLUTIONS
środowiskową natrue
(lub dowolną inną wartość). Podczas publikowania rozwiązania z włączoną tą zmienną wartość projektuPublishRelease
wykonywalnego ma pierwszeństwo i przepływa nową konfigurację domyślną do innych projektów w rozwiązaniu. Jeśli rozwiązanie zawiera wiele projektów wykonywalnych lub najwyższegoPublishRelease
poziomu z różnymi wartościami, rozwiązanie nie zostanie pomyślnie opublikowane. W przypadku rozwiązań, które mają wiele projektów, użycie tego ustawienia zwiększa czas wymagany do opublikowania.
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) i niemieckich (Niemcy).
<PropertyGroup>
<SatelliteResourceLanguages>en-US;de-DE</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.
Aby określić wiele języków jako argument ,
dotnet publish
należy dodać trzy pary cudzysłowów wokół identyfikatorów języka. Na przykład:dotnet msbuild multi.msbuildproj -p:SatelliteResourceLanguages="""de;en"""
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 wersjach .NET Core 3.0 i nowszych domyślnie tworzony jest plik wykonywalny zależny od platformy. UseAppHost
Ustaw właściwość na wartość , aby false
wyłączyć generowanie pliku wykonywalnego.
<PropertyGroup>
<UseAppHost>false</UseAppHost>
</PropertyGroup>
Aby uzyskać więcej informacji na temat wdrażania, zobacz Wdrażanie aplikacji .NET.
Właściwości związane z przycinaniem
Wiele właściwości programu MSBuild jest dostępnych w celu dostosowania przycinania, która 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. Możesz włączyć analizę, nawet jeśli PublishTrimmed ustawiono 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 na true wartość . |
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 aplikacji przycinanej. |
Właściwości związane z kompilacją
W tej sekcji opisano następujące właściwości programu MSBuild:
- ContinuousIntegrationBuild
- CopyDebugSymbolFilesFromPackages
- CopyDocumentationFilesFromPackages
- DisableImplicitFrameworkDefines
- DocumentationFile
- EmbeddedResourceUseDependentUponConvention
- EnablePreviewFeatures
- EnableWindowsTargeting
- GenerateDocumentationFile
- GenerateRequiresPreviewFeaturesAttribute
- OptimizeImplicitlyTriggeredBuild
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#.
ContinuousIntegrationBuild
Właściwość wskazuje, czy kompilacja ContinuousIntegrationBuild
jest uruchamiana na serwerze ciągłej integracji(CI). W przypadku ustawienia na wartość true
ta właściwość włącza ustawienia, które mają zastosowanie tylko do oficjalnych kompilacji, w przeciwieństwie do kompilacji lokalnych na maszynie dewelopera. Na przykład przechowywane ścieżki plików są znormalizowane dla oficjalnych kompilacji. Jednak na lokalnej maszynie programistycznej debuger nie będzie mógł znaleźć lokalnych plików źródłowych, jeśli ścieżki plików są znormalizowane.
Możesz użyć zmiennej systemu ciągłej integracji, aby warunkowo ustawić ContinuousIntegrationBuild
właściwość. Na przykład nazwa zmiennej usługi Azure Pipelines to TF_BUILD
:
<PropertyGroup Condition="'$(TF_BUILD)' == 'true'">
<ContinuousIntegrationBuild>true</ContinuousIntegrationBuild>
</PropertyGroup>
W przypadku GitHub Actions nazwa zmiennej to GITHUB_ACTIONS
:
<PropertyGroup Condition="'$(GITHUB_ACTIONS)' == 'true'">
<ContinuousIntegrationBuild>true</ContinuousIntegrationBuild>
</PropertyGroup>
CopyDebugSymbolFilesFromPackages
Gdy ta właściwość jest ustawiona na true
wartość , wszystkie pliki symboli (znane również jako pliki PDB) z PackageReference
elementów w projekcie są kopiowane do danych wyjściowych kompilacji. Te pliki mogą zapewnić więcej śladów stosu informacyjnego dla wyjątków i ułatwić zrozumienie zrzutów pamięci i śladów uruchomionej aplikacji. Jednak uwzględnienie tych plików powoduje zwiększenie rozmiaru pakietu wdrożenia.
Ta właściwość została wprowadzona w zestawie .NET SDK 7.0.100, ale domyślnie nie jest określona.
CopyDocumentationFilesFromPackages
Gdy ta właściwość jest ustawiona na true
wartość , wszystkie wygenerowane pliki dokumentacji XML z PackageReference
elementów w projekcie są kopiowane do danych wyjściowych kompilacji. Należy pamiętać, że włączenie tej funkcji spowoduje zwiększenie rozmiaru pakietu wdrożenia.
Ta właściwość została wprowadzona w zestawie .NET SDK 7.0.100, ale domyślnie nie jest określona.
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 jest nieskonfigurowana (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 docelowych monikers i tych niejawnych symboli preprocesora, zobacz Platformy docelowe.
Ponadto w przypadku określenia struktury docelowej specyficznej dla systemu operacyjnego w projekcie (na przykład net6.0-android
) są generowane 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 platform docelowych specyficznych dla systemu operacyjnego, zobacz Program TFMs specyficzny dla systemu operacyjnego.
Jeśli platforma docelowa oznacza obsługę starszych struktur docelowych, są emitowane symbole preprocesora dla tych starszych struktur. Na przykład net6.0
oznacza obsługę net5.0
i tak dalej w drodze powrotnej do .netcoreapp1.0
. Dlatego dla każdej z tych platform docelowych zostanie zdefiniowana struktura z minimalnym symbolem ograniczenia 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 wartość GenerateDocumentationFile na true
, nazwa pliku dokumentacji jest domyślnie nazwą zestawu, ale z rozszerzeniem pliku .xml . 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 wartość GenerateDocumentationFile na false
, kompilator nie generuje pliku dokumentacji. Jeśli określisz tę właściwość i pominięto właściwość GenerateDocumentationFile, kompilator generuje 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 znajdują się w plikach zasobów. Na przykład jeśli plik Form1.resx znajduje się w tym samym folderze co form1.cs i EmbeddedResourceUseDependentUponConvention
jest ustawiony na true
, wygenerowany plik resources przyjmuje nazwę z pierwszego typu zdefiniowanego w pliku Form1.cs. Jeśli na przykład MyNamespace.Form1
jest pierwszym typem zdefiniowanym w pliku Form1.cs, wygenerowana nazwa pliku to MyNamespace.Form1.resources.
Uwaga
Jeśli LogicalName
dla elementu określono EmbeddedResource
wartość , ManifestResourceName
lub DependentUpon
metadane, wygenerowana nazwa pliku manifestu dla tego pliku zasobu jest oparta na tych metadanych.
Domyślnie w nowym projekcie platformy .NET ta właściwość ma wartość true
. Jeśli dla false
elementu w pliku projektu określono EmbeddedResource
wartość , a dla elementu w pliku projektu nie LogicalName
określono wartości , ManifestResourceName
DependentUpon
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 Jak nazwano pliki manifestu zasobu.
<PropertyGroup>
<EmbeddedResourceUseDependentUponConvention>true</EmbeddedResourceUseDependentUponConvention>
</PropertyGroup>
EnablePreviewFeatures
Właściwość EnablePreviewFeatures
określa, czy projekt zależy od jakichkolwiek interfejsów API, czy 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 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 True
.
<PropertyGroup>
<EnablePreviewFeatures>True</EnablePreviewFeatures>
</PropertyGroup>
Gdy projekt zawiera tę właściwość ustawioną na True
, do pliku AssemblyInfo.cs zostanie dodany następujący atrybut poziomu zestawu:
[assembly: RequiresPreviewFeatures]
Analizator ostrzega, czy ten atrybut jest obecny na zależnościach dla projektów, w których EnablePreviewFeatures
nie ustawiono wartości True
.
Autorzy bibliotek, którzy zamierzają dostarczać zestawy wersji zapoznawczej, powinni ustawić tę właściwość na True
wartość . Jeśli zestaw musi być dostarczony z kombinacją interfejsów API w wersji zapoznawczej i bez wersji zapoznawczej, zobacz sekcję GenerateRequiresPreviewFeaturesAttribute poniżej.
EnableWindowsTargeting
EnableWindowsTargeting
Ustaw właściwość na wartość , aby true
tworzyć aplikacje systemu Windows (na przykład Windows Forms lub Windows Presentation Foundation) na platformie innej niż Windows. Jeśli nie ustawisz tej właściwości na true
, zostanie wyświetlone ostrzeżenie dotyczące kompilacji NETSDK1100. Ten błąd występuje, ponieważ pakiety docelowe i pakiety uruchomieniowe nie są automatycznie pobierane na platformach, które nie są obsługiwane. Ustawiając tę właściwość, te pakiety są pobierane podczas kierowania krzyżowego.
Uwaga
Ta właściwość jest obecnie zalecana, aby umożliwić programowanie na platformach innych niż Windows. Ale gdy aplikacja jest gotowa do wydania, powinna zostać utworzona w systemie Windows. Podczas kompilowania na platformie innej niż Windows dane wyjściowe mogą nie być takie same jak podczas kompilowania w systemie Windows. W szczególności plik wykonywalny nie jest oznaczony jako aplikacja systemu Windows (co oznacza, że zawsze uruchomi okno konsoli) i nie będzie mieć osadzonej ikony.
<PropertyGroup>
<EnableWindowsTargeting>true</EnableWindowsTargeting>
</PropertyGroup>
GenerateDocumentationFile
Właściwość GenerateDocumentationFile
określa, czy kompilator generuje plik dokumentacji XML dla biblioteki. Jeśli ustawisz tę właściwość na true
i nie określisz nazwy pliku za pomocą 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 kodu 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 został oznaczony atrybutem RequiresPreviewFeaturesAttribute , który wymagałby od użytkowników włączenia funkcji w wersji zapoznawczej, ustaw tę właściwość na False
.
<PropertyGroup>
<EnablePreviewFeatures>True</EnablePreviewFeatures>
<GenerateRequiresPreviewFeaturesAttribute>False</GenerateRequiresPreviewFeaturesAttribute>
</PropertyGroup>
Ważne
Jeśli ustawisz GenerateRequiresPreviewFeaturesAttribute
właściwość na False
wartość , musisz mieć pewność, że wszystkie publiczne interfejsy API, które opierają się na funkcjach w wersji zapoznawczej za pomocą polecenia RequiresPreviewFeaturesAttribute.
OptimizeImplicitlyTriggeredBuild
Aby przyspieszyć czas kompilacji, kompilacje, które są niejawnie wyzwalane przez analizę kodu pomijania przez program Visual Studio, 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 true
jest . Jeśli ustawiono TreatWarningsAsErrors
wartość true
, ale nadal chcesz, aby kompilacje wyzwalane niejawnie zostały zoptymalizowane, możesz ustawić wartość OptimizeImplicitlyTriggeredBuild
True
. Aby wyłączyć optymalizację kompilacji dla niejawnie wyzwalanych kompilacji, ustaw wartość OptimizeImplicitlyTriggeredBuild
False
.
<PropertyGroup>
<OptimizeImplicitlyTriggeredBuild>True</OptimizeImplicitlyTriggeredBuild>
</PropertyGroup>
Domyślne właściwości dołączania elementów
W tej sekcji opisano następujące właściwości programu MSBuild:
- DefaultItemExcludesInProjectFolder
- DefaultItemExcludes
- EnableDefaultCompileItems
- EnableDefaultEmbeddedResourceItems
- EnableDefaultItems
- EnableDefaultNoneItems
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 plików *.cs i innych plików rozszerzeń językowych.
<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
- AnalysisLevel<, kategoria>
- AnalysisMode
- Kategoria AnalysisMode<>
- CodeAnalysisTreatWarningsAsErrors
- EnableNETAnalyzers
- EnforceCodeStyleInBuild
- _SkipUpgradeNetAnalyzersNuGetWarning
AnalysisLevel
Właściwość AnalysisLevel
umożliwia określenie zestawu analizatorów kodu do uruchomienia zgodnie z wydaniem 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 platformę .NET 7, ale nie chcesz, aby domyślny zestaw reguł analizy kodu został zmieniony, ustaw wartość AnalysisLevel
6
.
<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 mają 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 ustawisz wartość AnalysisLevel
5-<mode>
lub 5.0-<mode>
, a następnie zainstalujesz zestaw .NET 6 SDK 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.
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. |
7.0 |
Używany jest zestaw reguł, które były dostępne dla wersji .NET 7, nawet jeśli są dostępne nowsze reguły. |
7.0-<mode> |
Używany jest zestaw reguł, które były dostępne dla wersji .NET 7, nawet jeśli są dostępne nowsze reguły. Wartość <mode> określa, które reguły są włączone. |
7 |
Używany jest zestaw reguł, które były dostępne dla wersji .NET 7, nawet jeśli są dostępne nowsze reguły. |
7-<mode> |
Używany jest zestaw reguł, które były dostępne dla wersji .NET 7, nawet jeśli są dostępne nowsze reguły. 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 programie .NET 5 i starszych wersjach 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
true
wartość , ta właściwość również wpływa na reguły stylu kodu (IDEXXXX). - Jeśli ustawisz wartość złożoną dla
AnalysisLevel
parametru , nie musisz określać elementu AnalysisMode. Jeśli jednak to zrobisz,AnalysisLevel
pierwszeństwo maAnalysisMode
wartość . - 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<Category>
Wprowadzona na platformie .NET 6 ta właściwość jest taka sama jak AnalysisLevel, z tą różnicą, że dotyczy tylko 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ły |
---|---|
<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 (IDEXXXX) |
<AnalysisLevelUsage> |
Reguły użycia |
AnalysisMode
Począwszy od platformy .NET 5, zestaw .NET SDK 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 nowszych wersjach. 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 niż Default tryb. Niektóre sugestie, które są zdecydowanie zalecane w przypadku wymuszania kompilacji, są włączone jako ostrzeżenia kompilacji. Aby sprawdzić, które reguły obejmują te reguły, sprawdź plik %ProgramFiles%/dotnet/sdk/[version]/Sdks/Microsoft.NET.Sdk/analyzers/build/config/analysislevel_[level]_minimum.editorconfig . |
Recommended |
Nie dotyczy | Tryb bardziej agresywny niż Minimum tryb, w którym więcej reguł jest włączanych jako ostrzeżenia kompilacji. Aby sprawdzić, które reguły obejmują, sprawdź plik %ProgramFiles%/dotnet/sdk/[version]/Sdks/Microsoft.NET.Sdk/analyzers/build/config/analysislevel_[level]_recommended.editorconfig . |
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
true
wartość , 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ństwoAnalysisMode
ma wartość . - Jeśli
AnalysisMode
ustawiono wartośćAllEnabledByDefault
iAnalysisLevel
jest ustawiona na5.0
5
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 false
wartość .
<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.404
do ) 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
- Niezmienna globalizacja
- PredefinedCulturesOnly
- RetainVMGarbageCollection
- ServerGarbageCollection
- ThreadPoolMaxThreads
- ThreadPoolMinThreads
- TieredCompilation
- TieredCompilationQuickJit
- TieredCompilationQuickJitForLoops
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 powiązane z odwołaniem
Następujące właściwości programu MSBuild zostały opisane w tej sekcji:
- AssetTargetFallback
- DisableImplicitFrameworkReferences
- DisableTransitiveFrameworkReferenceDownloads
- DisableTransitiveProjectReferences
- ManagePackageVersionsCentrally
- Właściwości związane z przywracaniem
- UseMauiEssentials
- ValidateExecutableReferencesMatchSelfContained
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 true
wartość , możesz dodać jawne odwołania tylko do potrzebnych struktur lub pakietów.
<PropertyGroup>
<DisableImplicitFrameworkReferences>true</DisableImplicitFrameworkReferences>
</PropertyGroup>
DisableTransitiveFrameworkReferenceDownloads
Ustaw właściwość , DisableTransitiveFrameworkReferenceDownloads
aby true
uniknąć pobierania dodatkowych pakietów środowiska uruchomieniowego i pakietów docelowych, do których nie odwołuje się bezpośrednio projekt.
<PropertyGroup>
<DisableTransitiveFrameworkReferenceDownloads>true</DisableTransitiveFrameworkReferenceDownloads>
</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 true
wartość , ma podobny wpływ na ustawienie PrivateAssets="All"
dla wszystkich zależności projektu zależnego.
Jeśli ustawisz tę właściwość na true
wartość , możesz dodać jawne odwołania tylko do potrzebnych projektów.
<PropertyGroup>
<DisableTransitiveProjectReferences>true</DisableTransitiveProjectReferences>
</PropertyGroup>
ManagePackageVersionsCentrally
Właściwość została wprowadzona ManagePackageVersionsCentrally
na platformie .NET 7. Ustawiając go true
w pliku Directory.Packages.props w katalogu głównym repozytorium, można zarządzać typowymi zależnościami w projektach z jednej lokalizacji. Dodaj wersje dla typowych zależności pakietów przy użyciu PackageVersion
elementów w pliku Directory.Packages.props . Następnie w pojedynczych plikach projektu można pominąć Version
atrybuty z dowolnych PackageReference
elementów odwołujących się do pakietów zarządzanych centralnie.
Przykładowy plik Directory.Packages.props :
<PropertyGroup>
<ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
</PropertyGroup>
...
<ItemGroup>
<PackageVersion Include="Microsoft.Extensions.Configuration" Version="7.0.0" />
</ItemGroup>
Pojedynczy plik projektu:
<ItemGroup>
<PackageReference Include="Microsoft.Extensions.Configuration" />
</ItemGroup>
Aby uzyskać więcej informacji, zobacz centralne zarządzanie pakietami (CPM).
Właściwości związane z przywracaniem
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>
UseMauiEssentials
UseMauiEssentials
Ustaw właściwość na , aby true
zadeklarować jawne odwołanie do projektu lub pakietu, który zależy od maUI Essentials. To ustawienie zapewnia, że projekt zostanie ściągnięty we właściwej znanej dokumentacji struktury dla programu MAUI Essentials. Jeśli projekt odwołuje się do projektu, który używa programu MAUI Essentials, ale nie ustawisz tej właściwości na true
wartość , może wystąpić ostrzeżenie kompilacji NETSDK1186
.
<PropertyGroup>
<UseMauiEssentials>true</UseMauiEssentials>
</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 platformy lub odwrotnie, generuje on błędy ODPOWIEDNIO NETSDK1150 i NETSDK1151. Aby uniknąć tych błędów, gdy odwołanie jest zamierzone, ustaw ValidateExecutableReferencesMatchSelfContained
właściwość na false
wartość .
<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.
Właściwości związane z uruchamianiem
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>
Właściwości związane z hostingem
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 EnableComHosting
true
wartość oznacza również, że parametr EnableDynamicLoading to true
.
<PropertyGroup>
<EnableComHosting>True</EnableComHosting>
</PropertyGroup>
Aby uzyskać więcej informacji, zobacz Uwidacznianie składników 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
LatestMinor
wartość . - 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:
Można użyć dowolnych atrybutów elementu standardowego, na przykład Include
i Update
, na tych elementach. Użyj Include
polecenia , aby dodać nowy element i użyć Update
go do zmodyfikowania istniejącego elementu. 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 znajomego.
<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 jest $(PublicKey)
dostępny, ten klucz jest używany. W przeciwnym razie do atrybutu nie jest dodawany ż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 o sposobie określania minimalnej wersji, maksymalnej wersji, zakresu lub dokładnego dopasowania, zobacz Zakresy wersji.
Fragment kodu pliku projektu w poniższym przykładzie odwołuje się do pakietu System.Runtime .
<ItemGroup>
<PackageReference Include="System.Runtime" Version="4.3.0" />
</ItemGroup>
Zasoby zależności można również kontrolować 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 Package references in project files (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 w tym samym celu w projektach Visual Basic. Ta właściwość jest dostępna od platformy .NET 6.
<ItemGroup>
<Using Include="My.Awesome.Namespace" />
</ItemGroup>
Można również użyć Using
elementu do zdefiniowania globalnych using <alias>
i using static <type>
dyrektyw.
<ItemGroup>
<Using Include="My.Awesome.Namespace" Alias="Awesome" />
</ItemGroup>
Na przykład:
<Using Include="Microsoft.AspNetCore.Http.Results" Alias="Results" />
Emitujeglobal using Results = global::Microsoft.AspNetCore.Http.Results;
<Using Include="Microsoft.AspNetCore.Http.Results" Static="True" />
Emitujeglobal using static global::Microsoft.AspNetCore.Http.Results;
Aby uzyskać więcej informacji, zobacz aliasowane using
dyrektywy i using static <type>
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
CopyToPublishDirectory
Metadane elementu MSBuild kontrolują, kiedy element jest kopiowany 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 miejsca kopiowania elementu do. Link
Określa również, jak elementy spoza drzewa projektu są wyświetlane w oknie Eksplorator rozwiązań programu Visual Studio.
Jeśli Link
nie określono elementu spoza stożka projektu, wartość domyślna %(LinkBase)\%(RecursiveDir)%(Filename)%(Extension)
to . 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 globu elementu Include
w Eksplorator rozwiązań.