Opzioni del compilatore C# che ne controllano l'output

Le opzioni seguenti controllano la generazione dell'output del compilatore.

DocumentationFile

L'opzione DocumentationFile consente di inserire commenti per la documentazione in un file XML. Per altre informazioni sulla documentazione del codice, vedere Tag consigliati per i commenti sulla documentazione. Il valore specifica il percorso del file XML di output. Il file XML contiene i commenti nei file di codice sorgente della compilazione.

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

Il file di codice sorgente che contiene istruzioni Main o di primo livello viene restituito per primo nel file XML. Spesso si vuole usare il file .xml generato con IntelliSense. Il nome file .xml deve corrispondere al nome dell'assembly. Il file .xml deve trovarsi nella stessa directory dell'assembly. In questo modo, quando si farà riferimento all'assembly nel progetto Visual Studio, verrà trovato anche il file .xml. Per altre informazioni sulla generazione di commenti di codice, vedere Fornitura di commenti del codice. A meno che non si esegua la compilazione con <TargetType:Module>, in file saranno inclusi i tag <assembly> e </assembly> che specificano il nome del file contenente il manifesto dell’ assembly per il file di output. Come esempi, vedere Come usare le funzionalità della documentazione XML.

Questa opzione può essere usata in qualsiasi progetto di tipo .NET SDK. Per altre informazioni, vedere La proprietà DocumentationFile.

OutputAssembly

L'opzione OutputAssembly specifica il nome del file di output. Il percorso di output specifica la cartella in cui viene inserito l'output del compilatore.

<OutputAssembly>folder</OutputAssembly>

Specificare il nome completo e l'estensione del file che si vuole creare. Se non si specifica il nome del file di output, MSBuild usa il nome del progetto per specificare il nome dell'assembly di output. I progetti di stile precedente usano le regole seguenti:

• Un .exe accetta il nome dal file di codice sorgente che contiene il metodo Main o le istruzioni di primo livello.
• Un file con estensione dll o netmodule corrisponderà al nome del primo file di codice sorgente.

I moduli prodotti durante una compilazione diventano file associati a un assembly prodotto anch'esso in fase di compilazione. Per visualizzare il manifesto dell'assembly e i file associati, usare ildasm.exe.

L'opzione del compilatore OutputAssembly è necessaria perché un file eseguibile sia la destinazione di un assembly Friend.

PlatformTarget

Specifica la versione di CLR che può eseguire l'assembly.

<PlatformTarget>anycpu</PlatformTarget>

• anycpu (valore predefinito) consente di compilare l'assembly in modo da poter essere eseguito su qualsiasi piattaforma. L'applicazione viene eseguita come processo a 64 bit, quando possibile, e tramite essa viene eseguito il fallback a 32 bit solo quando questa modalità è disponibile.
• anycpu32bitpreferred consente di compilare l'assembly in modo da poter essere eseguito su qualsiasi piattaforma. L'applicazione viene eseguita in modalità a 32 bit nei sistemi che supportano sia le applicazioni a 64 bit sia quelle a 32 bit. È possibile specificare questa opzione solo per i progetti destinati a .NET Framework 4.5 o versioni successive.
• ARM compila l'assembly in modo da poter essere eseguito su un computer con processore Advanced RISC Machine (ARM).
• ARM64 compila l'assembly in modo che possa essere eseguito da CLR a 64 bit in un computer con un processore Advanced RISC Machine (ARM) che supporta il set di istruzioni A64.
• x64 compila l'assembly in modo che possa essere eseguito da CLR a 64 bit in un computer che supporta il set di istruzioni AMD64 o EM64T.
• x86 compila l'assembly in modo che possa essere eseguito da CLR a 32 bit, compatibile con x86.
• Itanium compila l'assembly in modo che possa essere eseguito da CLR a 64 bit in un computer dotato di processore Itanium.

In un sistema operativo Windows a 64 bit:

• Gli assembly compilati con l'opzione x86 potranno essere eseguiti da CLR a 32 bit in WOW64.
• Una DLL compilata con l'opzione anycpu viene eseguita dallo stesso Common Language Runtime del processo in cui viene caricata.
• Gli eseguibili compilati con anycpu vengono eseguiti dalla versione di Common Language Runtime a 64 bit.
• Gli eseguibili compilati con l'opzione anycpu32bitpreferred vengono eseguiti dalla versione di Common Language Runtime a 32 bit.

L'impostazione anycpu32bitpreferred è valida solo per file eseguibili (con estensione exe) e richiede .NET Framework 4.5. Per altre informazioni sullo sviluppo di un'applicazione da eseguire su un sistema operativo Windows a 64 bit, vedere Applicazioni a 64 bit.

L'opzione PlatformTarget viene impostata dalla pagina delle proprietà Build per il progetto in Visual Studio.

Il comportamento di anycpu presenta alcune sfumature aggiuntive in .NET Core e .NET 5 e versioni successive. Quando si imposta anycpu, pubblicare l'applicazione ed eseguirla con il dotnet.exe a x86 o il dotnet.exe a x64. Per le applicazioni autonome, il passaggio dotnet publish crea un pacchetto dell'eseguibile per il RID di configurazione.

ProduceReferenceAssembly

L'opzione ProduceReferenceAssembly controlla se il compilatore produce assembly di riferimento.

<ProduceReferenceAssembly>true</ProduceReferenceAssembly>

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

Le opzioni ProduceReferenceAssembly e ProduceOnlyReferenceAssembly si escludono a vicenda.

