Informazioni di riferimento su MSBuild per i progetti .NET SDK

  • Articolo

Questa pagina è un riferimento per le proprietà e gli elementi di MSBuild che è possibile usare per configurare i progetti .NET.

Nota

Questa pagina è in progress e non elenca tutte le proprietà di MSBuild utili per .NET SDK. Per un elenco delle proprietà comuni di MSBuild, vedere Proprietà comuni di MSBuild.

Proprietà di convalida dell'assembly

Queste proprietà ed elementi vengono passati all'attività ValidateAssemblies. Per altre informazioni sulla convalida degli assembly, vedere Convalida dell'assembly.

Le proprietà MSBuild seguenti sono documentate in questa sezione:

Nota

Queste proprietà non fanno (ancora) parte di .NET SDK. Per usarle, è anche necessario aggiungere un oggetto PackageReference a Microsoft.DotNet.ApiCompat.Task.

Inoltre, le proprietà seguenti documentate nelle Proprietà di convalida del pacchetto si applicano anche alla convalida dell'assembly:

ApiCompatStrictMode

Se impostata su true, la ApiCompatStrictMode proprietà specifica che i controlli di compatibilità dell'API devono essere eseguiti in modalità strict.

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

ApiCompatValidateAssemblies

La proprietà ApiCompatValidateAssemblies abilita una serie di convalide negli assembly specificati. Per altre informazioni, vedere Convalida dell'assembly.

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

Proprietà del framework

Le proprietà MSBuild seguenti sono documentate in questa sezione:

TargetFramework

La proprietà TargetFramework specifica la versione del framework di destinazione per l'app. Per un elenco di moniker del framework di destinazione validi, vedere Framework di destinazione nei progetti in stile SDK.

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

Per altre informazioni, vedere Framework di destinazione nei progetti in stile SDK.

TargetFrameworks

Usare la proprietà TargetFrameworks quando si vuole che l'app sia destinata a più piattaforme. Per un elenco di moniker del framework di destinazione validi, vedere Framework di destinazione nei progetti in stile SDK.

Nota

Questa proprietà viene ignorata se TargetFramework viene specificato (singolare).

<PropertyGroup>
  <TargetFrameworks>net8.0;net462</TargetFrameworks>
</PropertyGroup>

Per altre informazioni, vedere Framework di destinazione nei progetti in stile SDK.

NetStandardImplicitPackageVersion

Nota

Questa proprietà si applica solo ai progetti che usano netstandard1.x. Non si applica ai progetti che usano netstandard2.x.

Usare la proprietà NetStandardImplicitPackageVersion quando si vuole specificare una versione del framework inferiore alla versione del metapacchetto. Il file di progetto nell'esempio seguente è destinato a netstandard1.3 ma usa la versione 1.6.0 di NETStandard.Library.

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

Proprietà dell'attributo assembly

GenerateAssemblyInfo

La proprietà GenerateAssemblyInfo controlla la generazione dell'attributo AssemblyInfo per il progetto. Il valore predefinito è true. Usare false per disabilitare la generazione del file:

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

L'impostazione GeneratedAssemblyInfoFile controlla il nome del file generato.

Quando il valore GenerateAssemblyInfo è true, le proprietà del progetto correlate al pacchetto vengono trasformate in attributi di assembly.

Per altre informazioni sulla generazione di attributi di assembly tramite un file di progetto, vedere Impostare gli attributi dell'assembly in un file di progetto.

GeneratedAssemblyInfoFile

La proprietà GeneratedAssemblyInfoFile definisce il percorso relativo o assoluto del file di informazioni sull'assembly generato. Il valore predefinito è un file denominato [project-name]. Assemblyinfo. [cs|vb] nella directory $(IntermediateOutputPath) (in genere obj).

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

Proprietà pacchetto

Proprietà descrittive

È possibile specificare proprietà come PackageId, PackageVersion, PackageIcon, Title e Description per descrivere il pacchetto creato dal progetto. Per informazioni su queste e altre proprietà, vedere la destinazione del pacchetto.

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

PackRelease

La proprietà PackRelease è simile alla proprietà PublishRelease, ad eccezione del fatto che modifica il comportamento predefinito di dotnet pack. Questa proprietà è stata introdotta in .NET 7.

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

Nota

  • A partire da .NET 8 SDK, PackRelease per impostazione predefinita è true. Per altre informazioni, vedere il 'pacchetto dotnet' utilizza la configurazione Release.
  • Solo .NET 7 SDK: per usare PackRelease in un progetto che fa parte di una soluzione di Visual Studio, è necessario impostare la variabile di ambiente DOTNET_CLI_ENABLE_PACK_RELEASE_FOR_SOLUTIONS su true (o qualsiasi altro valore). Per le soluzioni con molti progetti, l'impostazione di questa variabile aumenta il tempo necessario per il pacchetto.

Proprietà di convalida dei pacchetti

Queste proprietà ed elementi vengono passati all'attività ValidatePackage. Per altre informazioni sulla convalida dei pacchetti, vedere Panoramica della convalida dei pacchetti.

Per le proprietà per l'attività ValidateAssemblies, vedere Proprietà di convalida dell'assembly.

Le proprietà e gli elementi di MSBuild seguenti sono documentati in questa sezione:

ApiCompatEnableRuleAttributesMustMatch

Se impostata su true, la proprietà ApiCompatEnableRuleAttributesMustMatch abilita la regola di convalida che controlla se gli attributi corrispondono. Il valore predefinito è false.

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

ApiCompatEnableRuleCannotChangeParameterName

Se impostata su true, la proprietà ApiCompatEnableRuleCannotChangeParameterName abilita la regola di convalida che controlla se i nomi dei parametri sono stati modificati nei metodi pubblici. Il valore predefinito è false.

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

ApiCompatExcludeAttributesFile

L'elemento ApiCompatExcludeAttributesFile specifica il percorso di un file che contiene attributi da escludere in formato DocId.

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

ApiCompatGenerateSuppressionFile

La proprietà ApiCompatGenerateSuppressionFile specifica se generare un file di eliminazione della compatibilità.

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

ApiCompatPermitUnnecessarySuppressions

La proprietà ApiCompatPermitUnnecessarySuppressions specifica se consentire eliminazioni non necessarie nel file di eliminazione.

Il valore predefinito è false.

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

ApiCompatPreserveUnnecessarySuppressions

La proprietà ApiCompatPreserveUnnecessarySuppressions specifica se mantenere eliminazioni non necessarie durante la rigenerazione del file di eliminazione. Quando un file di eliminazione esistente viene rigenerato, il relativo contenuto viene letto, deserializzato in un set di eliminazioni e quindi archiviato in un elenco. Alcune delle eliminazioni potrebbero non essere più necessarie se l'incompatibilità è stata risolta. Quando le eliminazioni vengono serializzate su disco, è possibile scegliere di mantenere tutte le espressioni esistenti (deserializzate) impostando questa proprietà su true.

Il valore predefinito è false.

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

ApiCompatRespectInternals

La proprietà ApiCompatRespectInternals specifica se è necessario verificare la compatibilità delle API internal oltre alle API public.

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

ApiCompatSuppressionFile

L'elemento ApiCompatSuppressionFile specifica il percorso di uno o più file di eliminazione da cui leggere. Se non specificato, il file di eliminazione <project-directory>/CompatibilitySuppressions.xml viene letto (se esistente).

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

ApiCompatSuppressionOutputFile

La proprietà ApiCompatSuppressionOutputFile specifica il percorso di un file di eliminazione in cui scrivere quando <ApiCompatGenerateSuppressionFile> è true. Se non specificato, viene utilizzato il primo elemento ApiCompatSuppressionFile.

EnablePackageValidation

La proprietà EnablePackageValidation abilita una serie di convalide nel pacchetto dopo l'attività Pack. Per altre informazioni, vedere Convalida del pacchetto.

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

EnableStrictModeForBaselineValidation

Se impostata su true, la proprietà EnableStrictModeForBaselineValidation abilita modalità strict per i controlli della baseline del pacchetto. Il valore predefinito è false.

EnableStrictModeForCompatibleFrameworksInPackage

Se impostata su true, la proprietà abilita EnableStrictModeForCompatibleFrameworksInPackage la modalità strict per gli assembly compatibili in base al framework di destinazione. Il valore predefinito è false.

EnableStrictModeForCompatibleTfms

Se impostata su true, la proprietà EnableStrictModeForCompatibleTfms abilita la modalità strict per gli assembly di contratto e implementazione per tutti i framework di destinazione compatibili. Il valore predefinito è true.

NoWarn

La proprietà NoWarn specifica gli ID di diagnostica da eliminare.

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

