Opções do compilador C# que especificam entradas

As opções a seguir controlam entradas do compilador. A nova sintaxe MSBuild é mostrada em Negrito. A sintaxe csc.exe mais antiga é mostrada em code style.

• References / -reference ou -references: referenciar metadados do arquivo ou arquivos de assembly especificados.
• AddModules / -addmodule: adicionar um módulo (criado com target:module para este assembly).
• EmbedInteropTypes / -link: inserir metadados dos arquivos de assembly de interoperabilidade especificados.

Referências

A opção References faz com que o compilador importe informações de tipo public no arquivo especificado para o projeto atual, permitindo que você referencie metadados dos arquivos do assembly especificado.

<Reference Include="filename" />

filename é o nome de um arquivo que contém um manifesto do assembly. Para importar mais de um arquivo, inclua um elemento Reference separado para cada arquivo. Você pode definir um alias como um elemento filho do elemento Reference:

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

No exemplo anterior, LS é o identificador C# válido que representa um namespace raiz que conterá todos os namespaces do assembly filename.dll. Os arquivos importados devem conter um manifesto. Use AdditionalLibPaths para especificar o diretório no qual uma ou mais das suas referências de assembly estão localizadas. O tópico AdditionalLibPaths também discute os diretórios nos quais o compilador pesquisa assemblies. Para que o compilador reconheça um tipo em um assembly e não um módulo, ele precisa ser forçado a resolver o tipo, que você pode fazer definindo uma instância do tipo. Há outras maneiras de resolver nomes de tipo em um assembly para o compilador: por exemplo, se você herda de um tipo em um assembly, o nome do tipo será reconhecido pelo compilador. Às vezes, é necessário referenciar duas versões diferentes do mesmo componente de dentro de um assembly. Para fazer isso, use o elemento Alias no elemento References para cada arquivo, a fim de diferenciar entre os dois arquivos. Esse alias será usado como um qualificador do nome do componente e será resolvido para o componente em um dos arquivos.

Observação

No Visual Studio, use o comando Adicionar Referência. Para obter mais informações, consulte Como adicionar ou remover referências usando o Gerenciador de Referências.

AddModules

Essa opção adiciona à compilação atual um módulo que foi criado com a opção <TargetType>module</TargetType>:

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

Em que file e file2 são arquivos de saída que contêm metadados. O arquivo não pode conter um manifesto do assembly. Para importar mais de um arquivo, separe os nomes de arquivo com vírgula ou ponto e vírgula. Todos os módulos adicionados com AddModules devem estar no mesmo diretório que o arquivo de saída em tempo de execução. Ou seja, é possível especificar um módulo em qualquer diretório em tempo de compilação, mas o módulo deve estar no diretório do aplicativo em tempo de execução. Se o módulo não estiver no diretório do aplicativo em tempo de execução, você obterá um TypeLoadException. file não pode conter um assembly. Por exemplo, se o arquivo de saída tiver sido criado com a opção TargetType igual a module, os metadados dele poderão ser importados com AddModules.

Se o arquivo de saída tiver sido criado com uma opção TargetType diferente de module, os metadados dele não poderão ser importados com AddModules, mas poderão ser importados com a opção References.

EmbedInteropTypes

Faz com que o compilador disponibilize as informações de tipo COM nos assemblies especificados para o projeto sendo compilado no momento.

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

Em que file1;file2;file3 é uma lista de nomes de arquivo de assembly delimitada por ponto-e-vírgula. Se o nome do arquivo contém um espaço, coloque o nome entre aspas. A opção EmbedInteropTypes permite que você implante um aplicativo que tenha informações de tipo inserido. O aplicativo pode usar tipos em um assembly de runtime que implementa as informações de tipo inseridas sem a necessidade de uma referência ao assembly de runtime. Se forem publicadas várias versões do assembly de runtime, o aplicativo que contém as informações de tipo inseridas poderá trabalhar com as várias versões sem precisar ser recompilado. Para obter um exemplo, consulte Instruções passo a passo: Inserindo tipos de assemblies gerenciado.

O uso da opção EmbedInteropTypes é especialmente útil quando você está trabalhando com a interoperabilidade COM. Você pode inserir tipos COM para que seu aplicativo não precise mais de um PIA (assembly de interoperabilidade primário) no computador de destino. A opção EmbedInteropTypes instrui o compilador a inserir as informações de tipo COM do assembly de interoperabilidade referenciado no código compilado resultante. O tipo COM é identificado pelo valor CLSID (GUID). Como resultado, o aplicativo pode ser executado em um computador de destino que tem os mesmos tipos COM instalados com os mesmos valores CLSID. Os aplicativos que automatizam o Microsoft Office são um bom exemplo. Como aplicativos como o Office normalmente mantêm o mesmo valor CLSID entre diferentes versões, seu aplicativo pode usar os tipos COM referenciados contanto que o .NET Framework 4 ou posterior esteja instalado no computador de destino e seu aplicativo use métodos, propriedades ou eventos que estão incluídos nos tipos COM referenciados. A opção EmbedInteropTypes incorpora apenas interfaces, estruturas e delegados. Não há suporte para a incorporação de classes COM.

Observação

Quando você cria uma instância de um tipo COM inserido no seu código, você deve criar a instância usando a interface apropriada. Tentar criar uma instância de um tipo COM inserido usando o CoClass causa um erro.

Assim como a opção de compilador References, a opção de compilador EmbedInteropTypes usa o arquivo de resposta Csc.rsp, que faz referência a assemblies .NET usados com frequência. Use a opção do compilador NoConfig se não quiser que o compilador use o arquivo Csc.rsp.

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

Os tipos que têm um parâmetro genérico cujo tipo é inserido de um assembly de interoperabilidade não poderão ser usados se o tipo for de um assembly externo. Essa restrição não se aplica a interfaces. Por exemplo, considere a interface Range que é definida no assembly Microsoft.Office.Interop.Excel. Se uma biblioteca insere tipos de interoperabilidade do assembly Microsoft.Office.Interop.Excel e expõe um método que retorna um tipo genérico que tem um parâmetro cujo tipo é a interface Range, esse método deve retornar uma interface genérica, como mostrado no exemplo de código a seguir.

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;
    }
}

No exemplo a seguir, o código do cliente pode chamar o método que retorna a interface genérica IList sem erros.

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();
    }
}