In genere non è necessario lavorare direttamente con i file di assembly di riferimento. Per impostazione predefinita, gli assembly di riferimento vengono generati in una sottocartella ref del percorso intermedio, ad esempio obj/ref/. Per generarli nella directory di output (ad esempio bin/ref/), impostare ProduceReferenceAssemblyInOutDir su true nel progetto.

.NET SDK 6.0.200 ha apportato una modifica che ha spostato gli assembly di riferimento dalla directory di output alla directory intermedia per impostazione predefinita.

TargetType

L'opzione TargetType del compilatore può essere specificata in uno dei formati seguenti:

• library: per creare una libreria di codice. library è il valore predefinito.
• exe: per creare un file con estensione exe.
• module per creare un modulo.
• winexe per creare un programma di Windows.
• winmdobj per creare un file .winmdobj intermedio.
• appcontainerexe per creare un file .exe per le applicazioni in Windows 8.x Store.

<TargetType>library</TargetType>

Il compilatore crea solo un manifesto dell'assembly per ogni compilazione. Le informazioni su tutti i file in una compilazione vengono inserite nel manifesto dell'assembly. Quando si generano più file di output nella riga di comando, è possibile creare solo un manifesto e deve essere inseriti nel primo file di output specificato nella riga di comando.

Se si crea un assembly, è possibile indicare che tutto o parte del codice è conforme a CLS con l'attributo CLSCompliantAttribute.

libreria

L'opzione library consente la creazione da parte del compilatore di una libreria di collegamento dinamico (DLL), anziché di un file eseguibile (EXE). La libreria creata avrà estensione .dll Se non diversamente specificato tramite l'opzione OutputAssembly, il nome del file di output corrisponderà al nome del primo file di input. Quando si compila un file .dll non è necessario un metodo Main.

exe

L'opzione exe indica al compilatore di creare un file eseguibile (EXE), applicazione console. Il file eseguibile verrà creato con estensione .exe. Usare winexe per creare l'eseguibile di un programma Windows. Se non diversamente specificato con l'opzione OutputAssembly, il nome del file di output accetta il nome del file di input che contiene il punto di ingresso (metodo Main o istruzioni di primo livello). Un solo punto di ingresso è necessario nei file del codice sorgente che vengono compilati in un file con estensione EXE. L'opzione del compilatore StartupObject consente di specificare la classe che contiene il metodo Main, nei casi in cui il codice ha più di una classe con un metodo Main.

modulo

Questa opzione indica al compilatore di non generare un manifesto dell'assembly. Per impostazione predefinita, l'estensione del file di output creato eseguendo la compilazione con questa opzione sarà .netmodule. Un file che non dispone di un manifesto dell'assembly non può essere caricato dal runtime .NET. È tuttavia possibile incorporare un file di questo tipo nel manifesto di un assembly con AddModules. Se viene creato più di un modulo in un'unica compilazione, i tipi internal in un modulo saranno disponibili per gli altri moduli nella compilazione. Se il codice di un modulo fa riferimento a tipi internal in un altro modulo, è necessario incorporare entrambi i moduli in un manifesto dell'assembly tramite AddModules. La creazione di un modulo non è supportata nell'ambiente di sviluppo di Visual Studio.

winexe

Con l'opzione winexe il compilatore crea un file eseguibile (EXE), ovvero un programma di Windows. Il file eseguibile verrà creato con estensione .exe. È un programma di Windows che genera un'interfaccia utente dalla libreria di .NET o con le API Windows. Usare exe per creare un'applicazione console. Se non diversamente specificato con l'opzione OutputAssembly, il nome del file di output corrisponderà al nome del file di input contenente il metodo Main. Un solo metodo Main è necessario nei file del codice sorgente che vengono compilati in un file con estensione exe. L'opzione StartupObject consente di specificare la classe che contiene il metodo Main, nei casi in cui il codice ha più di una classe con un metodo Main.

winmdobj

Se si utilizza l'opzione winmdobj, il compilatore crea un file intermedio .winmdobj che è possibile convertire in un file binario Windows Runtime (.winmd). Il file .winmd può quindi essere utilizzato dai programmi C++ e JavaScript, oltre ai programmi di linguaggi gestiti.

L'impostazione winmdobj segnala al compilatore che è richiesto un modulo intermedio. Il file .winmd può quindi essere inserito dallo strumento di esportazione WinMDExp per produrre un file di metadati Windows (.winmd). Il file .winmd contiene il codice della libreria originale e i metadati di WinMD utilizzati da JavaScript o C++ e da Windows Runtime. L'output di un file compilato usando l'opzione del compilatore winmdobj viene usato solo come input per lo strumento di esportazione WimMDExp. Il file .winmdobj stesso non viene referenziato direttamente. A meno che non si usi l'opzione OutputAssembly, il nome del file di output corrisponderà al nome del primo file di input. Non è richiesto un metodo Main.

appcontainerexe

Se si usa l'opzione del compilatore appcontainerexe, il compilatore crea un file eseguibile Windows (.exe) che deve essere eseguito in un contenitore di app. Questa opzione equivale a -target:winexe, ma è progettata per le applicazioni di Windows 8.x Store.

Per richiedere che l'app venga eseguita in un contenitore di app, questa opzione imposta un bit nel file eseguibile di tipo PE. Quando questo bit è impostato, viene generato un errore se il metodo CreateProcess tenta di avviare il file eseguibile all'esterno di un contenitore di app. A meno che non si usi l'opzione OutputAssembly, il nome del file di output corrisponderà al nome del file di input contenente il metodo Main.