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.

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

Riferimenti

L'opzione Riferimenti fa in modo 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 Reference separato per ogni file. È possibile definire un alias come elemento figlio dell'elemento Reference :

<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. L'argomento AdditionalLibPaths illustra anche le directory in cui il compilatore cerca gli assembly. Affinché il compilatore riconosca un tipo in un assembly e non in un modulo, deve essere forzato a risolvere il tipo, che è possibile eseguire definendo un'istanza del tipo. Esistono altri modi per risolvere i nomi dei tipi in un assembly per il compilatore, ad esempio se si eredita da un tipo in un assembly, il nome del tipo verrà quindi riconosciuto dal compilatore. A volte è necessario fare riferimento a due versioni diverse dello stesso componente dall'interno di un assembly. A tale scopo, utilizzare l'elemento Aliases nell'elemento References per ogni file per distinguere tra i due file. Questo alias verrà usato come qualificatore per il nome del componente e verrà risolto nel componente in uno dei file.

Annotazioni

In Visual Studio usare il comando Aggiungi riferimento . Per altre informazioni, vedere Procedura: Aggiungere o rimuovere riferimenti tramite Gestione riferimenti.

AddModules

Questa opzione aggiunge un modulo creato con l'opzione <OutputType>module</OutputType> 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ù file, separare i nomi di file con una virgola o un punto e virgola. Tutti i moduli aggiunti con AddModules devono trovarsi nella stessa directory del file di output in fase di esecuzione. Ciò significa che è possibile specificare un modulo in qualsiasi directory in fase di compilazione, ma il modulo deve trovarsi 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 OutputType del modulo, i relativi metadati possono essere importati con AddModules.

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

EmbedInteropTypes

Fa in modo che il compilatore renda disponibili al progetto le informazioni sul tipo COM negli assembly specificati attualmente in fase di compilazione.

<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 incorporato senza richiedere un riferimento all'assembly di runtime. Se vengono pubblicate diverse versioni dell'assembly di runtime, l'applicazione che contiene le informazioni sul tipo incorporato può funzionare con le varie versioni senza dover essere ricompilata. Per un esempio, vedere Procedura dettagliata: Incorporamento di tipi da assembly gestiti.

L'uso dell'opzione EmbedInteropTypes è particolarmente utile quando si usa l'interoperabilità COM. È possibile incorporare tipi COM in modo che l'applicazione non richieda più un assembly di interoperabilità primario (PIA) 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 è identificato dal valore CLSID (GUID). Di conseguenza, l'applicazione può essere eseguita in un computer di destinazione che ha installato gli stessi tipi COM con gli stessi valori CLSID. Le applicazioni che automatizzano Microsoft Office sono un buon esempio. Poiché le applicazioni come Office mantengono lo stesso valore CLSID in versioni diverse, l'applicazione può usare i tipi COM a cui si fa riferimento, purché .NET Framework 4 o versione successiva 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.

Annotazioni

Quando si crea un'istanza di un tipo COM incorporato nel codice, è necessario creare l'istanza usando l'interfaccia appropriata. Il tentativo di creare un'istanza di un tipo COM incorporato tramite CoClass genera un errore.

Analogamente all'opzione del compilatore References , 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 con un parametro generico il cui tipo è incorporato da un assembly di interoperabilità non possono essere utilizzati 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 con un parametro il cui tipo è l'interfaccia Range , tale 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 IList generica 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();
    }
}