Rediriger les versions d'assemblage

Article
03/10/2025

Note

Cet article est spécifique à .NET Framework. Elle ne s’applique pas aux implémentations plus récentes de .NET, notamment .NET 6 et versions ultérieures.

Vous pouvez rediriger les références de liaison au moment de la compilation vers des assemblys .NET Framework, des assemblys tiers ou des assemblys de votre propre application. Vous pouvez rediriger votre application pour utiliser une autre version d’un assembly de plusieurs façons : via une stratégie d’éditeur, via un fichier de configuration d’application ou via le fichier de configuration de l’ordinateur. Cet article explique comment fonctionne la liaison d’assembly dans .NET Framework et comment vous pouvez la configurer.

Conseil

Cet article est spécifique aux applications .NET Framework. Pour plus d’informations sur le chargement d’assemblage dans .NET 5+ (et .NET Core), consultez Chargement des dépendances dans .NET.

Unification des assemblies et liaison par défaut

Les liaisons aux assemblys .NET Framework sont parfois redirigées via un processus appelé unification d’assembly. .NET Framework se compose d’une version du Common Language Runtime et d’environ deux douzaines d’assemblys .NET Framework qui composent la bibliothèque de types. Ces assemblys .NET Framework sont traités par le runtime en tant qu’unité unique. Par défaut, lorsqu’une application est lancée, toutes les références aux types du code exécutés par le runtime sont dirigées vers les assemblys .NET Framework qui ont le même numéro de version que le runtime chargé dans un processus. Les redirections qui se produisent avec ce modèle sont le comportement par défaut du runtime.

Par exemple, si votre application référence des types dans l’espace de noms System.XML et a été créée à l’aide de .NET Framework 4.5, elle contient des références statiques à l’assembly System.XML fourni avec le runtime version 4.5. Si vous souhaitez rediriger la référence de liaison pour pointer vers l’assembly System.XML fourni avec .NET Framework 4, vous pouvez placer des informations de redirection dans le fichier de configuration de l’application. Une redirection de liaison dans un fichier de configuration pour un assembly .NET Framework unifié annule l’unification de cet assembly.

En outre, vous pouvez souhaiter rediriger manuellement la liaison d’assembly pour les assemblys tiers s’il existe plusieurs versions disponibles.

Conseil

Si vous mettez à jour un package NuGet que votre application référence indirectement et commencez à voir de nouvelles erreurs telles que FileLoadException, MissingMethodException, TypeLoadExceptionou FileNotFoundException, vous devrez peut-être activer les redirections de liaison automatique ou ajouter manuellement une redirection de liaison. Cela est normal lors de la mise à jour des packages NuGet et est le résultat de la génération de certains packages sur une version antérieure d’une dépendance. L’extrait de fichier de configuration d’application suivant ajoute une redirection de liaison pour le package System.Memory :

<dependentAssembly>
   <assemblyIdentity name="System.Memory" publicKeyToken="cc7b13ffcd2ddd51" culture="neutral" />
   <bindingRedirect oldVersion="0.0.0.0-4.0.2.0" newVersion="4.0.2.0" />
</dependentAssembly>

Rediriger les versions à l’aide de la politique d’éditeur

Les fournisseurs d’assemblys peuvent diriger les applications vers une version plus récente d’un assembly en incluant un fichier de stratégie d’éditeur avec le nouvel assembly. Le fichier de stratégie d’éditeur, qui se trouve dans le Global Assembly Cache, contient les paramètres de redirection d’assembly.

Chaque version major.minor d’un assembly possède son propre fichier de stratégie d’éditeur. Par exemple, les redirections de la version 2.0.2.222 vers 2.0.3.000 et de la version 2.0.2.321 vers la version 2.0.3.000 entrent dans le même fichier, car elles sont associées à la version 2.0. Toutefois, une redirection de la version 3.0.0.999 vers la version 4.0.0.000 s'effectue dans le fichier pour la version 3.0.0.999. Chaque version majeure du .NET Framework a son propre fichier de stratégie d’éditeur.

Si un fichier de stratégie d’éditeur existe pour un assembly, le runtime vérifie ce fichier après avoir vérifié le manifeste et le fichier de configuration d’application de l’assembly. Les fournisseurs doivent utiliser les fichiers de stratégie d’éditeur uniquement quand le nouvel assembly offre une compatibilité descendante avec l’assembly en cours de redirection.

Vous pouvez contourner la stratégie d’éditeur pour votre application en spécifiant des paramètres dans le fichier de configuration de l’application, comme indiqué dans la section Contourner la stratégie d’éditeur.

Rediriger les versions au niveau de l’application

Il existe quelques techniques différentes pour modifier le comportement de liaison de votre application via le fichier de configuration de l’application : vous pouvez modifier manuellement le fichier, vous pouvez vous appuyer sur la redirection automatique de liaison, ou vous pouvez spécifier le comportement de liaison en contourner la stratégie d’éditeur.

Modifier manuellement le fichier de configuration de l’application

