Opzioni del compilatore C# per le regole delle funzionalità del linguaggio

Le opzioni seguenti controllano il modo in cui il compilatore interpreta le funzionalità del linguaggio. La nuova sintassi di MSBuild viene visualizzata in grassetto. La sintassi di csc.exe precedente è mostrata in code style.

• CheckForOverflowUnderflow / -checked: generare controlli di overflow.
• AllowUnsafeBlocks: consenti / -unsafeunsafe il codice.
• DefineConstants / -define: definire i simboli di compilazione condizionale.
• LangVersion / -langversion: specificare la versione del linguaggio, ad esempio default (versione principale più recente) o latest (versione più recente, incluse le versioni secondarie).
• Nullable / -nullable: abilitare il contesto che ammette i valori Null o avvisi che ammettono i valori Null.

CheckForOverflowUnderflow

L'opzione CheckForOverflowUnderflow controlla il contesto di controllo dell'overflow predefinito che definisce il comportamento del programma in presenza di overflow aritmetici di integer.

<CheckForOverflowUnderflow>true</CheckForOverflowUnderflow>

Quando CheckForOverflowUnderflow è true, il contesto predefinito è un contesto controllato e il controllo dell'overflow è abilitato. Quando CheckForOverflowUnderflow è false, il contesto predefinito è un contesto deselezionato. Il valore predefinito per questa opzione è false, il che significa che il controllo dell'overflow è disabilitato.

È anche possibile controllare in modo esplicito il contesto di controllo dell'overflow per parti del codice usando le checked istruzioni e unchecked .

Per informazioni sul modo in cui il contesto di controllo dell'overflow influisce sulle operazioni e sulle operazioni che influisce, vedere l'articolo sulle checked istruzioni e unchecked.

AllowUnsafeBlocks

L'opzione del compilatore AllowUnsafeBlocks consente la compilazione del codice che usa la parola chiave unsafe. Il valore predefinito per questa opzione è false, ovvero il codice non gestito non è consentito.

<AllowUnsafeBlocks>true</AllowUnsafeBlocks>

Per altre informazioni sul codice unsafe, vedere Codice unsafe e puntatori.

Abilitare le regole di sicurezza della memoria aggiornate

Le regole di sicurezza della memoria aggiornate sono una funzionalità di anteprima in C# 15 e .NET 11. Usano due impostazioni indipendenti del compilatore:

• La versione del preview linguaggio consente il nuovo relax della sintassi e del puntatore.
• La updated-memory-safety-rules funzionalità del compilatore abilita le regole aggiornate, inclusi gli obblighi del chiamante non sicuro e fa in modo che il compilatore registri la scelta nell'assembly con l'attributo MemorySafetyRulesAttribute .

Una futura proprietà DELL'SDK stabile, MemorySafetyRules, è pianificata come terzo livello di attivazione per quando la funzionalità esce dall'anteprima (ad esempio, <MemorySafetyRules>2</MemorySafetyRules>), ma tale proprietà non è ancora implementata.

Per un progetto, usare entrambe le impostazioni:

<PropertyGroup>
  <LangVersion>preview</LangVersion>
  <Features>$(Features);updated-memory-safety-rules</Features>
</PropertyGroup>

Per un programma basato su file, aggiungere le direttive equivalenti:

#:property Features=$(Features);updated-memory-safety-rules
#:property LangVersion=preview

La proprietà AllowUnsafeBlocks è indipendente. Controlla se l'origine può usare la unsafe parola chiave . Un progetto può abilitare le regole aggiornate senza consentire codice non sicuro, nel qual caso riceve errori quando chiama api non sicure.

Se un assembly applica le regole aggiornate a un altro dipende da quale lato acconsente esplicitamente:

• Chiamante del modello aggiornato, chiamato al modello aggiornato: i marcatori del unsafe chiamato passano attraverso i metadati. Il chiamante esegue il wrapping di ogni chiamata a un membro non sicuro richiesto in un unsafe blocco.
• Chiamante del modello aggiornato, chiamato originale: una modalità di compatibilità considera qualsiasi membro chiamato con un tipo di puntatore nella firma come richiesto-non sicuro, quindi il sito di chiamata necessita di un blocco di inclusione unsafe . Questa modalità impedisce a un'API basata su puntatore di perdere automaticamente il unsafe requisito.
• Chiamante modello originale, chiamato modello aggiornato: le regole del puntatore originali sono ancora valide. Un membro non sicuro che non ha alcun tipo di puntatore nella firma diventa chiamabile dal codice sicuro, perché il chiamante del modello originale non riesce a leggere i nuovi marcatori.

DefineConstants

L'opzione DefineConstants definisce i simboli in tutti i file di codice sorgente del programma.

<DefineConstants>name;name2</DefineConstants>

