Partager via

Assemblies de référence

Les assemblys de référence sont un type spécial d’assembly qui contient uniquement la quantité minimale de métadonnées requise pour représenter l’aire d’API publique de la bibliothèque. Ils incluent des déclarations pour tous les membres qui sont significatifs lors du référencement d’un assembly dans les outils de génération, mais excluent toutes les implémentations de membres et déclarations de membres privés qui n’ont aucun impact observable sur leur contrat d’API. En revanche, les assemblys standard sont appelés assemblys d’implémentation.

Les assemblys de référence ne peuvent pas être chargés pour l’exécution, mais ils peuvent être passés en tant qu’entrée du compilateur de la même façon que les assemblys d’implémentation. Les assemblys de référence sont généralement distribués avec le Kit de développement logiciel (SDK) d’une plateforme ou d’une bibliothèque particulière.

L’utilisation d’un assembly de référence permet aux développeurs de créer des programmes qui ciblent une version de bibliothèque spécifique sans avoir l’assembly d’implémentation complet pour cette version. Supposons que vous disposez uniquement de la dernière version de certaines bibliothèques sur votre ordinateur, mais que vous souhaitez créer un programme qui cible une version antérieure de cette bibliothèque. Si vous compilez directement sur l’assembly d’implémentation, vous pouvez utiliser par inadvertance des membres d’API qui ne sont pas disponibles dans la version antérieure. Vous ne trouverez cette erreur que lors du test du programme sur l’ordinateur cible. Si vous compilez sur l’assembly de référence pour la version antérieure, vous obtenez immédiatement une erreur au moment de la compilation.

Un assembly de référence peut également représenter un contrat, autrement dit, un ensemble d’API qui ne correspondent pas à l’assembly d’implémentation concret. Ces assemblys de référence, appelés assemblys de contrat, peuvent être utilisés pour cibler plusieurs plateformes qui prennent en charge le même ensemble d’API. Par exemple, .NET Standard fournit l’assembly de contrat, netstandard.dll, qui représente l’ensemble d’API communes partagées entre différentes plateformes .NET. Les implémentations de ces API sont contenues dans différents assemblys sur différentes plateformes, telles que mscorlib.dll sur .NET Framework ou System.Private.CoreLib.dll sur .NET Core. Une bibliothèque qui cible .NET Standard peut s’exécuter sur toutes les plateformes qui prennent en charge .NET Standard.

Utilisation d’assemblys de référence

Pour utiliser certaines API de votre projet, vous devez ajouter des références à leurs assemblys. Vous pouvez ajouter des références à des assemblys d’implémentation ou à des assemblys de référence. Il est recommandé d’utiliser des assemblys de référence chaque fois qu’ils sont disponibles. Cela garantit que vous utilisez uniquement les membres d’API pris en charge dans la version cible, destinés à être utilisés par les concepteurs d’API. L’utilisation de l’assembly de référence garantit que vous ne prenez pas de dépendance sur les détails de l’implémentation.

Les assemblys de référence pour les bibliothèques .NET Framework sont distribués avec des packs de ciblage. Vous pouvez les obtenir en téléchargeant un programme d’installation autonome ou en sélectionnant un composant dans Visual Studio Installer. Pour plus d’informations, consultez Installer le .NET Framework pour les développeurs. Pour .NET Core et .NET Standard, les assemblys de référence sont automatiquement téléchargés si nécessaire (via NuGet) et référencés. Pour .NET Core 3.0 et versions ultérieures, les assemblys de référence pour l’infrastructure principale se trouvent dans le package Microsoft.NETCore.App.Ref (le package Microsoft.NETCore.App est utilisé à la place pour les versions antérieures à la version 3.0).