PackageValidationBaselineFrameworkToIgnore

L'elemento PackageValidationBaselineFrameworkToIgnore specifica un framework di destinazione da ignorare dal pacchetto di base. La stringa del framework deve corrispondere esattamente al nome della cartella nel pacchetto di base.

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

PackageValidationBaselineName

La proprietà PackageValidationBaselineName specifica il nome del pacchetto di base per convalidare il pacchetto corrente. Se non specificato, viene utilizzato il valore PackageId.

PackageValidationBaselineVersion

La proprietà PackageValidationBaselineVersion specifica la versione del pacchetto di base per convalidare il pacchetto corrente.

PackageValidationReferencePath

L'elemento PackageValidationReferencePath specifica il percorso della directory in cui è possibile trovare l'assembly di riferimento per TFM.

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

RoslynAssembliesPath

La proprietà RoslynAssembliesPath specifica il percorso della directory contenente gli assembly Microsoft.CodeAnalysis che si desidera utilizzare. È necessario impostare questa proprietà solo se si vuole eseguire il test con un compilatore più recente rispetto a quello presente nell'SDK.

Le proprietà MSBuild seguenti sono documentate in questa sezione:

AppendTargetFrameworkToOutputPath

La proprietà AppendTargetFrameworkToOutputPath controlla se il moniker del framework di destinazione (TFM) viene aggiunto al percorso di output (definito da OutputPath). .NET SDK aggiunge automaticamente il framework di destinazione e, se presente, l'identificatore di runtime al percorso di output. L'impostazione AppendTargetFrameworkToOutputPath per false impedire l'accodamento del TFM al percorso di output. Tuttavia, senza TFM nel percorso di output, più artefatti della compilazione possono sovrascriversi tra loro.

Ad esempio, per un'app .NET 5, il percorso di output passa da bin\Debug\net5.0 a bin\Debug con l'impostazione seguente:

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

AppendRuntimeIdentifierToOutputPath

La proprietà AppendRuntimeIdentifierToOutputPath controlla se l’identificatore di runtime (RID) viene aggiunto al percorso di output. .NET SDK aggiunge automaticamente il framework di destinazione e, se presente, l'identificatore di runtime al percorso di output. L'impostazione di AppendRuntimeIdentifierToOutputPath su false impedisce l'accodamento del RID al percorso di output.

Ad esempio, per un'app .NET 5 e un RID di win-x64, l'impostazione seguente modifica il percorso di output da bin\Debug\net5.0\win-x64 a bin\Debug\net5.0:

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

CopyLocalLockFileAssemblies

La proprietà CopyLocalLockFileAssemblies è utile per i progetti di plug-in con dipendenze da altre librerie. Se si imposta questa proprietà su true, tutte le dipendenze del pacchetto NuGet vengono copiate nella directory di output. Ciò significa che è possibile usare l'output di dotnet build per eseguire il plug-in su qualsiasi computer.

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

Suggerimento

In alternativa, è possibile usare dotnet publish per pubblicare la libreria di classi. Per altre informazioni, vedere dotnet publish.

ErrorOnDuplicatePublishOutputFiles

La proprietà ErrorOnDuplicatePublishOutputFiles si riferisce al fatto che l'SDK generi un errore NETSDK1148 quando MSBuild rileva i file duplicati nell'output di pubblicazione, ma non è in grado di determinare quali file rimuovere. Impostare la proprietà ErrorOnDuplicatePublishOutputFiles su false se non si desidera che venga generato l'errore.

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

Questa proprietà è stata introdotta in .NET 6.

GenerateRuntimeConfigDevFile

A partire da .NET 6 SDK, il file [Appname].runtimesettings.dev.json non viene più generato per impostazione predefinita in fase di compilazione. Se si desidera che questo file venga comunque generato, impostare la proprietà GenerateRuntimeConfigDevFile su true.

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

GenerateRuntimeConfigurationFiles

La proprietà GenerateRuntimeConfigurationFiles controlla se le opzioni di configurazione del runtime vengono copiate dal file di runtimeconfig.template.json al file [appname].runtimeconfig.json. Per le app che richiedono un file di runtimeconfig.json, ovvero quelle il cui OutputType è Exe, per impostazione predefinita questa proprietà è true.

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

GenerateSatelliteAssembliesForCore

La proprietà GenerateSatelliteAssembliesForCore controlla se gli assembly satellite vengono generati usando csc.exe o Al.exe (Linker Assembly) nei progetti .NET Framework. (I progetti .NET Core e .NET 5+ usano sempre csc.exe per generare assembly satellite.) Per i progetti .NET Framework, gli assembly satellite vengono creati da al.exe, per impostazione predefinita. Impostando la proprietà GenerateSatelliteAssembliesForCore su true, gli assembly satellite vengono creati da csc.exe. L'uso di csc.exe può essere vantaggioso nelle situazioni seguenti:

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

IsPublishable

La proprietà IsPublishable consente l'esecuzione della destinazione Publish. Questa proprietà influisce solo sui processi che usano file .*proj e sulla destinazione Publish, ad esempio il comando dotnet publish. Non influisce sulla pubblicazione in Visual Studio, che usa la destinazione PublishOnly. Il valore predefinito è true.

Questa proprietà è utile se si esegue dotnet publish in un file di soluzione, in quanto consente la selezione automatica di progetti da pubblicare.

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

PreserveCompilationContext

La proprietà PreserveCompilationContext consente a un'applicazione compilata o pubblicata di compilare più codice in fase di esecuzione usando le stesse impostazioni usate in fase di compilazione. Gli assembly a cui viene fatto riferimento in fase di compilazione verranno copiati nella sottodirectory ref della directory di output. I nomi degli assembly di riferimento vengono archiviati nel file .deps.json dell'applicazione insieme alle opzioni passate al compilatore. È possibile recuperare queste informazioni usando le proprietà DependencyContext.CompileLibraries e DependencyContext.CompilationOptions.

Questa funzionalità viene usata internamente dalle pagine MVC ASP.NET Core e Razor per supportare la compilazione in fase di esecuzione dei file Razor.

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

PreserveCompilationReferences

La proprietà PreserveCompilationReferences è simile alla proprietà PreserveCompilationContext, ad eccezione del fatto che copia solo gli assembly di riferimento nella directory di pubblicazione e non il file .deps.json.

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

Per altre informazioni, vedere proprietà di Razor SDK.

ProduceReferenceAssemblyInOutDir

In .NET 5 e versioni precedenti gli assembly di riferimento vengono sempre scritti nella directory OutDir. In .NET 6 e versioni successive è possibile usare la proprietà ProduceReferenceAssemblyInOutDir per controllare se gli assembly di riferimento vengono scritti nella directory OutDir. Il valore predefinito è false e gli assembly di riferimento vengono scritti solo nella directory IntermediateOutputPath. Impostare il valore su true per scrivere assembly di riferimento nella directory OutDir.

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

Per altre informazioni, vedere Scrivere assembly di riferimento nell'output intermedio.

PublishDocumentationFile

Quando questa proprietà è true, il file di documentazione XML per il progetto, se ne viene generato uno, viene incluso nell'output di pubblicazione per il progetto. Questa proprietà viene impostata sul valore predefinito true.

Suggerimento

Impostare GenerateDocumentationFile su true per generare un file di documentazione XML in fase di compilazione.

PublishDocumentationFiles

Questa proprietà è un flag di abilitazione per diverse altre proprietà che controllano se diversi tipi di file di documentazione XML vengono copiati nella directory di pubblicazione per impostazione predefinita, ovvero PublishDocumentationFile e PublishReferencesDocumentationFiles. Se tali proprietà non sono impostate e questa proprietà viene impostata, tali proprietà verranno impostate per impostazione predefinita su true. Questa proprietà viene impostata sul valore predefinito true.

PublishReferencesDocumentationFiles

Quando questa proprietà è true, i file di documentazione XML per i riferimenti del progetto vengono copiati nella directory di pubblicazione, anziché semplicemente asset di runtime come i file DLL. Questa proprietà viene impostata sul valore predefinito true.

PublishRelease

La proprietà PublishRelease informa dotnet publish di usare la configurazione Release per impostazione predefinita anziché la configurazione Debug. Questa proprietà è stata introdotta in .NET 7.

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

