Options du compilateur C# qui spécifient les entrées

Les options suivantes contrôlent les entrées du compilateur. La nouvelle syntaxe MSBuild est affichée en gras. La syntaxe csc.exe plus ancienne est présentée en code style.

• References / -reference ou -references : métadonnées de référence du fichier ou des fichiers d’assembly spécifiés.
• AddModules-addmodule /  : ajoute un module (créé avec target:module sur cet assembly.)
• EmbedInteropTypes / -link : incorpore les métadonnées des fichiers d’assembly d’interopérabilité spécifiés.

Références

L’option References indique au compilateur d’importer les informations de type public du fichier spécifié dans le projet actuel, ce qui vous permet de référencer les métadonnées des fichiers d’assembly spécifiés.

<Reference Include="filename" />

filename est le nom d’un fichier contenant un manifeste d’assembly. Pour importer plusieurs fichiers, incluez un élément Reference pour chaque fichier. Vous pouvez définir un alias en tant qu’élément enfant de l’élément Reference :

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

Dans l’exemple précédent, LS est l’identificateur C# valide représentant un espace de noms racine qui contient tous les espaces de noms de l’assembly filename.dll. Les fichiers que vous importez doivent contenir un manifeste. Utilisez AdditionalLibPaths pour spécifier le répertoire dans lequel se trouvent une ou plusieurs références d’assembly. La rubrique AdditionalLibPaths décrit également les répertoires dans lesquels le compilateur recherche les assemblys. Pour que le compilateur reconnaisse un type dans un assembly, et non dans un module, il doit être forcé à résoudre le type, ce que vous pouvez faire en définissant une instance du type. Il existe d’autres moyens de résoudre les noms de types dans un assembly pour le compilateur : par exemple, si vous héritez d’un type dans un assembly, le nom du type est ensuite reconnu par le compilateur. Il est parfois nécessaire de référencer deux versions différentes du même composant dans un assembly. Pour ce faire, utilisez l’élément Aliases sur l’élément References de chaque fichier afin de distinguer les deux fichiers. Cet alias est utilisé comme qualificateur pour le nom du composant et se traduit par le composant dans l’un des fichiers.

Notes

Dans Visual Studio, utilisez la commande Ajouter une référence. Pour plus d’informations, consultez Guide pratique pour ajouter ou supprimer des références à l’aide du gestionnaire de références.

AddModules

Cette option ajoute à la compilation en cours un module créé à l’aide du commutateur <TargetType>module</TargetType>.

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

Où file, file2 sont des fichiers de sortie qui contiennent des métadonnées. Le fichier ne peut pas contenir de manifeste d’assembly. Pour importer plusieurs fichiers, séparez les noms des fichiers par une virgule ou un point-virgule. Tous les modules ajoutés avec AddModules doivent se trouver dans le même répertoire que le fichier de sortie au moment de l’exécution. Vous pouvez donc spécifier un module dans n’importe quel répertoire au moment de la compilation, mais le module doit se trouver dans le répertoire de l’application au moment de l’exécution. Si le module n’est pas dans le répertoire de l’application au moment de l’exécution, vous recevez une TypeLoadException. file ne peut pas contenir d’assembly. Par exemple, si le fichier de sortie a été créé avec l’option TargetType de module, ses métadonnées peuvent être importées avec AddModules.

Si le fichier de sortie a été créé avec une option TargetType autre que module, ses métadonnées ne peuvent pas être importées avec AddModules mais peuvent l’être avec l’option References.

EmbedInteropTypes

Fait que le compilateur rend disponible pour le projet en cours de compilation les informations de type COM des assemblys spécifiés.

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

Où file1;file2;file3 est une liste délimitée par des points-virgules de noms de fichiers d’assembly. Si le nom de fichier contient un espace, placez-le entre des guillemets. L’option EmbedInteropTypes vous permet de déployer une application dans laquelle des informations de type sont incorporées. L’application peut ensuite utiliser des types dans un assembly de runtime qui implémentent les informations de type incorporées sans nécessiter une référence à l’assembly de runtime. Si différentes versions de l’assembly de runtime sont publiées, l’application qui contient les informations de type incorporées peut fonctionner avec les différentes versions sans devoir être recompilée. Pour un exemple, consultez Procédure pas à pas : incorporation de types provenant d’assemblys managés.

L’option EmbedInteropTypes est particulièrement utile avec COM Interop. Vous pouvez incorporer des types COM afin que votre application ne nécessite plus un assembly PIA (Primary Interop Assembly) sur l’ordinateur cible. L’option EmbedInteropTypes indique au compilateur d’incorporer les informations de type COM provenant de l’assembly Interop référencé dans le code compilé résultant. Le type COM est identifié par la valeur du CLSID (GUID). Par conséquent, votre application peut s’exécuter sur un ordinateur cible où les mêmes types COM ont été installés avec les mêmes valeurs de CLSID. Les applications qui automatisent Microsoft Office sont un bon exemple. Étant donné que les applications comme Office gardent habituellement la même valeur de CLSID à travers différentes versions, votre application peut utiliser les types COM référencés dès lors que le .NET Framework 4 ou ultérieur est installé sur l’ordinateur cible, et que votre application utilise les méthodes, propriétés ou événements qui sont inclus dans les types COM référencés. L’option EmbedInteropTypes incorpore seulement les interfaces, les structures et les délégués. L’incorporation de classes COM n’est pas prise en charge.

Notes

Quand vous créez une instance d’un type COM incorporé dans votre code, vous devez créer l’instance à l’aide de l’interface appropriée. Une tentative de création d’une instance d’un type COM incorporé à l’aide de la coclasse provoque une erreur.

Comme l’option de compilateur References, l’option EmbedInteropTypes utilise le fichier réponse Csc.rsp, qui référence les assemblys .NET fréquemment utilisés. Utilisez l’option de compilateur NoConfig si vous ne voulez pas que le compilateur utilise le fichier Csc.rsp.

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

Vous ne pouvez pas utiliser des types qui ont un paramètre générique dont le type est incorporé depuis un assembly d’interopérabilité si ce type provient d’un assembly externe. Cette restriction ne s’applique pas aux interfaces. Prenons l’exemple de l’interface Range qui est définie dans l’assembly Microsoft.Office.Interop.Excel. Si une bibliothèque incorpore les types interop de l’assembly Microsoft.Office.Interop.Excel et expose une méthode qui retourne un type générique qui a un paramètre dont le type est l’interface Range, cette méthode doit retourner une interface générique, comme dans l’exemple de code suivant.

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

Dans l’exemple suivant, le code client peut appeler la méthode qui retourne l’interface générique IList sans erreur.

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