Opções do compilador C# que especificam entradas

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

• Referências / -reference ou -references: Metadados de referência do(s) arquivo(s) de assembly especificado(s).
• AddModules-addmodule / : Adicione um módulo (criado com target:module este assembly.)
• EmbedInteropTypes / -link: Incorpore metadados dos arquivos de assembly de interoperabilidade especificados.

Referências

A opção Referências faz com que o compilador importe informações de tipo público no arquivo especificado para o projeto atual, permitindo que você faça referência a metadados dos arquivos de assembly especificados.

<Reference Include="filename" />

filename é o nome de um arquivo que contém um manifesto de 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 no assembly filename.dll. Os arquivos importados devem conter um manifesto. Use AdditionalLibPaths para especificar o diretório no qual uma ou mais referências de assembly estão localizadas. O tópico AdditionalLibPaths também discute os diretórios nos quais o compilador procura assemblies. Para que o compilador reconheça um tipo em um assembly, e não em um módulo, ele precisa ser forçado a resolver o tipo, o 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ê herdar de um tipo em um assembly, o nome do tipo será reconhecido pelo compilador. Às vezes, é necessário fazer referência a duas versões diferentes do mesmo componente de dentro de uma montagem. Para fazer isso, use o elemento Aliases no elemento References para cada arquivo para distinguir entre os dois arquivos. Esse alias será usado como um qualificador para o nome do componente e será resolvido para o componente em um dos arquivos.

Nota

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

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

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

Onde file, file2 são arquivos de saída que contêm metadados. O arquivo não pode conter um manifesto de 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, você pode 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 TypeLoadExceptionarquivo . file não pode conter um assembly. Por exemplo, se o arquivo de saída foi criado com a opção TargetType do módulo, seus metadados podem ser importados com AddModules.

Se o arquivo de saída foi criado com uma opção TargetType diferente do módulo, seus metadados não podem ser importados com AddModules, mas podem ser importados com a opção References.

EmbedInteropTypes

Faz com que o compilador disponibilize informações de tipo COM nos assemblies especificados para o projeto que você está compilando no momento.

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

Onde file1;file2;file3 é uma lista delimitada por ponto-e-vírgula de nomes de arquivo de assembly. Se o nome do ficheiro contiver um espaço, coloque-o entre aspas. A opção EmbedInteropTypes permite implantar um aplicativo que tenha informações de tipo incorporadas. O aplicativo pode usar tipos em um assembly de tempo de execução que implementam as informações de tipo incorporadas sem exigir uma referência ao assembly de tempo de execução. Se várias versões do assembly de tempo de execução forem publicadas, o aplicativo que contém as informações de tipo incorporadas poderá trabalhar com as várias versões sem precisar ser recompilado. Para obter um exemplo, consulte Passo a passo: incorporando tipos de assemblies gerenciados.

Usar a opção EmbedInteropTypes é especialmente útil quando você está trabalhando com interoperabilidade COM. Você pode incorporar tipos COM para que seu aplicativo não exija mais um PIA (primary interop assembly) no computador de destino. A opção EmbedInteropTypes instrui o compilador a incorporar 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, seu aplicativo pode ser executado em um computador de destino que instalou os mesmos tipos de COM com os mesmos valores CLSID. Os aplicativos que automatizam o Microsoft Office são um bom exemplo. Como aplicativos como o Office geralmente mantêm o mesmo valor CLSID em versões diferentes, seu aplicativo pode usar os tipos COM referenciados, desde que o .NET Framework 4 ou posterior esteja instalado no computador de destino e seu aplicativo use métodos, propriedades ou eventos 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.

Nota

Ao criar uma instância de um tipo COM incorporado em seu código, você deve criar a instância usando a interface apropriada. Tentar criar uma instância de um tipo COM incorporado usando o CoClass causa um erro.

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 freqüência. Use a opção de 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 é incorporado a partir de um assembly de interoperabilidade não podem ser usados se esse tipo for de um assembly externo. Esta restrição não se aplica a interfaces. Por exemplo, considere a Range interface definida no Microsoft.Office.Interop.Excel assembly. Se uma biblioteca incorpora tipos de interoperabilidade do Microsoft.Office.Interop.Excel assembly e expõe um método que retorna um tipo genérico que tem um parâmetro cujo tipo é a Range interface, esse método deve retornar uma interface genérica, conforme 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 IList interface genérica sem erro.

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