Questa opzione specifica i nomi di uno o più simboli da definire. L'opzione DefineConstants ha lo stesso effetto dell'uso della direttiva #define per il preprocessore, ad eccezione del fatto che l'opzione del compilatore è valida per tutti i file nel progetto. Un simbolo resta definito in un file del codice sorgente finché una direttiva #undef nel file non rimuove la definizione. Quando si usa l'opzione -define, una direttiva #undef in un file non ha effetto in altri file del codice sorgente nel progetto. È possibile usare i simboli creati da questa opzione con #if, #else, #elif e #endif per la compilazione condizionale dei file del codice sorgente. Il compilatore C# stesso non definisce alcun simbolo o macro che è possibile usare nel codice sorgente. Tutte le definizioni dei simboli devono essere definite dall'utente.

LangVersion

La versione del linguaggio predefinita per il compilatore C# dipende dal framework di destinazione per l'applicazione e dalla versione dell'SDK o di Visual Studio installata. Queste regole sono definite nel controllo delle versioni del linguaggio C#.

L'opzione LangVersion fa sì che il compilatore accetti solo la sintassi inclusa nella specifica del linguaggio C# specificata, ad esempio:

<LangVersion>9.0</LangVersion>

Alcune funzionalità di anteprima richiedono un consenso esplicito separato oltre a <LangVersion>preview</LangVersion>. Ad esempio, le regole di sicurezza della memoria aggiornate di C# 15 usano la funzionalità del updated-memory-safety-rules compilatore. Per altre informazioni, vedere Abilitare le regole di sicurezza della memoria aggiornate.

I valori validi sono i seguenti:

Considerazioni

• Per assicurarsi che il progetto usi la versione del compilatore predefinita consigliata per il framework di destinazione, non usare l'opzione LangVersion. Aggiornare il framework di destinazione per accedere alle funzionalità del linguaggio più recenti.

• Specificare LangVersion con il valore default è diverso dall'omissione dell'opzione LangVersion. Specificando default viene utilizzata la versione più recente del linguaggio supportata dal compilatore, senza tenere conto del framework di destinazione. Ad esempio, la compilazione di un progetto destinato a .NET 6 da Visual Studio 17.6 usa C# 10 se non si specifica l'opzione LangVersion, ma usa C# 11 se LangVersion è impostata su default.

• L'opzione del compilatore LangVersion non influisce sui metadati a cui fa riferimento l'applicazione C#.

• Poiché ogni versione del compilatore C# contiene estensioni per la specifica del linguaggio, LangVersion non offre la funzionalità equivalente di una versione precedente del compilatore.

• Mentre gli aggiornamenti di versione di C# coincidono in genere con le versioni principali di .NET, la nuova sintassi e le nuove funzionalità non sono necessariamente associate alla versione specifica del framework. Ogni funzionalità specifica ha requisiti minimi .NET API o Common Language Runtime che potrebbero consentire l'esecuzione su framework di livello inferiore includendo pacchetti NuGet o altre librerie.

• Indipendentemente dall'impostazione di LangVersion specificata, per creare il file con estensione exe o dll viene usata la versione corrente di Common Language Runtime. Un'eccezione è costituita dagli assembly Friend e da ModuleAssemblyName, che vengono eseguiti con -langversion:ISO-1.

Per altri metodi per la specifica della versione del linguaggio C#, vedere Controllo delle versioni del linguaggio C#.

Per informazioni su come impostare questa opzione del compilatore a livello di codice, vedere LanguageVersion.

Specifiche del linguaggio C#

Versione minima dell'SDK necessaria per supportare tutte le funzionalità del linguaggio

La tabella seguente elenca le versioni minime dell'SDK con il compilatore C# che supporta la versione del linguaggio corrispondente:

Nullable

Usare l'opzione Nullable per specificare il contesto nullable. Impostarlo nella configurazione del progetto usando il <Nullable> tag :

<Nullable>enable</Nullable>

L'argomento deve essere enable, disable, warnings o annotations. L'argomento enable attiva il contesto nullable. L'argomento disable disattiva il contesto nullable. L'argomento warnings attiva il contesto di avviso nullable. L'argomento annotations attiva il contesto di annotazione nullable. Per altre informazioni su questi valori, vedere Contesti nullable. Per altre informazioni sull'abilitazione dei tipi riferimento nullable in una codebase esistente, vedere Strategie di migrazione nullable.

L'analisi del flusso deduce il supporto dei valori Null delle variabili all'interno del codice eseguibile. Il supporto dei valori Null dedotto di una variabile è indipendente dal supporto dei valori Null dichiarato della variabile. Il compilatore analizza le chiamate al metodo anche quando la chiamata viene omessa in modo condizionale dall'output compilato. Ad esempio, il compilatore analizza ancora una chiamata a Debug.Assert per ottenere valori Null, anche se la chiamata è condizionale e non viene compilata in build di versione.

La chiamata dei metodi annotati con gli attributi seguenti influisce anche sull'analisi del flusso:

• Precondizioni semplici: AllowNullAttribute e DisallowNullAttribute
• Postcondizioni semplici: MaybeNullAttribute e NotNullAttribute
• Postcondizioni condizionali: MaybeNullWhenAttribute e NotNullWhenAttribute
• DoesNotReturnIfAttribute (ad esempio, DoesNotReturnIf(false) per Debug.Assert) e DoesNotReturnAttribute
• NotNullIfNotNullAttribute
• Postcondizioni dei membri: MemberNotNullAttribute(String) e MemberNotNullAttribute(String[])