Opzioni del compilatore C# che controllano la generazione del codice

  • Articolo

Le opzioni seguenti controllano la generazione del codice dal compilatore. La nuova sintassi di MSBuild viene visualizzata in grassetto. La sintassi di csc.exe precedente è illustrata in code style.

  • DebugType / -debug: genera (o non genera) informazioni di debug.
  • Optimize / -optimize: abilita le ottimizzazioni.
  • Deterministic / -deterministic: genera un output equivalente byte per byte dalla stessa origine di input.
  • ProduceOnlyReferenceAssembly / -refonly: genera un assembly di riferimento, anziché un assembly completo, come output primario.

DebugType

L'opzione DebugType indica al compilatore di generare informazioni di debug e di inserirle nel file o nei file di output. Le informazioni di debug vengono aggiunte per impostazione predefinita.

<DebugType>pdbonly</DebugType>

Per tutte le versioni del compilatore a partire da C# 6.0, non esiste alcuna differenza tra pdbonly e full. Scegliere pdbonly. Per modificare il percorso del file .pdb, vedere PdbFile.

I valori validi sono i seguenti:

Valore Significato
full Generare informazioni di debug nel .pdb usando il formato predefinito per la piattaforma corrente:
Windows: un file pdb di Windows.
Linux/macOS: un file Portable PDB.
pdbonly Uguale a full. Per altre informazioni, vedere la nota seguente.
portable Generare informazioni di debug nel file con estensione pdb usando il formato Portable PDB multipiattaforma.
embedded Generare informazioni di debug nel file .dll/.exe stesso (il file .pdb non viene generato) usando formato Portable PDB.

Importante

Le informazioni seguenti si applicano solo ai compilatori precedenti a C# 6.0. Il valore di questo elemento può essere full o pdbonly. L'argomento full, effettivo se non si specifica pdbonly, consente di collegare un debugger al programma in esecuzione. Specificando pdbonly si consente il debug del codice sorgente quando il programma viene avviato nel debugger, ma l'assembler viene visualizzato solo se il programma in esecuzione è collegato al debugger. Usare questa opzione per creare build di debug. Se si usa Full, tenere presente che comporta un impatto sulla velocità e sulle dimensioni del codice ottimizzato JIT e un impatto ridotto sulla qualità del codice con full. Per la generazione di codice di versione, è consigliabile usare pdbonly o non usare alcun file PDB. Una differenza tra pdbonly e full sta nel fatto che con full il compilatore genera un DebuggableAttribute, che viene usato per indicare al compilatore JIT che le informazioni di debug sono disponibili. Di conseguenza, se nel codice DebuggableAttribute è impostato su false e si usa full, verrà restituito un errore. Per altre informazioni su come configurare le prestazioni di debug di un'applicazione, vedere Semplificazione del debug di un'immagine.

Ottimizzazione

L'opzione Optimize abilita o disabilita le ottimizzazioni eseguite dal compilatore per ridurre le dimensioni del file di output e aumentarne la velocità e l'efficienza. L'opzione Optimize è abilitata per impostazione predefinita per una configurazione della build di Versione. È disattivato per impostazione predefinita per un debug e per qualsiasi altra configurazione di compilazione.

<Optimize>true</Optimize>

Impostare l'opzione Optimize dalla pagina delle proprietà di compilazione per il progetto in Visual Studio.

L'opzione Optimize comunica poi a Common Language Runtime di ottimizzare il codice in fase di esecuzione. Per impostazione predefinita, le ottimizzazioni sono disabilitate. Per abilitare le ottimizzazioni, specificare Optimize+. Durante la compilazione di un modulo per l'uso da parte di un assembly, specificare per Optimize le stesse impostazioni usate per l'assembly. È possibile combinare le opzioni Optimize e Debug.

Deterministico

Fa sì che il compilatore generi un assembly il cui output byte per byte è identico in tutte le compilazioni se si usano input identici.

<Deterministic>true</Deterministic>

Per impostazione predefinita, l'output del compilatore che deriva da un set di input specifico è univoco, poiché il compilatore aggiunge un timestamp e un MVID (Module.ModuleVersionId, ovvero un GUID che identifica in modo univoco il modulo e la versione) generato da numeri casuali. L'opzione <Deterministic> si usa per generare un assembly deterministico il cui contenuto binario è identico in tutte le compilazioni purché l'input rimanga lo stesso. In una compilazione di questo tipo, i campi relativi a timestamp e MVID verranno sostituiti con i valori derivati da un hash di tutti gli input di compilazione. Il compilatore considera gli input seguenti al fine del determinismo:

  • La sequenza dei parametri della riga di comando.
  • Il contenuto del file di risposta del file RSP del compilatore.
  • La versione precisa del compilatore in uso e i relativi assembly di riferimento.
  • Il percorso della directory corrente.
  • Il contenuto binario di tutti i file passati in modo esplicito al compilatore direttamente o indirettamente, tra cui:
    • File di origine
    • Assembly di riferimento
    • Moduli a cui viene fatto riferimento
    • Risorse
    • Il file di chiave con nome sicuro
    • @ file di risposta
    • Analizzatori
    • Set di regole
    • Altri file che possono essere usati dagli analizzatori
  • Le impostazioni cultura correnti (per la lingua in cui vengono generati la diagnostica e i messaggi di eccezione).
  • Codifica predefinita (o la tabella codici corrente) se non è specificata la codifica.
  • L'esistenza, non esistenza e contenuto dei file nei percorsi di ricerca del compilatore (specificati, ad esempio, da -lib o -recurse).
  • Piattaforma Common Language Runtime (CLR) in cui viene eseguito il compilatore.
  • Il valore di %LIBPATH%, che può influenzare il caricamento delle dipendenze dell'analizzatore.

La compilazione deterministica può essere usata per stabilire se un file binario viene compilato da un'origine attendibile. L'output deterministico può risultare utile quando l'origine è disponibile pubblicamente. Può anche determinare se le fasi di compilazione dipendenti dalle modifiche apportate al file binario sono usate nel processo di compilazione.

ProduceOnlyReferenceAssembly

L'opzione ProduceOnlyReferenceAssembly indica che deve essere restituito un assembly di riferimento anziché un assembly di implementazione come output primario. Il parametro ProduceOnlyReferenceAssembly disabilita automaticamente l'output dei file PDB poiché non è possibile eseguire gli assembly di riferimento.

<ProduceOnlyReferenceAssembly>true</ProduceOnlyReferenceAssembly>

Gli assembly di riferimento sono un tipo speciale di assembly. Gli assembly di riferimento contengono solo la quantità minima di metadati necessari per rappresentare la superficie API pubblica della libreria. Includono dichiarazioni per tutti i membri significativi per fare riferimento a un assembly negli strumenti di compilazione, ma escludono tutte le implementazioni dei membri e le dichiarazioni dei membri privati che non hanno alcun impatto osservabile sul contratto API. Per altre informazioni, vedere Assembly di riferimento.

Le opzioni ProduceOnlyReferenceAssembly e ProduceReferenceAssembly si escludono a vicenda.