Opciones del compilador de C# que especifican entradas

Las opciones siguientes controlan las entradas del compilador. La nueva sintaxis de MSBuild se muestra en negrita. La sintaxis de csc.exe anterior se muestra en code style.

• References / -reference o -references: se hace referencia a los metadatos de los archivos de ensamblado especificados.
• AddModules / -addmodule: se agrega un módulo (creado con target:module para este ensamblado).
• EmbedInteropTypes / -link: se insertan metadatos de los archivos de ensamblado de interoperabilidad especificados.

Referencias

La opción References hace que el compilador importe información de tipo public del archivo especificado al proyecto actual, lo que permite hacer referencia a metadatos de los archivos de ensamblado especificados.

<Reference Include="filename" />

filename es el nombre de un archivo que contiene un manifiesto del ensamblado. Para importar más de un archivo, incluya un elemento Reference diferente para cada archivo. Puede definir un alias como un elemento secundario del elemento Reference:

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

En el ejemplo anterior, LS es el identificador de C# válido que representa un espacio de nombres raíz que contendrá todos los espacios de nombres en el archivo filename.dll del ensamblado. Los archivos que importe deben contener un manifiesto. Use AdditionalLibPaths para especificar el directorio en el que se encuentran una o varias de las referencias de ensamblado. En el tema AdditionalLibPaths también se describen los directorios en los que el compilador busca ensamblados. Para que el compilador reconozca un tipo de un ensamblado (y no de un módulo), debe obligársele a que resuelva el tipo, lo que se puede conseguir si se define una instancia del tipo. Existen otras formas de que el compilador resuelva nombres de tipos en un ensamblado; por ejemplo, si se hereda de un tipo de un ensamblado, el compilador reconocerá el nombre del tipo. A veces es necesario hacer referencia a dos versiones diferentes del mismo componente desde un ensamblado. Para ello, use el elemento Aliases del elemento References de cada archivo para distinguir entre los dos archivos. Este alias se usará como calificador para el nombre del componente y se resolverá en el componente de uno de los archivos.

Nota

En Visual Studio, use el comando Agregar referencia. Para obtener más información, consulta Procedimiento para agregar o quitar referencias mediante el Administrador de referencias.

AddModules

Esta opción agrega un módulo que se ha creado con el modificador <TargetType>module</TargetType> para la compilación actual:

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

Donde file, file2 son archivos de salida que contienen metadatos. El archivo no puede contener un manifiesto del ensamblado. Para importar más de un archivo, hay que separar los nombres de archivo con una coma o un punto y coma. Todos los módulos agregados con AddModules deben encontrarse en el mismo directorio que el archivo de salida en tiempo de ejecución. Es decir, puede especificar un módulo de cualquier directorio en el momento de la compilación, pero el módulo debe encontrarse en el directorio de la aplicación en tiempo de ejecución. Si el módulo no se encuentra en el directorio de la aplicación en tiempo de ejecución, obtendrá TypeLoadException. file no puede contener ningún ensamblado. Por ejemplo, si el archivo de salida se ha creado con la opción TargetType de module, sus metadatos se pueden importar con AddModules.

Si el archivo de salida se ha creado con una opción TargetType diferente de module, no se podrán importar sus metadatos con AddModules, pero sí con References.

EmbedInteropTypes

Hace que el compilador facilite al proyecto que se está compilando información de tipos COM en los ensamblados especificados.

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

Donde file1;file2;file3 es una lista de nombres de archivo de ensamblado delimitados por signos de punto y coma. Si el nombre de archivo contiene un espacio, escríbalo entre comillas. La opción EmbedInteropTypes permite implementar una aplicación que tiene información de tipo insertada. La aplicación puede usar los tipos de un ensamblado en tiempo de ejecución que implementan la información de tipo incrustada sin necesidad de una referencia al ensamblado en tiempo de ejecución. Si hay varias versiones del ensamblado en tiempo de ejecución publicadas, la aplicación que contiene la información de tipo incrustada puede trabajar con las distintas versiones sin tener que volver a compilar. Para obtener un ejemplo, vea Tutorial: Insertar los tipos de los ensamblados administrados.

La opción EmbedInteropTypes resulta de especial utilidad cuando se trabaja con la interoperabilidad COM. Puede incrustar tipos COM para que la aplicación ya no necesite un ensamblado de interoperabilidad primario (PIA) en el equipo de destino. La opción EmbedInteropTypes indica al compilador que inserte la información de tipo COM del ensamblado de interoperabilidad al que se hace referencia en el código compilado resultante. El tipo COM se identifica mediante el valor de CLSID (GUID). Como resultado, la aplicación se puede ejecutar en un equipo de destino que tenga instalados los mismos tipos COM con los mismos valores de CLSID. Las aplicaciones que automatizan Microsoft Office son un buen ejemplo. Dado que las aplicaciones como Office suelen mantener el mismo valor de CLSID en las distintas versiones, la aplicación puede usar los tipos COM a los que se hace referencia siempre que .NET Framework 4 o posterior esté instalado en el equipo de destino y la aplicación emplee métodos, propiedades o eventos que estén incluidos en los tipos COM a los que se hace referencia. La opción EmbedInteropTypes solo inserta interfaces, estructuras y delegados. No se admite la inserción de clases COM.

Nota

Cuando se crea una instancia de un tipo COM incrustado en el código, hay que crear la instancia mediante la interfaz adecuada. Si se intenta crear una instancia de un tipo COM incrustado mediante la coclase, se produce un error.

Como sucede con la opción del compilador References, la opción del compilador EmbedInteropTypes usa el archivo de respuesta Csc.rsp, que hace referencia a ensamblados de .NET usados con frecuencia. Use la opción del compilador NoConfig si no quiere que el compilador utilice el archivo Csc.rsp.

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

Los tipos que tienen un parámetro genérico cuyo tipo se ha incrustado desde un ensamblado de interoperabilidad no se pueden usar si ese tipo pertenece a un ensamblado externo. Esta restricción no se aplica a las interfaces. Por ejemplo, considere la interfaz Range que se define en el ensamblado Microsoft.Office.Interop.Excel. Si una biblioteca inserta tipos de interoperabilidad desde el ensamblado Microsoft.Office.Interop.Excel y expone un método que devuelve un tipo genérico que tiene un parámetro cuyo tipo es la interfaz Range, ese método debe devolver una interfaz genérica, como se muestra en el ejemplo de código siguiente.

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

En el ejemplo siguiente, el código de cliente puede llamar al método que devuelve la interfaz genérica IList sin errores.

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