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 / -unsafe: consentire il codice non gestito.
• 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. In caso contrario, il contesto predefinito è un contesto non controllato. Il valore predefinito per questa opzione è false, ovvero il controllo dell'overflow è disabilitato.

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

Per informazioni su come il contesto di controllo dell'overflow influisce sulle operazioni e sulle operazioni interessate, vedere l'articolo sulle istruzioni checked 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.

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>

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. È possibile 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.

• I metadati a cui viene fatto riferimento nell'applicazione C# non sono soggetti all'opzione del compilatore LangVersion.

• 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 presenta requisiti minimi in termini di API .NET o Common Language Runtime che ne consentono l'esecuzione in versioni di framework di livello inferiore, inclusi 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

L'opzione Nullable consente di specificare il contesto che ammette i valori Null. Può essere impostata nella configurazione del progetto usando il tag <Nullable>:

<Nullable>enable</Nullable>

L'argomento deve essere enable, disable, warnings o annotations. L'argomento enable abilita il contesto che ammette i valori Null. Se si specifica disable, il contesto che ammette i valori Null verrà disabilitato. Quando si specifica l'argomento warnings, viene abilitato il contesto di avviso che ammette i valori Null. Quando si specifica l'argomento annotations, viene abilitato il contesto di annotazione che ammette i valori Null. I valori sono descritti e illustrati nell'articolo Contesti che ammettono i valori Null. Per altre informazioni sulle attività coinvolte nell'abilitazione dei tipi riferimento che ammettono i valori Null in una codebase esistente, vedere l'articolo sulle strategie di migrazione per i tipi che ammettono valori Null.

L'analisi del flusso viene usata per dedurre 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. Le chiamate ai metodi vengono analizzate anche quando vengono omesse in modo condizionale. Ad esempio, Debug.Assert in modalità di rilascio.

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

• Pre-condizioni semplici: AllowNullAttribute e DisallowNullAttribute
• Post-condizioni semplici: MaybeNullAttribute e NotNullAttribute
• Post-condizioni condizionali: MaybeNullWhenAttribute e NotNullWhenAttribute
• DoesNotReturnIfAttribute (ad esempio, DoesNotReturnIf(false) per Debug.Assert) e DoesNotReturnAttribute
• NotNullIfNotNullAttribute
• Post-condizioni membro: MemberNotNullAttribute(String) e MemberNotNullAttribute(String[])