Vous pouvez modifier manuellement le fichier de configuration d’application pour résoudre les problèmes d’assembly. Par exemple, si un fournisseur publie une version plus récente d’un assembly que votre application utilise sans fournir de stratégie d’éditeur (car elle ne garantit pas la compatibilité descendante), vous pouvez diriger votre application pour utiliser la version plus récente de l’assembly en plaçant les informations de liaison d’assembly dans le fichier de configuration de votre application comme suit.

<dependentAssembly>
  <assemblyIdentity name="someAssembly"
    publicKeyToken="32ab4ba45e0a69a1"
    culture="en-us" />
  <bindingRedirect oldVersion="7.0.0.0" newVersion="8.0.0.0" />
</dependentAssembly>

Utilisation de la redirection de liaison automatique

Lorsque vous créez une application de bureau dans Visual Studio qui cible .NET Framework 4.5.1 ou une version ultérieure, l’application utilise la redirection de liaison automatique. Cela signifie que si deux composants référencent des versions différentes du même assembly nommé fort, le runtime ajoute automatiquement une redirection de liaison vers la version plus récente de l’assembly dans le fichier de configuration de l’application de sortie (app.config). Cette redirection annule l’unification de l'assemblage qui pourrait autrement avoir lieu. Le fichier source app.config n’est pas modifié. Par exemple, supposons que votre application référence directement un composant .NET Framework hors bande, mais utilise une bibliothèque tierce qui cible une version antérieure du même composant. Lorsque vous compilez l’application, le fichier de configuration de l’application de sortie est modifié pour contenir une redirection de liaison vers la version la plus récente du composant.

Si vous créez une application web, vous recevez un avertissement de build concernant le conflit de liaison, qui, à son tour, vous permet d’ajouter la redirection de liaison nécessaire au fichier de configuration web source.

Si vous ajoutez manuellement des redirections de liaison vers le fichier source app.config, au moment de la compilation, Visual Studio tente d’unifier les assemblys en fonction des redirections de liaison que vous avez ajoutées. Par exemple, supposons que vous insérez la redirection de liaison suivantes pour un assembly :

<bindingRedirect oldVersion="3.0.0.0" newVersion="2.0.0.0" />

Si un autre projet dans votre application fait référence à la version 1.0.0.0 du même assembly, la redirection de liaison automatique ajoute l’entrée suivante au fichier de sortie app.config afin que l’application soit unifiée sur la version 2.0.0.0 de cet assembly :

<bindingRedirect oldVersion="1.0.0.0" newVersion="2.0.0.0" />

Vous pouvez activer la redirection automatique de liaison si votre application cible des versions antérieures de .NET Framework. Vous pouvez remplacer ce comportement par défaut en fournissant des informations de redirection de liaison dans le fichier app.config pour n’importe quel assembly, ou en désactivant la fonctionnalité de redirection de liaison. Pour plus d’informations sur l’activation ou la désactivation de cette fonctionnalité, consultez Comment : activer et désactiver la redirection de liaison automatique.

Contourner la politique de l'éditeur

Vous pouvez remplacer la stratégie d’éditeur dans le fichier de configuration d’application si nécessaire. Par exemple, de nouvelles versions d’assemblys qui prétendent être rétrocompatibles peuvent toujours interrompre une application. Si vous souhaitez contourner la stratégie d’éditeur, ajoutez un élément <publisherPolicy> à l’élément <dependentAssembly> dans le fichier de configuration de l'application, puis définissez l'attribut apply sur no, ce qui remplace les paramètres yes précédents.

<publisherPolicy apply="no" />

Ignorez la politique de l'éditeur pour que votre application continue à fonctionner pour vos utilisateurs, mais veillez à signaler le problème au fournisseur de l'assemblage. Si un assembly a un fichier de stratégie d’éditeur, le fournisseur doit s’assurer que l’assembly est rétrocompatible et que les clients peuvent utiliser la nouvelle version autant que possible.

Rediriger les versions pour les tests, les plug-ins ou les bibliothèques utilisés par un autre composant

Pour les tests, vous devez générer un fichier .dll.config. La plupart des frameworks de test unitaire existants respectent ces fichiers lors du chargement des tests.

Les plug-ins peuvent honorer .dll.config fichiers, mais ils peuvent également ne pas le faire. Le seul mécanisme infaillible pour les redirections consiste à fournir bindingRedirects lorsque AppDomain est créé.

Vous pouvez essayer de résoudre ce problème avec AssemblyResolve gestionnaires d’événements, mais cela ne fonctionne pas, car ces gestionnaires sont uniquement appelés sur une charge ayant échoué. Si une charge d’assembly réussit, soit parce qu’elle a été chargée par un autre assembly ou l’hôte, soit qu’elle était présente dans le GAC, un gestionnaire de AssemblyResolve ne sera pas appelé.

Rediriger les versions au niveau de l’ordinateur

