Opções do compilador C# que especificam entradas

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

• Referências / -reference ou -references: referenciar metadados do arquivo de assembly ou arquivos especificados.
• AddModules / -addmodule: adicionar um módulo (criado com target:module este assembly).)
• EmbedInteropTypes: insira / -link 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ê referencie metadados dos arquivos de assembly especificados.

<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 de referência 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 assemblyfilename.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 pesquisa 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 um assembly. 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.

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ência.

AddModules

Essa opção adiciona um módulo que foi criado com a opção <OutputType>module</OutputType> 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 do assembly. Para importar mais de um arquivo, separe os nomes de arquivo com uma vírgula ou um 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 TypeLoadException. file não pode conter um assembly. Por exemplo, se o arquivo de saída foi criado com a opção OutputType do módulo, seus metadados podem ser importados com AddModules.

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

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 está uma lista delimitada por ponto-e-vírgula de nomes de arquivo de assembly. Se o nome do arquivo contiver um espaço, coloque o nome entre aspas. A opção EmbedInteropTypes permite implantar um aplicativo que tenha informações de tipo inseridas. Em seguida, o aplicativo pode usar tipos em um assembly de runtime que implementam as informações de tipo inserido sem exigir uma referência ao assembly de runtime. Se várias versões do assembly de runtime forem publicadas, o aplicativo que contém as informações de tipo inserido poderá funcionar com as várias versões sem precisar ser recompilado. Para obter um exemplo, consulte Passo a passo: inserindo tipos de assemblies gerenciados.

Usar a opção EmbedInteropTypes é especialmente útil quando você está trabalhando com a interoperabilidade COM. Você pode inserir tipos COM para que seu aplicativo não exija mais 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, seu aplicativo pode ser executado em um computador de destino que instalou os mesmos tipos COM com os mesmos valores CLSID. Aplicativos que automatizam o Microsoft Office são um bom exemplo. Como aplicativos como o Office geralmente mantêm o mesmo valor CLSID em diferentes versões, 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 inserção de classes COM.

Observação

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

Assim como a opção do compilador References , a opção do 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 você 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;

Tipos que têm um parâmetro genérico cujo tipo é inserido de um assembly de interoperabilidade não podem ser usados se esse tipo for de um assembly externo. Essa restrição não se aplica a interfaces. Por exemplo, considere a Range interface definida no Microsoft.Office.Interop.Excel assembly. Se uma biblioteca inserir tipos de interoperabilidade do Microsoft.Office.Interop.Excel assembly e expor um método que retorna um tipo genérico que tenha um parâmetro cujo tipo é a Range interface, esse método deverá 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 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();
    }
}