Opzioni del compilatore C# che specificano gli input

Le opzioni seguenti controllano gli input del compilatore. La nuova sintassi di MSBuild viene visualizzata in grassetto. La sintassi di csc.exe precedente è illustrata in code style.

• Riferimenti / -reference o -references: metadati di riferimento dal file o dai file di assembly specificati.
• AddModules / -addmodule: aggiungere un modulo (creato con target:module a questo assembly).
• EmbedInteropTypes / -link: incorpora i metadati dai file di assembly di interoperabilità specificati.

Riferimenti

L'opzione Riferimenti fa sì che il compilatore importi informazioni sul tipo pubblico nel file specificato nel progetto corrente, consentendo di fare riferimento ai metadati dai file di assembly specificati.

<Reference Include="filename" />

filename è il nome di un file che contiene un manifesto dell'assembly. Per importare più file, includere un elemento Riferimento separato per ogni file. È possibile definire un alias come elemento figlio dell'elemento Riferimento:

<Reference Include="filename.dll">
  <Aliases>LS</Aliases>
</Reference>

Nell'esempio precedente LS è l'identificatore C# valido che rappresenta uno spazio dei nomi radice che conterrà tutti gli spazi dei nomi nell'assembly filename.dll. I file importati devono contenere un manifesto. Usare AdditionalLibPaths per specificare la directory in cui si trovano uno o più riferimenti all'assembly. Nell'argomento AdditionalLibPaths sono indicate anche le directory in cui il compilatore cerca gli assembly. Perché il compilatore sia in grado di riconoscere un tipo in un assembly e non in un modulo, è necessario imporre la risoluzione del tipo stesso. A questo scopo, è possibile definire un'istanza del tipo. La risoluzione dei nomi dei tipi in un assembly può avvenire anche con altre modalità. Se, ad esempio, si eredita da un tipo in un assembly, il nome del tipo sarà riconosciuto dal compilatore. In alcuni casi è necessario fare riferimento a due versioni diverse dello stesso componente da un unico assembly. A tale scopo, utilizzare l'elemento Aliases nell'elemento Riferimenti per ogni file per distinguere tra i due file. Questo alias verrà usato come qualificatore per il nome del componente, quindi risolto nel componente stesso in uno dei file.

AddModules

Questa opzione aggiunge un modulo creato con l'opzione <TargetType>module</TargetType> alla compilazione corrente:

<AddModule Include=file1 />
<AddModule Include=file2 />

Dove file, file2 sono file di output che contengono metadati. Il file non può contenere un manifesto dell'assembly. Per importare più di un file, separare i nomi dei file con una virgola o con un punto e virgola. Tutti i moduli aggiunti con AddModules devono trovarsi nella stessa directory del file di output in fase di esecuzione. Ovvero, è possibile specificare un modulo in una directory in fase di compilazione, ma il modulo deve essere nella directory dell'applicazione in fase di esecuzione. Se il modulo non si trova nella directory dell'applicazione in fase di esecuzione, si otterrà un TypeLoadException. file non può contenere un assembly. Ad esempio, se il file di output è stato creato con l’opzione TargetType del modulo, i relativi metadati possono essere importati con AddModules.

Se il file di output è stato creato con un'opzione TargetType diversa da modulo, i relativi metadati non possono essere importati con AddModules, ma possono essere importati con l'opzione Riferimenti.

EmbedInteropTypes

Indica al compilatore di rendere disponibili al progetto in fase di compilazione le informazioni sui tipi COM presenti negli assembly specificati.

<References>
  <EmbedInteropTypes>file1;file2;file3</EmbedInteropTypes>
</References>

Dove file1;file2;file3 è un elenco delimitato da punto e virgola di nomi di file di assembly. Se il nome del file contiene uno spazio, racchiudere il nome tra virgolette. L'opzione EmbedInteropTypes consente di distribuire un'applicazione con informazioni sul tipo incorporate. L'applicazione può quindi usare i tipi in un assembly di runtime che implementano le informazioni sul tipo incorporate senza dovere far riferimento all'assembly di runtime. Se vengono pubblicate diverse versioni dell'assembly di runtime, l'applicazione che contiene le informazioni sul tipo incorporate può funzionare con le diverse versioni senza che sia necessaria la ricompilazione. Per un esempio, vedere Procedura dettagliata: incorporamento dei tipi da assembly gestiti.

L'uso dell'opzione EmbedInteropTypes è particolarmente utile quando si usa l'interoperabilità COM. È possibile incorporare tipi COM in modo che per l'applicazione non sia più necessario un assembly di interoperabilità primario nel computer di destinazione. L'opzione EmbedInteropTypes indica al compilatore di incorporare le informazioni sul tipo COM dall'assembly di interoperabilità a cui si fa riferimento nel codice compilato risultante. Il tipo COM viene identificato dal valore CLSID (GUID). Di conseguenza, l'applicazione può essere eseguita in un computer di destinazione in cui sono stati installati gli stessi tipi COM con gli stessi valori CLSID. Le applicazioni che consentono di automatizzare Microsoft Office costituiscono un valido esempio. Poiché applicazioni come Office mantengono in genere lo stesso valore CLSID in versioni diverse, l'applicazione può usare i tipi COM a cui si fa riferimento purché .NET Framework 4 o versioni successive sia installato nel computer di destinazione e l'applicazione usi metodi, proprietà o eventi inclusi nei tipi COM a cui si fa riferimento. L'opzione EmbedInteropTypes incorpora solo interfacce, strutture e delegati. L'incorporamento delle classi COM non è supportato.

Analogamente all'opzione del compilatore Riferimenti, l'opzione del compilatore EmbedInteropTypes usa il file di risposta Csc.rsp, che fa riferimento agli assembly .NET usati di frequente. Usare l'opzione del compilatore NoConfig se non si vuole che il compilatore usi il file Csc.rsp.

// The following code causes an error if ISampleInterface is an embedded interop type.
ISampleInterface<SampleType> sample;

I tipi che hanno un parametro generico il cui tipo è incorporato da un assembly di interoperabilità non possono essere usati se tale tipo proviene da un assembly esterno. Questa restrizione non si applica alle interfacce. Si consideri ad esempio l'interfaccia Range definita nell'assembly Microsoft.Office.Interop.Excel. Se una libreria incorpora tipi di interoperabilità dall'assembly Microsoft.Office.Interop.Excel ed espone un metodo che restituisce un tipo generico che ha un parametro il cui tipo è l'interfaccia Range, il metodo deve restituire un'interfaccia generica, come illustrato nell'esempio di codice seguente.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using Microsoft.Office.Interop.Excel;

public class Utility
{
    // The following code causes an error when called by a client assembly.
    public List<Range> GetRange1()
    {
        return null;
    }

    // The following code is valid for calls from a client assembly.
    public IList<Range> GetRange2()
    {
        return null;
    }
}

Nell'esempio seguente, il codice client può chiamare il metodo che restituisce l'interfaccia generica IList senza errori.

public class Client
{
    public void Main()
    {
        Utility util = new Utility();

        // The following code causes an error.
        List<Range> rangeList1 = util.GetRange1();

        // The following code is valid.
        List<Range> rangeList2 = (List<Range>)util.GetRange2();
    }
}