Il peut arriver qu’un administrateur d’ordinateurs souhaite que toutes les applications d’un ordinateur utilisent une version spécifique d’un assembly. Par exemple, une version spécifique peut corriger un trou de sécurité. Si un assembly est redirigé dans le fichier de configuration de l’ordinateur, appelé machine.config, toutes les applications sur cet ordinateur qui utilisent l’ancienne version sont dirigées pour utiliser la nouvelle version. Le fichier de configuration de l’ordinateur remplace le fichier de configuration de l’application et le fichier de stratégie de l’éditeur. Ce fichier machine.config se trouve à %windir%\Microsoft.NET\Framework[version]\config\machine.config pour les machines 32 bits ou %windir%\Microsoft.NET\Framework64[version]\config\machine.config pour les machines 64 bits.

Spécifier la liaison d’assemblage dans les fichiers de configuration

Vous utilisez le même format XML pour spécifier les redirections de liaison, qu’elles se trouvent dans le fichier de configuration de l’application, le fichier de configuration de l’ordinateur ou le fichier de stratégie d’éditeur. Pour rediriger une version d’assembly vers une autre, utilisez l’élément <bindingRedirect>. L’attribut oldVersion peut spécifier une version d’assembly unique ou une plage de versions. L’attribut newVersion doit spécifier une seule version. Par exemple, <bindingRedirect oldVersion="1.1.0.0-1.2.0.0" newVersion="2.0.0.0"/> spécifie que le runtime doit utiliser la version 2.0.0.0 au lieu des versions d’assembly comprises entre 1.1.0.0 et 1.2.0.0.

L’exemple de code suivant montre divers scénarios de redirection de liaison. L’exemple spécifie une redirection pour une plage de versions pour myAssemblyet une redirection de liaison unique pour mySecondAssembly. L’exemple spécifie également que le fichier de stratégie de l’éditeur ne remplace pas les redirections de liaison pour myThirdAssembly.

Pour lier un assembly, vous devez spécifier la chaîne « urn :schemas-microsoft-com :asm.v1 » avec l’attribut xmlns dans la balise <assemblyBinding>.

<configuration>
  <runtime>
    <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
      <dependentAssembly>
        <assemblyIdentity name="myAssembly"
          publicKeyToken="32ab4ba45e0a69a1"
          culture="en-us" />
        <!-- Assembly versions can be redirected in app,
          publisher policy, or machine configuration files. -->
        <bindingRedirect oldVersion="1.0.0.0-2.0.0.0" newVersion="3.0.0.0" />
      </dependentAssembly>
      <dependentAssembly>
        <assemblyIdentity name="mySecondAssembly"
          publicKeyToken="32ab4ba45e0a69a1"
          culture="en-us" />
             <bindingRedirect oldVersion="1.0.0.0" newVersion="2.0.0.0" />
      </dependentAssembly>
      <dependentAssembly>
      <assemblyIdentity name="myThirdAssembly"
        publicKeyToken="32ab4ba45e0a69a1"
        culture="en-us" />
        <!-- Publisher policy can be set only in the app
          configuration file. -->
        <publisherPolicy apply="no" />
      </dependentAssembly>
    </assemblyBinding>
  </runtime>
</configuration>

Limiter les liaisons d’assemblage à une version spécifique

Vous pouvez utiliser l’attribut appliesTo sur l’élément <assemblyBinding> dans un fichier de configuration d’application pour rediriger les références de liaison d’assembly vers une version spécifique de .NET Framework. Cet attribut facultatif utilise un numéro de version .NET Framework pour indiquer la version à laquelle elle s’applique. Si aucun attribut appliesTo n’est spécifié, l’élément <assemblyBinding> s’applique à toutes les versions de .NET Framework.

Par exemple, pour rediriger la liaison d’assembly pour un assembly .NET Framework 3.5, vous devez inclure le code XML suivant dans le fichier de configuration d’application.

<runtime>
  <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1"
    appliesTo="v3.5">
    <dependentAssembly>
      <!-- assembly information goes here -->
    </dependentAssembly>
  </assemblyBinding>
</runtime>

Vous devez entrer les informations de redirection dans l’ordre des versions. Par exemple, entrez les informations de redirection de liaison d’assembly pour les assemblys .NET Framework 3.5 suivies de celles pour les assemblys .NET Framework 4.5. Enfin, vous devez entrer les informations de redirection des liaisons d'assembly pour toutes les redirections d'assembly du .NET Framework qui n'utilisent pas d'attribut appliesTo et qui s'appliquent donc à toutes les versions du .NET Framework. S’il existe un conflit dans la redirection, la première instruction de redirection correspondante dans le fichier de configuration est utilisée.

Par exemple, pour rediriger une référence vers un assembly .NET Framework 3.5 et une autre référence à un assembly .NET Framework 4, utilisez le modèle indiqué dans le pseudocode suivant.

<assemblyBinding xmlns="..." appliesTo="v3.5 ">
  <!--.NET Framework version 3.5 redirects here -->
</assemblyBinding>

<assemblyBinding xmlns="..." appliesTo="v4.0.30319">
  <!--.NET Framework version 4.0 redirects here -->
</assemblyBinding>

<assemblyBinding xmlns="...">
  <!-- redirects meant for all versions of the runtime -->
</assemblyBinding>

Partager via