Nota

  • A partire da .NET 8 SDK, PublishRelease per impostazione predefinita assume il valore true per i progetti destinati a .NET 8 o versione successiva. Per altre informazioni, vedere 'dotnet publish' usa la configurazione della release.
  • Questa proprietà non influisce sul comportamento di dotnet build /t:Publish e modifica la configurazione solo durante la pubblicazione tramite l'interfaccia della riga di comando di .NET.
  • Solo .NET 7 SDK: per usare PublishRelease in un progetto che fa parte di una soluzione di Visual Studio, è necessario impostare la variabile di ambiente DOTNET_CLI_ENABLE_PUBLISH_RELEASE_FOR_SOLUTIONS su true (o qualsiasi altro valore). Quando si pubblica una soluzione con questa variabile abilitata, il valore PublishRelease del progetto eseguibile ha la precedenza e passa la nuova configurazione predefinita a qualsiasi altro progetto nella soluzione. Se una soluzione contiene più progetti eseguibili o di primo livello con valori diversi di PublishRelease, la soluzione non verrà pubblicata correttamente. Per le soluzioni con molti progetti, l'uso di questa impostazione aumenta il tempo necessario per la pubblicazione.

PublishSelfContained

La proprietà PublishSelfContained informa dotnet publish di pubblicare un'app come app autonoma. Questa proprietà è utile quando non è possibile usare l'argomento --self-contained per il comando dotnet publish, ad esempio quando si pubblica a livello di soluzione. In tal caso, è possibile aggiungere la proprietà PublishSelfContained MSBuild a un progetto o al file directory.Build.Props.

Questa proprietà è stata introdotta in .NET 7. È simile alla proprietà SelfContained, ad eccezione del fatto che è specifico del verbo publish. È consigliabile usare PublishSelfContained anziché SelfContained.

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

RollForward

La proprietà RollForward controlla il modo in cui l'applicazione sceglie un runtime quando sono disponibili più versioni di runtime. Questo valore viene restituito a .runtimeconfig.json come l’impostazione rollForward.

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

Impostare RollForward su uno dei valori seguenti:

Valore Descrizione
Minor Impostazione predefinita se non specificato.
Esegue il roll forward alla versione secondaria successiva minima, se la versione secondaria richiesta non esiste. Se la versione secondaria richiesta è presente, viene usato il criterio LatestPatch.
Major Esegue il roll forward alla versione principale successiva disponibile e alla versione secondaria minima, se la versione principale richiesta non esiste. Se la versione principale richiesta è presente, viene usato il criterio Minor.
LatestPatch Esegue il roll forward alla versione di patch più recente. Questo valore disabilita il roll forward della versione secondaria.
LatestMinor Esegue il roll forward alla versione secondaria più recente, anche se la versione secondaria richiesta è presente.
LatestMajor Esegue il roll forward alla versione principale e secondaria più recente, anche se la versione principale richiesta è presente.
Disable Non eseguire il roll forward, associa solo alla versione specificata. Non è consigliato usare questo criterio per scopi generali poiché disabilita la possibilità di eseguire il roll forward alle patch più recenti. Questo valore è consigliato solo a scopo di test.

Per altre informazioni, vedere Comportamento di roll forward del controllo.

RuntimeFrameworkVersion

La proprietà RuntimeFrameworkVersion specifica la versione del runtime da utilizzare durante la pubblicazione. Specificare una versione di runtime:

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

Quando si pubblica un'applicazione dipendente dal framework, questo valore specifica la versione minima richiesta. Quando si pubblica un'applicazione autonoma, questo valore specifica la versione esatta richiesta.

RuntimeIdentifier

La proprietà RuntimeIdentifier consente di specificare un singolo identificatore di runtime (RID) per il progetto. Il RID consente di pubblicare una distribuzione autonoma.

<PropertyGroup>
  <RuntimeIdentifier>linux-x64</RuntimeIdentifier>
</PropertyGroup>

Identificatori di runtime

La proprietà RuntimeIdentifiers consente di specificare un elenco delimitato da punto e virgola di identificatori di runtime (RID) per il progetto. Utilizzare questa proprietà se è necessario pubblicare per più runtime. RuntimeIdentifiers viene usato in fase di ripristino per assicurarsi che gli asset corretti siano presenti nel grafico.

Suggerimento

RuntimeIdentifier (singolare) può fornire compilazioni più veloci quando è necessario un solo runtime.

<PropertyGroup>
  <RuntimeIdentifiers>win-x64;osx-x64;linux-x64</RuntimeIdentifiers>
</PropertyGroup>

SatelliteResourceLanguages

La proprietà SatelliteResourceLanguages consente di specificare per quali lingue si desidera mantenere gli assembly di risorse satellite durante la compilazione e la pubblicazione. Molti pacchetti NuGet includono assembly satellite delle risorse localizzati nel pacchetto principale. Per i progetti che fanno riferimento a questi pacchetti NuGet che non richiedono risorse localizzate, gli assembly localizzati possono inutilmente gonfiare le dimensioni di compilazione e pubblicazione dell'output. Aggiungendo la proprietà SatelliteResourceLanguages al file di progetto, solo gli assembly localizzati per le lingue specificate verranno inclusi nell'output di compilazione e pubblicazione. Nel file di progetto seguente, ad esempio, verranno conservati solo gli assembly satellite delle risorse in lingua inglese (Stati Uniti) e tedesco (Germania).

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

Nota

  • È necessario specificare questa proprietà nel progetto che fa riferimento al pacchetto NuGet con assembly satellite delle risorse localizzati.

  • Per specificare più lingue come argomento per dotnet publish, è necessario aggiungere tre coppie di virgolette intorno agli identificatori di lingua. Ad esempio:

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

SelfContained

La proprietà SelfContained informa dotnet build e dotnet publish di compilare o pubblicare un'app come app autonoma. Questa proprietà è utile quando non è possibile usare l'argomento --self-contained con il comando dotnet, ad esempio quando si pubblica a livello di soluzione. In tal caso, è possibile aggiungere la proprietà SelfContained MSBuild a un progetto o al Directory.Build.Props.

Questa proprietà è simile alla proprietà PublishSelfContained. È consigliabile usare PublishSelfContained anziché SelfContained quando possibile.

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

UseAppHost

La proprietà UseAppHost controlla se viene creato o meno un eseguibile nativo per una distribuzione. Per le distribuzioni autonome è necessario un eseguibile nativo. Per impostazione predefinita, viene creato un eseguibile dipendente dal framework. Impostare la proprietà UseAppHost su false per disabilitare la generazione dell’eseguibile.

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

Per altre informazioni sulla distribuzione, vedere Distribuzione di applicazioni .NET.

Numerose proprietà di MSBuild sono disponibili per ottimizzare il taglio, ovvero una funzionalità che elimina il codice inutilizzato dalle distribuzioni autonome. Queste opzioni sono descritte in dettaglio in opzioni taglio. Nella tabella seguente viene fornito un riferimento rapido.

Proprietà Valori Descrizione
PublishTrimmed true oppure false Controlla se il taglio è abilitato durante la pubblicazione.
TrimMode full oppure partial Il valore predefinito è full. Controlla la granularità di taglio.
SuppressTrimAnalysisWarnings true oppure false Controlla se vengono generati avvisi di analisi di taglio.
EnableTrimAnalyzer true oppure false Controlla se viene generato un subset di avvisi di analisi di taglio. È possibile abilitare l'analisi anche se PublishTrimmed è impostato su false.
ILLinkTreatWarningsAsErrors true oppure false Controlla se gli avvisi di taglio vengono considerati come errori. Ad esempio, è possibile impostare questa proprietà su false quando TreatWarningsAsErrors è impostato su true.
TrimmerSingleWarn true oppure false Controlla se viene visualizzato un singolo avviso per assembly o tutti gli avvisi.
TrimmerRemoveSymbols true oppure false Controlla se tutti i simboli vengono rimossi da un'applicazione eliminata.

Le proprietà MSBuild seguenti sono documentate in questa sezione:

Le opzioni del compilatore C#, ad esempio LangVersion e Nullable, possono essere specificate anche come proprietà MSBuild nel file di progetto. Per altre informazioni, vedere Opzioni del compilatore C#.

ContinuousIntegrationBuild

La proprietà ContinuousIntegrationBuild indica se una compilazione è in esecuzione in un server di integrazione continua (CI). Se impostata su true, questa proprietà abilita le impostazioni che si applicano solo alle build ufficiali anziché alle build locali in un computer per sviluppatori. Ad esempio, i percorsi di file archiviati vengono normalizzati per le build ufficiali. In un computer di sviluppo locale, tuttavia, il debugger non è in grado di trovare i file di origine locali se i percorsi dei file sono normalizzati.

Nota

Attualmente, l'impostazione di questa proprietà su true funziona solo se si aggiunge un riferimento specifico sourceLink del pacchetto del provider o un elemento <SourceRoot Include="$(MyDirectory)" />. Per altre informazioni, vedere dotnet/roslyn issue 55860.