Lorsque vous ajoutez des références à des assemblys .NET Framework dans Visual Studio à l’aide de la boîte de dialogue Ajouter une référence , vous sélectionnez un assembly dans la liste et Visual Studio recherche automatiquement des assemblys de référence qui correspondent à la version du framework cible sélectionnée dans votre projet. La même chose s’applique à l’ajout de références directement dans le projet MSBuild à l’aide de l’élément de projet Référence : vous devez uniquement spécifier le nom de l’assembly, et non le chemin d’accès complet du fichier. Lorsque vous ajoutez des références à ces assemblys dans la ligne de commande à l’aide de l’option -reference du compilateur (en C# et en Visual Basic) ou à l’aide de la Compilation.AddReferences méthode de l’API Roslyn, vous devez spécifier manuellement les fichiers d’assembly de référence pour la version correcte de la plateforme cible. Les fichiers d’assembly de référence .NET Framework se trouvent dans le %ProgramFiles(x86)%\Reference Assemblys\Microsoft\Framework\. Répertoire NETFramework . Pour .NET Core, vous pouvez forcer l’opération de publication à copier des assemblys de référence pour votre plateforme cible dans le sous-répertoire publish/refs de votre répertoire de sortie en définissant la propriété truedu PreserveCompilationContext projet sur . Vous pouvez ensuite transmettre ces fichiers d’assembly de référence au compilateur. L’utilisation DependencyContext à partir du package Microsoft.Extensions.DependencyModel peut vous aider à localiser leurs chemins d’accès.

Étant donné qu’ils ne contiennent aucune implémentation, les assemblys de référence ne peuvent pas être chargés pour l’exécution. Essayer de le faire aboutit à un System.BadImageFormatException. Si vous souhaitez examiner le contenu d’un assembly de référence, vous pouvez le charger dans le contexte de réflexion uniquement dans .NET Framework (à l’aide MetadataLoadContext de la Assembly.ReflectionOnlyLoad méthode) ou dans .NET Framework et .NET Framework.

Génération d’assemblys de référence

La génération d’assemblys de référence pour vos bibliothèques peut être utile lorsque vos consommateurs de bibliothèque doivent créer leurs programmes sur de nombreuses versions différentes de la bibliothèque. La distribution d’assemblys d’implémentation pour toutes ces versions peut être impraticable en raison de leur grande taille. Les assemblys de référence sont plus petits en taille et les distribuent dans le cadre du SDK de votre bibliothèque réduit la taille de téléchargement et enregistre l’espace disque.

Les IDEs et les outils de génération peuvent également tirer parti des assemblys de référence pour réduire les temps de génération en cas de solutions volumineuses composées de plusieurs bibliothèques de classes. En règle générale, dans les scénarios de génération incrémentielle, un projet est reconstruit lorsque l’un de ses fichiers d’entrée est modifié, y compris les assemblys dont il dépend. L’assembly d’implémentation change chaque fois que le programmeur modifie l’implémentation d’un membre. L’assembly de référence change uniquement lorsque son API publique est affectée. Par conséquent, l’utilisation de l’assembly de référence en tant que fichier d’entrée au lieu de l’assembly d’implémentation permet d’ignorer la build du projet dépendant dans certains cas.

Vous pouvez générer des assemblys de référence :

Si vous souhaitez distribuer des assemblys de référence avec des packages NuGet, vous devez les inclure dans le sous-répertoire ref\ sous le répertoire de package au lieu du sous-répertoire lib\ utilisé pour les assemblys d’implémentation.

Structure des assemblys de référence

Les assemblys de référence sont une extension du concept associé, des assemblys de métadonnées uniquement. Les assemblys de métadonnées uniquement ont leurs corps de méthode remplacés par un seul throw null corps, mais incluent tous les membres à l’exception des types anonymes. La raison d’utiliser throw null des corps (par opposition à aucun corps) est de sorte que PEVerify puisse s’exécuter et passer (validant ainsi l’exhaustivité des métadonnées).

Les assemblys de référence suppriment davantage les métadonnées (membres privés) des assemblys de métadonnées uniquement :

  • Un assembly de référence contient uniquement des références pour ce dont il a besoin dans l’aire d’API. L’assembly réel peut avoir des références supplémentaires liées à des implémentations spécifiques. Par exemple, l’assembly de référence pour class C { private void M() { dynamic d = 1; ... } } lequel il ne fait référence à aucun type requis pour dynamic.
  • Les membres de fonction privée (méthodes, propriétés et événements) sont supprimés dans les cas où leur suppression n’a pas d’impact sur la compilation. S’il n’existe aucun attribut InternalsVisibleTo , les membres de la fonction interne sont également supprimés.

Les métadonnées des assemblys de référence continuent de conserver les informations suivantes :

  • Tous les types, y compris les types privés et imbriqués.
  • Tous les attributs, même internes.
  • Toutes les méthodes virtuelles.
  • Implémentations d’interface explicites.
  • Implémentation explicite des propriétés et des événements, car leurs accesseurs sont virtuels.
  • Tous les champs de structures.

Les assemblys de référence incluent un attribut ReferenceAssembly au niveau de l’assembly. Cet attribut peut être spécifié dans la source ; le compilateur n’a pas besoin de le synthétiser. En raison de cet attribut, les runtimes refusent de charger des assemblys de référence pour l’exécution (mais ils peuvent être chargés en mode réflexion uniquement).

Les détails exacts de la structure d’assembly de référence dépendent de la version du compilateur. Les versions plus récentes peuvent choisir d’exclure davantage de métadonnées si elles sont déterminées comme n’affectant pas l’aire d’API publique.

Remarque

Les informations de cette section s’appliquent uniquement aux assemblys de référence générés par les compilateurs Roslyn à partir de C# version 7.1 ou Visual Basic version 15.3. La structure des assemblys de référence pour les bibliothèques .NET Framework et .NET Core peut différer dans certains détails, car ils utilisent leur propre mécanisme de génération d’assemblys de référence. Par exemple, ils peuvent avoir des corps de méthode totalement vides au lieu du throw null corps. Mais le principe général s’applique toujours : ils n’ont pas d’implémentations de méthode utilisables et contiennent des métadonnées uniquement pour les membres ayant un impact observable du point de vue de l’API publique.

Voir aussi