È possibile usare la variabile del sistema CI per impostare in modo condizionale la proprietà ContinuousIntegrationBuild. Ad esempio, il nome della variabile per Azure Pipelines è TF_BUILD:

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

Per GitHub Actions, il nome della variabile è GITHUB_ACTIONS:

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

CopyDebugSymbolFilesFromPackages

Quando questa proprietà è impostata su true, tutti i file di simboli (noti anche come file PDB) dagli elementi PackageReference del progetto vengono copiati nell'output di compilazione. Questi file possono fornire analisi dello stack più informative per le eccezioni e rendere più facili da riconoscere i dump e le tracce di memoria dell'applicazione in esecuzione. Tuttavia, l'inclusione di questi file comporta un aumento delle dimensioni del pacchetto di distribuzione.

Questa proprietà è stata introdotta in .NET SDK 7.0.100, anche se per impostazione predefinita non è specificata.

CopyDocumentationFilesFromPackages

Quando questa proprietà è impostata su true, tutti i file di documentazione XML generati dagli elementi PackageReference del progetto vengono copiati nell'output di compilazione. Si noti che l'abilitazione di questa funzionalità comporterà un aumento delle dimensioni del pacchetto di distribuzione.

Questa proprietà è stata introdotta in .NET SDK 7.0.100, anche se per impostazione predefinita non è specificata.

DisableImplicitFrameworkDefines

La proprietà DisableImplicitFrameworkDefines controlla se l'SDK genera o meno simboli del preprocessore per il framework di destinazione e la piattaforma per il progetto .NET. Quando questa proprietà è impostata su false o è annullata (ovvero il valore predefinito) i simboli del preprocessore vengono generati per:

  • Framework senza versione (NETFRAMEWORK, NETSTANDARD, NET)
  • Framework con versione (NET48, NETSTANDARD2_0, NET6_0)
  • Framework con limite di versione minima (NET48_OR_GREATER, NETSTANDARD2_0_OR_GREATER, NET6_0_OR_GREATER)

Per altre informazioni sui moniker del framework di destinazione e su questi simboli del preprocessore implicito, vedere Framework di destinazione.

Inoltre, se si specifica un framework di destinazione specifico del sistema operativo nel progetto (ad esempio net6.0-android), vengono generati i simboli del preprocessore seguenti:

  • Piattaforma senza versione (ANDROID, IOS, WINDOWS)
  • Piattaforma con versione (IOS15_1)
  • Piattaforma con limite minimo di versione (IOS15_1_OR_GREATER)

Per altre informazioni sui moniker del framework di destinazione specifici del sistema operativo, vedere TFM specifici del sistema operativo.

Infine, se il framework di destinazione implica il supporto per i framework di destinazione meno recenti, vengono generati simboli del preprocessore per tali framework meno recenti. Ad esempio, net6.0implica il supporto per net5.0 e così via fino al ritorno a .netcoreapp1.0. Pertanto, per ognuno di questi framework di destinazione, verrà definito il simbolo di framework con limite di versione minima.

DocumentationFile

La proprietà DocumentationFile consente di specificare un nome file per il file XML che contiene la documentazione per la libreria. Affinché IntelliSense funzioni correttamente con la documentazione, il nome del file deve essere uguale al nome dell'assembly e deve trovarsi nella stessa directory dell'assembly. Se non si specifica questa proprietà ma si imposta GenerateDocumentationFile su true, il nome del file di documentazione viene impostato per impostazione predefinita sul nome dell'assembly, ma con un'estensione di file .xml. Per questo motivo, spesso è più facile omettere questa proprietà e usare la proprietà GenerateDocumentationFile.

Se si specifica questa proprietà ma si imposta GenerateDocumentationFile su false, il compilatore non genera un file di documentazione. Se si specifica questa proprietà e si omette la proprietà GenerateDocumentationFile, il compilatore genera un file di documentazione.

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

EmbeddedResourceUseDependentUponConvention

La proprietà EmbeddedResourceUseDependentUponConvention definisce se i nomi di file manifesto della risorsa vengono generati da informazioni sul tipo nei file di origine che si trovano in condivisione con i file di risorse. Ad esempio, se Form1.resx si trova nella stessa cartella di Form1.cs e EmbeddedResourceUseDependentUponConvention è impostato su true, il file .resources generato prende il nome dal primo tipo definito in Form1.cs. Se MyNamespace.Form1 è il primo tipo definito in Form1.cs, il nome del file generato è MyNamespace.Form1.resources.

Nota

Se i metadati LogicalName, ManifestResourceName o DependentUpon vengono specificati per un elemento EmbeddedResource, il nome del file manifesto generato per tale file di risorse si basa invece su tali metadati.

Per impostazione predefinita, in un nuovo progetto .NET destinato a .NET Core 3.0 o versione successiva, questa proprietà è impostata su true. Se è impostato su false e non vengono specificati metadati LogicalName, ManifestResourceName o DependentUpon per l'elemento EmbeddedResource nel file di progetto, il nome del file manifesto della risorsa si basa sullo spazio dei nomi radice per il progetto e sul percorso del file relativo .resx. Per altre informazioni, vedere Come vengono denominati i file manifesto delle risorse.

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

EnablePreviewFeatures

La proprietà EnablePreviewFeatures definisce se il progetto dipende da qualsiasi API o assembly decorati con l'attributo RequiresPreviewFeaturesAttribute. Questo attributo viene usato per indicare che un'API o un assembly usa funzionalità considerate in anteprima per la versione dell'SDK in uso. Le funzionalità di anteprima non sono supportate e possono essere rimosse in una versione futura. Per abilitare l'uso delle funzionalità di anteprima, impostare la proprietà su True.

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

Quando un progetto contiene questa proprietà impostata su True, l'attributo a livello di assembly seguente viene aggiunto al file AssemblyInfo.cs:

[assembly: RequiresPreviewFeatures]

Un analizzatore avvisa se questo attributo è presente nelle dipendenze per i progetti in cui EnablePreviewFeatures non è impostato su True.

Gli autori di librerie che intendono spedire gli assembly di anteprima devono impostare questa proprietà su True. Se un assembly deve essere fornito con una combinazione di API di anteprima e non di anteprima, vedere la sezione GenerateRequiresPreviewFeaturesAttribute di seguito.

EnableWindowsTargeting

Impostare la proprietà EnableWindowsTargeting su true per compilare app di Windows (ad esempio, app Windows Form o Windows Presentation Foundation) in una piattaforma non Windows. Se questa proprietà non viene impostata su true, si otterrà un avviso di compilazione NETSDK1100. Questo errore si verifica perché la destinazione e i pacchetti runtime non vengono scaricati automaticamente sulle piattaforme non supportate. Impostando questa proprietà, tali pacchetti vengono scaricati quando si esegue il cross-targeting.

Nota

Questa proprietà è attualmente consigliata per consentire lo sviluppo su piattaforme non Windows. Tuttavia, quando l'applicazione è pronta per essere rilasciata, deve essere compilata su Windows. Quando si esegue la compilazione su una piattaforma non Windows, l'output potrebbe non essere uguale a quando si esegue la compilazione in Windows. In particolare, l'eseguibile non è contrassegnato come un'applicazione Windows (il che significa che avvierà sempre una finestra della console) e non avrà un'icona incorporata.

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

GenerateDocumentationFile

La proprietà GenerateDocumentationFile controlla se il compilatore genera un file di documentazione XML per la libreria. Se si imposta questa proprietà su true e non si specifica un nome file tramite la proprietà DocumentationFile, il file XML generato viene inserito nella stessa directory di output dell'assembly e ha lo stesso nome file (ma con un'estensione .xml).

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

Per altre informazioni sulla generazione di documentazione dai commenti di codice, vedere commenti della documentazione XML (C#), Documentare il codice con XML (Visual Basic) o Documentare il codice con XML (F#).

GenerateRequiresPreviewFeaturesAttribute

La proprietà GenerateRequiresPreviewFeaturesAttribute è strettamente correlata alla proprietà EnablePreviewFeatures. Se la libreria usa funzionalità di anteprima, ma non si vuole che l'intero assembly venga contrassegnato con l'attributo RequiresPreviewFeaturesAttribute, che richiederebbe a tutti i consumer di abilitare le funzionalità di anteprima, impostare questa proprietà su False.

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

Importante

Se si imposta la proprietà GenerateRequiresPreviewFeaturesAttribute su False, è necessario essere certi di decorare tutte le API pubbliche che si basano sulle funzionalità di anteprima con RequiresPreviewFeaturesAttribute.

OptimizeImplicitlyTriggeredBuild

Per velocizzare il tempo di compilazione, le compilazioni attivate in modo implicito da Visual Studio ignorano l'analisi del codice, inclusa l'analisi che ammette i valori Null. Visual Studio attiva una compilazione implicita quando si eseguono test, ad esempio. Tuttavia, le compilazioni implicite vengono ottimizzate solo quando TreatWarningsAsErrors non è true. Se è stato TreatWarningsAsErrors impostato su true ma si desidera comunque ottimizzare le compilazioni attivate in modo implicito, è possibile impostare OptimizeImplicitlyTriggeredBuild su True. Per disattivare l'ottimizzazione della compilazione per le compilazioni attivate in modo implicito, impostare OptimizeImplicitlyTriggeredBuild su False.

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

DisableRuntimeMarshalling

La proprietà DisableRuntimeMarshalling consente di specificare che si vuole disabilitare il supporto del marshalling di runtime per il progetto. Se questa proprietà è impostata su true, l'oggetto DisableRuntimeMarshallingAttribute viene aggiunto all'assembly e qualsiasi interoperabilità P/Invokes o basata su delegato seguirà le regole relative al marshalling di runtime disabilitato.

<PropertyGroup>
    <DisableRuntimeMarshalling>True</DisableRuntimeMarshalling>
</PropertyGroup>

Proprietà di inclusione degli elementi predefinite

Le proprietà MSBuild seguenti sono documentate in questa sezione:

Per altre informazioni, vedere Inclusioni ed esclusioni predefinite.

DefaultItemExcludes

Utilizzare la proprietà DefaultItemExcludes per definire i criteri GLOB per file e cartelle che devono essere esclusi dall'inclusione, esclusione e rimozione di GLOB. Per impostazione predefinita, le cartelle ./bin e ./obj vengono escluse dai criteri GLOB.

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

DefaultItemExcludesInProjectFolder

Utilizzare la proprietà DefaultItemExcludesInProjectFolder per definire i criteri GLOB per file e cartelle nella cartella del progetto da escludere dall'inclusione, esclusione e rimozione di GLOB. Per impostazione predefinita, le cartelle che iniziano con un punto (.), ad esempio .git e .vs, vengono escluse dai criteri GLOB.

Questa proprietà è molto simile alla proprietà DefaultItemExcludes, ad eccezione del fatto che considera solo i file e le cartelle nella cartella del progetto. Quando un criterio GLOB corrisponde involontariamente agli elementi all'esterno della cartella del progetto con un percorso relativo, utilizzare la proprietà DefaultItemExcludesInProjectFolder anziché la proprietà DefaultItemExcludes.

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

EnableDefaultItems

La proprietà EnableDefaultItems controlla se gli elementi di compilazione, gli elementi delle risorse incorporati e gli elementi None vengono inclusi in modo implicito nel progetto. Il valore predefinito è true. Impostare la proprietà EnableDefaultItems su false per disabilitare tutta l'inclusione implicita dei file.

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

EnableDefaultCompileItems

La proprietà EnableDefaultCompileItems controlla se gli elementi di compilazione vengono inclusi in modo implicito nel progetto. Il valore predefinito è true. Impostare la proprietà EnableDefaultCompileItems su false per disabilitare l'inclusione implicita di *.cs e altri file di estensione del linguaggio.

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

EnableDefaultEmbeddedResourceItems

La proprietà EnableDefaultEmbeddedResourceItems controlla se gli elementi delle risorse incorporati vengono inclusi in modo implicito nel progetto. Il valore predefinito è true. Impostare la proprietà EnableDefaultEmbeddedResourceItems su false per disabilitare l'inclusione implicita dei file di risorse incorporati.

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

EnableDefaultNoneItems

La proprietà EnableDefaultNoneItems controlla se gli elementi None (file che non hanno alcun ruolo nel processo di compilazione) vengono inclusi in modo implicito nel progetto. Il valore predefinito è true. Impostare la proprietà EnableDefaultNoneItems su false per disabilitare l'inclusione implicita degli elementi None.

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

Proprietà di analisi del codice

Le proprietà MSBuild seguenti sono documentate in questa sezione:

AnalysisLevel

La proprietà AnalysisLevel consente di specificare un set di analizzatori di codice da eseguire in base a una versione .NET. Ogni versione di .NET, a partire da .NET 5, include un set di regole di analisi codice. Di questo set, le regole abilitate per impostazione predefinita per tale versione analizzeranno il codice. Ad esempio, se si esegue l'aggiornamento a .NET 8 ma non si vuole modificare il set predefinito di regole di analisi codice, impostare AnalysisLevel su 7.

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

Facoltativamente, a partire da .NET 6, è possibile specificare un valore composto per questa proprietà che specifica anche l'aggressività per abilitare le regole. I valori composti prendono il formato <version>-<mode>, dove il valore <mode> è uno dei valori AnalysisMode. Nell'esempio seguente viene usata la versione di anteprima degli analizzatori codice e viene abilitato il set consigliato di regole.

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

Valore predefinito:

  • Se il progetto è destinato a .NET 5 o versione successiva o se è stata aggiunta la proprietà AnalysisMode, il valore predefinito è latest.
  • In caso contrario, questa proprietà viene omessa a meno che non venga aggiunta in modo esplicito al file di progetto.

Nella tabella seguente vengono illustrati i valori che è possibile specificare.

Valore Significato
latest Vengono usati gli analizzatori di codice più recenti rilasciati. Si tratta dell'impostazione predefinita.
latest-<mode> Vengono usati gli analizzatori di codice più recenti rilasciati. Il valore <mode> determina quali regole sono abilitate.
preview Vengono usati gli analizzatori di codice più recenti, anche se sono in anteprima.
preview-<mode> Vengono usati gli analizzatori di codice più recenti, anche se sono in anteprima. Il valore <mode> determina quali regole sono abilitate.
8.0 Viene usato il set di regole disponibili per la versione .NET 8, anche se sono disponibili regole più recenti.
8.0-<mode> Viene usato il set di regole disponibili per la versione .NET 8, anche se sono disponibili regole più recenti. Il valore <mode> determina quali regole sono abilitate.
8 Viene usato il set di regole disponibili per la versione .NET 8, anche se sono disponibili regole più recenti.
8-<mode> Viene usato il set di regole disponibili per la versione .NET 8, anche se sono disponibili regole più recenti. Il valore <mode> determina quali regole sono abilitate.
7.0 Viene usato il set di regole disponibili per la versione .NET 7, anche se sono disponibili regole più recenti.
7.0-<mode> Viene usato il set di regole disponibili per la versione .NET 7, anche se sono disponibili regole più recenti. Il valore <mode> determina quali regole sono abilitate.
7 Viene usato il set di regole disponibili per la versione .NET 7, anche se sono disponibili regole più recenti.
7-<mode> Viene usato il set di regole disponibili per la versione .NET 7, anche se sono disponibili regole più recenti. Il valore <mode> determina quali regole sono abilitate.
6.0 Viene usato il set di regole disponibili per la versione .NET 6, anche se sono disponibili regole più recenti.
6.0-<mode> Viene usato il set di regole disponibili per la versione .NET 6, anche se sono disponibili regole più recenti. Il valore <mode> determina quali regole sono abilitate.
6 Viene usato il set di regole disponibili per la versione .NET 6, anche se sono disponibili regole più recenti.
6-<mode> Viene usato il set di regole disponibili per la versione .NET 6, anche se sono disponibili regole più recenti. Il valore <mode> determina quali regole sono abilitate.
5.0 Viene usato il set di regole disponibili per la versione .NET 5, anche se sono disponibili regole più recenti.
5.0-<mode> Viene usato il set di regole disponibili per la versione .NET 5, anche se sono disponibili regole più recenti. Il valore <mode> determina quali regole sono abilitate.
5 Viene usato il set di regole disponibili per la versione .NET 5, anche se sono disponibili regole più recenti.
5-<mode> Viene usato il set di regole disponibili per la versione .NET 5, anche se sono disponibili regole più recenti. Il valore <mode> determina quali regole sono abilitate.

Nota

  • A partire da .NET 6, se si imposta EnforceCodeStyleInBuild su true, questa proprietà influisce sulle regole di tipo codice (IDEXXXX), oltre alle regole di qualità del codice.
  • Se si imposta un valore composto per AnalysisLevel, non è necessario specificare un AnalysisMode. Tuttavia, se si esegue questa operazione, AnalysisLevel ha la precedenza su AnalysisMode.
  • Questa proprietà non ha alcun effetto sull'analisi del codice nei progetti che non fanno riferimento a un SDK di progetto, ad esempio progetti .NET Framework legacy che fanno riferimento al pacchetto NuGet Microsoft.CodeAnalysis.NetAnalyzers.

Categoria AnalysisLevel<>

Questa proprietà è identica a AnalysisLevel, ad eccezione del fatto che si applica solo a una categoria specifica di regole di analisi del codice. Questa proprietà consente di usare una versione diversa degli analizzatori di codice per una categoria specifica o di abilitare o disabilitare regole a un livello diverso rispetto alle altre categorie di regole. Se si omette questa proprietà per una determinata categoria di regole, per impostazione predefinita viene impostato il valore AnalysisLevel. I valori disponibili sono uguali a quelli di AnalysisLevel.

<PropertyGroup>
  <AnalysisLevelSecurity>preview</AnalysisLevelSecurity>
</PropertyGroup>

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

La tabella seguente elenca il nome della proprietà per ogni categoria di regole.

Nome della proprietà Categoria regola
<AnalysisLevelDesign> Regole di progettazione
<AnalysisLevelDocumentation> Regole della documentazione
<AnalysisLevelGlobalization> Regole di globalizzazione
<AnalysisLevelInteroperability> Regole di portabilità e interoperabilità
<AnalysisLevelMaintainability> Regole di manutenibilità
<AnalysisLevelNaming> Regole di denominazione
<AnalysisLevelPerformance> Regole di prestazioni
<AnalysisLevelSingleFile> Regole dell'applicazione a file singolo
<AnalysisLevelReliability> Regole di affidabilità
<AnalysisLevelSecurity> Regole di sicurezza
<AnalysisLevelStyle> Regole di tipo codice (IDEXXXX)
<AnalysisLevelUsage> Regole di utilizzo

AnalysisMode

.NET SDK viene fornito con tutte le regole di qualità del codice "CA". Per impostazione predefinita, solo alcune regole sono abilitate come avvisi di compilazione in ogni versione di .NET. La proprietà AnalysisMode consente di personalizzare il set di regole abilitate per impostazione predefinita. È possibile passare a una modalità di analisi più aggressiva in cui è possibile rifiutare esplicitamente le regole singolarmente o una modalità di analisi più conservativa in cui è possibile acconsentire esplicitamente a regole specifiche. Ad esempio, se si desidera abilitare tutte le regole come avvisi di compilazione, impostare il valore su All.

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

Nella tabella seguente vengono illustrati i valori delle opzioni disponibili. Sono elencati in ordine crescente del numero di regole abilitate.

Valore Descrizione
None Tutte le regole sono disabilitate. È possibile acconsentire in modo selettivo alle singole regole per abilitarle.
Default Modalità predefinita, in cui alcune regole sono abilitate come avvisi di compilazione, alcune regole vengono abilitate come suggerimenti dell'IDE di Visual Studio e il resto sono disabilitate.
Minimum Modalità più aggressiva rispetto alla modalità Default. Alcuni suggerimenti consigliati per l'imposizione della compilazione sono abilitati come avvisi di compilazione. Per visualizzare le regole incluse, esaminare il file %ProgramFiles%/dotnet/sdk/[version]/Sdks/Microsoft.NET.Sdk/analyzers/build/config/analysislevel_[level]_minimum.editorconfig.
Recommended Modalità più aggressiva rispetto alla modalità Minimum, in cui sono abilitate più regole come avvisi di compilazione. Per visualizzare le regole incluse, esaminare il file %ProgramFiles%/dotnet/sdk/[version]/Sdks/Microsoft.NET.Sdk/analyzers/build/config/analysislevel_[level]_recommended.editorconfig.
All Tutte le regole vengono abilitate come avvisi di compilazione*. È possibile rifiutare esplicitamente le singole regole per disabilitarle.

* Le regole seguenti non sono abilitate impostandoAnalysisMode su All o impostando AnalysisLevel su latest-all: CA1017, CA1045, CA1005, CA1014, CA1060, CA1021 e le regole dell'analizzatore delle metriche del codice (CA1501, CA1502, CA1505, CA1506 e CA1509). Queste regole legacy potrebbero essere deprecate in una versione futura. Tuttavia, è comunque possibile abilitarle singolarmente usando una voce dotnet_diagnostic.CAxxxx.severity = <severity>.

Nota

  • A partire da .NET 6, se si imposta EnforceCodeStyleInBuild su true, questa proprietà influisce sulle regole di tipo codice (IDEXXXX), oltre alle regole di qualità del codice.
  • Se si usa un valore composto per AnalysisLevel, ad esempio, <AnalysisLevel>8-recommended</AnalysisLevel>, è possibile omettere completamente questa proprietà. Tuttavia, se si specificano entrambe le proprietà, AnalysisLevel ha la precedenza su AnalysisMode.
  • Questa proprietà non ha alcun effetto sull'analisi del codice nei progetti che non fanno riferimento a un SDK di progetto, ad esempio progetti .NET Framework legacy che fanno riferimento al pacchetto NuGet Microsoft.CodeAnalysis.NetAnalyzers.

Categoria AnalysisMode<>

Questa proprietà è identica a AnalysisMode, ad eccezione del fatto che si applica solo a una categoria specifica di regole di analisi del codice. Questa proprietà consente di abilitare o disabilitare regole a un livello diverso rispetto alle altre categorie di regole. Se si omette questa proprietà per una determinata categoria di regole, per impostazione predefinita viene impostato il valore AnalysisMode. I valori disponibili sono uguali a quelli di AnalysisMode.

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

La tabella seguente elenca il nome della proprietà per ogni categoria di regole.

Nome della proprietà Categoria regola
<AnalysisModeDesign> Regole di progettazione
<AnalysisModeDocumentation> Regole della documentazione
<AnalysisModeGlobalization> Regole di globalizzazione
<AnalysisModeInteroperability> Regole di portabilità e interoperabilità
<AnalysisModeMaintainability> Regole di manutenibilità
<AnalysisModeNaming> Regole di denominazione
<AnalysisModePerformance> Regole di prestazioni
<AnalysisModeSingleFile> Regole dell'applicazione a file singolo
<AnalysisModeReliability> Regole di affidabilità
<AnalysisModeSecurity> Regole di sicurezza
<AnalysisModeStyle> Regole di tipo codice (IDEXXXX)
<AnalysisModeUsage> Regole di utilizzo

CodeAnalysisTreatWarningsAsErrors

La proprietà CodeAnalysisTreatWarningsAsErrors consente di configurare se gli avvisi di analisi della qualità del codice (CAxxxx) devono essere considerati come avvisi e interrompere la compilazione. Se si usa il flag -warnaserror quando si compilano i progetti, anche gli avvisi di analisi della qualità del codice .NET vengono considerati errori. Se non si desidera che gli avvisi di analisi della qualità del codice vengano considerati come errori, è possibile impostare la CodeAnalysisTreatWarningsAsErrors proprietà MSBuild su false nel file di progetto.

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

EnableNETAnalyzers

L'analisi della qualità del codice .NET è abilitata per impostazione predefinita per i progetti destinati a .NET 5 o versione successiva. Se si usa .NET 5+ SDK, è possibile abilitare l'analisi del codice .NET per i progetti tipo SDK destinati a versioni precedenti di .NET impostando la proprietà EnableNETAnalyzers su true. Per disabilitare l'analisi del codice in qualsiasi progetto, impostare questa proprietà su false.

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

Nota

Questa proprietà si applica in modo specifico agli analizzatori predefiniti in .NET 5+ SDK. Non deve essere usata quando si installa un pacchetto di analisi del codice NuGet.

EnforceCodeStyleInBuild

L'analisi dello stile di codice .NET è disabilitata, per impostazione predefinita, in compilazione per tutti i progetti .NET. È possibile abilitare l'analisi dello stile del codice per i progetti .NET impostando la proprietà EnforceCodeStyleInBuild su true.

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

Tutte le regole di stile del codice configurate come avvisi o errori verranno eseguite in caso di violazioni della compilazione e del report.

_SkipUpgradeNetAnalyzersNuGetWarning

La proprietà _SkipUpgradeNetAnalyzersNuGetWarning consente di configurare se viene visualizzato un avviso se si usano analizzatori di codice da un pacchetto NuGet non aggiornato rispetto agli analizzatori di codice nella versione più recente di .NET SDK. L'avviso è simile al seguente:

.NET SDK include analizzatori più recenti con la versione '6.0.0' rispetto alla versione '5.0.3' del pacchetto 'Microsoft.CodeAnalysis.NetAnalyzers'. Aggiornare o rimuovere questo riferimento al pacchetto.

Per rimuovere questo avviso e continuare a usare la versione degli analizzatori di codice nel pacchetto NuGet, impostare _SkipUpgradeNetAnalyzersNuGetWarning su true nel file di progetto.

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

Proprietà di configurazione di esecuzione

È possibile configurare alcuni comportamenti di runtime specificando le proprietà di MSBuild nel file di progetto dell'app. Per informazioni su altri modi per configurare il comportamento di runtime, vedere Impostazioni configurazione di esecuzione.

AutoreleasePoolSupport

La proprietà AutoreleasePoolSupport configura se ogni thread gestito riceve un NSAutoreleasePool implicito durante l'esecuzione in una piattaforma macOS supportata. Per altre informazioni, vedere AutoreleasePool per i thread gestiti.

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

ConcurrentGarbageCollection

La proprietà ConcurrentGarbageCollection consente di configurare se è abilitato Garbage Collection in background (simultaneo). Impostare il valore su false per disabilitare l'operazione di Garbage Collection in background. Per altre informazioni, vedere GC in background.

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

InvariantGlobalization

La proprietà InvariantGlobalization consente di configurare se l'app viene eseguita in modalità invariante di globalizzazione, il che significa che non ha accesso a dati specifici delle impostazioni cultura. Impostare il valore su true per l'esecuzione in modalità invariante di globalizzazione. Per altre informazioni, vedere Modalità invariante.

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

PredefinedCulturesOnly

In .NET 6 e versioni successive la proprietà PredefinedCulturesOnly configura se le app possono creare impostazioni cultura diverse dalle impostazioni cultura inglese non dipendenti da paese/area geografica quando la modalità invariante di globalizzazione è abilitata. Il valore predefinito è true. Impostare il valore su false per consentire la creazione di nuove impostazioni cultura in modalità invariante di globalizzazione.

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

Per altre informazioni, vedere Creazione delle impostazioni cultura e mapping dei casi in modalità invariante di globalizzazione.

RetainVMGarbageCollection

La proprietà RetainVMGarbageCollection configura il Garbage Collector per inserire segmenti di memoria eliminati in un elenco di standby per usarli o rilasciarli in futuro. L'impostazione del valore su true indica al Garbage Collector di inserire i segmenti in un elenco di standby. Per altre informazioni, vedere Conservare la macchina virtuale.

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

ServerGarbageCollection

La proprietà ServerGarbageCollection consente di configurare se l'applicazione usa Garbage Collection della workstation o Garbage Collection del server. Impostare il valore su true per usare l'operazione di Garbage Collection del server. Per altre informazioni, vedere Workstation vs. server.

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

ThreadPoolMaxThreads

La proprietà ThreadPoolMaxThreads configura il numero massimo di thread per il pool di thread di lavoro. Per altre informazioni, vedere Numero massimo di thread.

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

ThreadPoolMinThreads

La proprietà ThreadPoolMinThreads configura il numero minimo di thread per il pool di thread di lavoro. Per altre informazioni, vedere Thread minimi.

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

TieredCompilation

La proprietà TieredCompilation configura se il compilatore JIT (Just-In-Time) utilizza compilazione a livelli. Impostare il valore su false per disabilitare la compilazione a livelli. Per altre informazioni, vedere Compilazione a livelli.

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

TieredCompilationQuickJit

La proprietà TieredCompilationQuickJit consente di configurare se il compilatore JIT usa il quick JIT. Impostare il valore su false per disabilitare quick JIT. Per altre informazioni, vedere Quick JIT.

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

TieredCompilationQuickJitForLoops

La proprietà TieredCompilationQuickJitForLoops consente di configurare se il compilatore JIT usa il quick JIT nei metodi che contengono cicli. Impostare il valore su true per abilitare il quick JIT sui metodi che contengono cicli. Per altre informazioni, vedere Quick JIT for loops (JIT rapido per i cicli).

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

TieredPGO

La proprietà TieredPGO controlla se è abilitata la Profile Guided Optmization (PGO) dinamica o a livelli. Impostare il valore su true per abilitare laPGO a livelli. Per altre informazioni, vedere la Profile Guided Optmization.

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

UseWindowsThreadPool

La proprietà UseWindowsThreadPool configura se la gestione dei thread del pool di thread è delegata al pool di thread di Windows (solo Windows). Il valore predefinito è false, nel qual caso viene usato il pool di thread .NET. Per altre informazioni, vedere pool di thread di Windows.

<PropertyGroup>
  <UseWindowsThreadPool>true</UseWindowsThreadPool>
</PropertyGroup>

Le proprietà MSBuild seguenti sono documentate in questa sezione:

AssetTargetFallback

La proprietà AssetTargetFallback consente di specificare versioni del framework compatibili aggiuntive per i riferimenti al progetto e i pacchetti NuGet. Ad esempio, se si specifica una dipendenza del pacchetto usando PackageReference ma tale pacchetto non contiene asset compatibili con TargetFramework dei progetti, la proprietà AssetTargetFallback entra in gioco. La compatibilità del pacchetto a cui si fa riferimento viene ricontrollata usando ogni framework di destinazione specificato in AssetTargetFallback. Questa proprietà sostituisce la proprietà PackageTargetFallbackdeprecata.

È possibile impostare la proprietà AssetTargetFallback su una o più versioni del framework di destinazione.

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

DisableImplicitFrameworkReferences

La proprietà DisableImplicitFrameworkReferences controlla gli elementi FrameworkReference impliciti quando sono destinati a .NET Core 3.0 e versioni successive. Quando la destinazione è .NET Core 2.1 o .NET Standard 2.0 e versioni precedenti, controlla gli elementi PackageReference impliciti ai pacchetti in un metapacchetto. (Un metapacchetto è un pacchetto basato su framework costituito solo da dipendenze da altri pacchetti.) Questa proprietà controlla anche riferimenti impliciti, ad esempio System e System.Core quando la destinazione è .NET Framework.

Impostare questa proprietà su true per disabilitare gli elementi FrameworkReference impliciti o PackageReference. Se si imposta questa proprietà su true, è possibile aggiungere riferimenti espliciti solo ai framework o ai pacchetti necessari.

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

DisableTransitiveFrameworkReferenceDownloads

Impostare la proprietà DisableTransitiveFrameworkReferenceDownloads su true per evitare di scaricare pacchetti aggiuntivi di runtime e targeting a cui non fa riferimento direttamente il progetto.

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

DisableTransitiveProjectReferences

La proprietà DisableTransitiveProjectReferences controlla i riferimenti impliciti relativi al progetto. Impostare questa proprietà su true per disabilitare gli elementi ProjectReference impliciti. La disabilitazione dei riferimenti impliciti al progetto comporta un comportamento non transitivo simile al sistema di progetto legacy.

Quando questa proprietà è true, ha un effetto simile a quello dell'impostazione PrivateAssets="All" su tutte le dipendenze del progetto di dipendenza.

Se si imposta questa proprietà su true, è possibile aggiungere riferimenti espliciti solo ai progetti necessari.

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

ManagePackageVersionsCentrally

La proprietà ManagePackageVersionsCentrally è stata introdotta in .NET 7. Impostandola su true in un file Directory.Packages.props nella radice del repository, è possibile gestire le dipendenze comuni nei progetti da un'unica posizione. Aggiungere versioni per le dipendenze dei pacchetti comuni usando gli elementi PackageVersion nel file Directory.Packages.props. Quindi, nei singoli file di progetto, è possibile omettere gli attributi Version da tutti gli elementi PackageReference che fanno riferimento a pacchetti gestiti centralmente.

File di esempio Directory.Packages.props:

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

File di progetto singolo:

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

Per altre informazioni, vedere Central Package Management (CPM).

Il ripristino di un pacchetto a cui si fa riferimento installa tutte le relative dipendenze dirette e tutte le dipendenze di tali dipendenze. È possibile personalizzare il ripristino dei pacchetti specificando proprietà come RestorePackagesPath e RestoreIgnoreFailedSources. Per altre informazioni su queste e altre proprietà, vedere Destinazione di ripristino.

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

UseMauiEssentials

Impostare la proprietà UseMauiEssentials su true per dichiarare un riferimento esplicito a un progetto o a un pacchetto che dipende da MAUI Essentials. Questa impostazione garantisce che il progetto esegue il pulling del riferimento al framework noto corretto per MAUI Essentials. Se il progetto fa riferimento a un progetto che usa MAUI Essentials ma non si imposta questa proprietà su true, è possibile che venga visualizzato un avviso di compilazione NETSDK1186.

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

ValidateExecutableReferencesMatchSelfContained

La proprietà ValidateExecutableReferencesMatchSelfContained può essere utilizzata per disabilitare gli errori correlati ai riferimenti al progetto eseguibile. Se .NET rileva che un progetto eseguibile autonomo fa riferimento a un progetto eseguibile dipendente dal framework o viceversa, genera gli errori rispettivamente NETSDK1150 e NETSDK1151. Per evitare questi errori quando il riferimento è intenzionale, impostare la proprietà ValidateExecutableReferencesMatchSelfContained su false.

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

WindowsSdkPackageVersion

La proprietà WindowsSdkPackageVersion può essere usata per eseguire l'override della versione del pacchetto di destinazione Windows SDK. Questa proprietà è stata introdotta in .NET 5 e sostituisce l'uso dell'elemento FrameworkReference a questo scopo.

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

Nota

Non è consigliabile eseguire l'override della versione di Windows SDK, perché i pacchetti destinati a Windows SDK sono inclusi in .NET 5+ SDK. Al contrario, per fare riferimento al pacchetto Windows SDK più recente, aggiornare la versione di .NET SDK. Questa proprietà deve essere usata solo in rari casi, ad esempio l'uso di pacchetti di anteprima o la necessità di eseguire l'override della versione di C#/WinRT.

Per avviare un'app con il comando dotnet run vengono usate le proprietà seguenti:

RunArguments

La proprietà RunArguments definisce gli argomenti passati all'app quando viene eseguita.

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

Suggerimento

È possibile specificare argomenti aggiuntivi da passare all'app usando l'opzione -- per dotnet run.

RunWorkingDirectory

La proprietà RunWorkingDirectory definisce la directory di lavoro in cui avviare il processo dell'applicazione. Può essere un percorso assoluto o un percorso relativo alla directory del progetto. Se non si specifica una directory, OutDir viene usata come directory di lavoro.

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

Le proprietà MSBuild seguenti sono documentate in questa sezione:

EnableComHosting

La proprietà EnableComHosting indica che un assembly fornisce un server COM. L'impostazione di EnableComHosting su true implica anche che EnableDynamicLoading sia true.

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

Per altre informazioni, vedere Esporre componenti .NET a COM.

EnableDynamicLoading

La proprietà EnableDynamicLoading indica che un assembly è un componente caricato dinamicamente. Il componente può essere una libreria COM o una libreria non COM che può essere usata da un host nativo o usato come plug-in. L'impostazione di questa proprietà su true ha gli effetti seguenti:

  • Viene generato un file .runtimeconfig.json.
  • RollForward è impostato su LatestMinor.
  • I riferimenti NuGet vengono copiati in locale.
<PropertyGroup>
  <EnableDynamicLoading>true</EnableDynamicLoading>
</PropertyGroup>

Proprietà del file generato

Le proprietà seguenti riguardano il codice nei file generati:

DisableImplicitNamespaceImports

La proprietà DisableImplicitNamespaceImports può essere usata per disabilitare le importazioni implicite di spazi dei nomi nei progetti Visual Basic destinati a .NET 6 o versione successiva. Gli spazi dei nomi impliciti sono gli spazi dei nomi predefiniti importati a livello globale in un progetto Visual Basic. Impostare questa proprietà su true per disabilitare le importazioni implicite di spazi dei nomi.

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

ImplicitUsings

La proprietà ImplicitUsings può essere usata per abilitare e disabilitare direttive global using implicite nei progetti C# destinati a .NET 6 o versione successiva e C# 10 o versione successiva. Quando la funzionalità è abilitata, .NET SDK aggiunge direttive global using per un set di spazi dei nomi predefiniti in base al tipo di SDK di progetto. Impostare questa proprietà su true o enable per abilitare le direttive implicite global using. Per disabilitare le direttive implicite global using, rimuovere la proprietà o impostarla su false o disable.

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

Nota

I modelli per i nuovi progetti C# destinati a .NET 6 o versione successiva hanno ImplicitUsings impostato su enable per impostazione predefinita.

Per definire una direttiva global using esplicita, aggiungere un elemento Using.

Articoli

Gli elementi MSBuild sono input nel sistema di compilazione. Gli elementi vengono specificati in base al tipo, ovvero il nome dell'elemento. Ad esempio, Compile e Reference sono due tipi di elemento comuni. I tipi di elemento aggiuntivi seguenti sono resi disponibili da .NET SDK:

È possibile usare qualsiasi attributo di elemento standard, ad esempio, Include e Update, in questi elementi. Usare Include per aggiungere un nuovo elemento e usare Update per modificare un elemento esistente. Ad esempio, Update viene spesso usato per modificare un elemento aggiunto in modo implicito da .NET SDK.

AssemblyMetadata

L'elemento AssemblyMetadata specifica un attributo assembly AssemblyMetadataAttribute della coppia chiave-valore. I metadati Include diventano la chiave e i metadati Value diventano il valore.

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

InternalsVisibleTo

L'elemento InternalsVisibleTo genera un attributo assembly InternalsVisibleToAttribute per l'assembly Friend specificato.

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

Se l'assembly Friend è firmato, è possibile specificare dei metadati Key facoltativi per specificare la chiave pubblica completa. Se non si specificano i metadati Key ed è disponibile un $(PublicKey), viene usata tale chiave. In caso contrario, all'attributo non viene aggiunta alcuna chiave pubblica.

FrameworkReference

L'elemento FrameworkReference definisce un riferimento a un framework condiviso .NET.

L'attributo Include specifica l'ID framework.

Il frammento di file di progetto nell'esempio seguente fa riferimento al framework condiviso Microsoft.AspNetCore.App.

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

PackageReference

L'elemento PackageReference definisce un riferimento a un pacchetto NuGet.

L'attributo Include specifica l'ID del pacchetto. L'attributo Version specifica la versione o l'intervallo di versioni. Per informazioni su come specificare una versione minima, una versione massima, un intervallo o una corrispondenza esatta, vedere Intervalli di versioni.

Il frammento di file di progetto nell'esempio seguente fa riferimento al pacchetto System.Runtime.

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

È anche possibile controllare gli asset di dipendenza usando metadati come PrivateAssets.

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

Per altre informazioni, vedere i riferimenti ai pacchetti nei file di progetto.

TrimmerRootAssembly

L'elemento TrimmerRootAssembly consente di escludere un assembly dal taglio. Il taglio è il processo di rimozione di parti inutilizzate del runtime da un'applicazione in un pacchetto. In alcuni casi, il taglio potrebbe rimuovere erroneamente i riferimenti necessari.

L’XML seguente esclude l'assembly System.Security dal taglio.

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

Per altre informazioni, vedere Opzioni di taglio.

Con

L'elemento Using consente di includere a livello globale uno spazio dei nomi nel progetto C#, in modo che non sia necessario aggiungere una direttiva using per lo spazio dei nomi all'inizio dei file di origine. Questo elemento è simile all'elemento Import che può essere usato per lo stesso scopo nei progetti Visual Basic. Questa proprietà è disponibile a partire da .NET 6.

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

È anche possibile usare l'elemento Using per definire direttive using <alias> e using static <type> globali.

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

Ad esempio:

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

Per altre informazioni, vedere direttive using con alias e using static <type>direttive.

Metadati degli elementi

Oltre agli attributi dell'elemento MSBuild standard, i tag di metadati degli elementi seguenti vengono resi disponibili da .NET SDK:

CopyToPublishDirectory

I metadati CopyToPublishDirectory in un elemento MSBuild controllano quando l'elemento viene copiato nella directory di pubblicazione. I valori consentiti sono PreserveNewest, che copia l'elemento solo se è stato modificato, Always, che copia sempre l'elemento e Never, che non copia mai l'elemento. Dal punto di vista delle prestazioni, PreserveNewest è preferibile perché abilita una compilazione incrementale.

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

LinkBase

Per un elemento esterno alla directory del progetto e alle relative sottodirectory, la destinazione di pubblicazione usa i metadati del collegamento dell'elemento per determinare dove copiare l'elemento. Link determina anche la modalità di visualizzazione degli elementi all'esterno dell'albero del progetto nella finestra Esplora soluzioni di Visual Studio.

Se Link non viene specificato per un elemento esterno al cono del progetto, per impostazione predefinita è %(LinkBase)\%(RecursiveDir)%(Filename)%(Extension). LinkBase consente di specificare una cartella di base sensibile per gli elementi esterni al cono del progetto. La gerarchia di cartelle nella cartella di base viene mantenuta tramite RecursiveDir. Se LinkBase non viene specificato, viene omesso dal percorso Link.

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

L'immagine seguente mostra come viene visualizzato un file incluso tramite GLOB elemento Include precedente in Esplora soluzioni.

Solution Explorer showing item with LinkBase metadata.

Vedi anche