Assemblyversies doorverwijzen

Artikel
03/05/2025

Notitie

Dit artikel is specifiek voor .NET Framework. Dit geldt niet voor nieuwere implementaties van .NET, waaronder .NET 6 en nieuwere versies.

U kunt compileertijdbindingsverwijzingen omleiden naar .NET Framework-assembly's, assembly's van derden of de assembly's van uw eigen app. U kunt uw app op verschillende manieren omleiden om een andere versie van een assembly te gebruiken: via uitgeversbeleid, via een app-configuratiebestand of via het computerconfiguratiebestand. In dit artikel wordt beschreven hoe assemblybinding werkt in .NET Framework en hoe u deze kunt configureren.

Tip

Dit artikel is specifiek voor .NET Framework-apps. Zie Dependency loading in .NETvoor informatie over het laden van assembly's in .NET 5+ (en .NET Core).

Assemblage-eenwording en standaardbinding

Bindingen met .NET Framework-assemblies worden soms omgeleid via een proces genaamd assembly-unification. .NET Framework bestaat uit een versie van de algemene taalruntime en ongeveer twee dozijn .NET Framework-assembly's waaruit de typebibliotheek bestaat. Deze .NET Framework-assembly's worden door de runtime als één eenheid behandeld. Wanneer een app wordt gestart, worden alle verwijzingen naar typen code die door de runtime worden uitgevoerd, standaard omgeleid naar .NET Framework-assembly's met hetzelfde versienummer als de runtime die in een proces wordt geladen. De omleidingen die optreden met dit model, zijn het standaardgedrag voor de runtime.

Als uw app bijvoorbeeld verwijst naar typen in de System.XML naamruimte en is gebouwd met .NET Framework 4.5, bevat deze statische verwijzingen naar de System.XML-assembly die wordt geleverd met runtimeversie 4.5. Als u de bindingsverwijzing wilt omleiden naar de System.XML assembly die wordt geleverd met .NET Framework 4, kunt u omleidingsinformatie in het app-configuratiebestand plaatsen. Een bindingsomleiding in een configuratiebestand voor een geïntegreerde .NET Framework-assembly annuleert de eenwording voor die assembly.

Daarnaast kunt u de assemblybinding handmatig omleiden voor assembly's van derden als er meerdere versies beschikbaar zijn.

Tip

Als u een NuGet-pakket bijwerkt waarnaar uw toepassing indirect verwijst en nieuwe fouten ziet, zoals FileLoadException, MissingMethodException, TypeLoadExceptionof FileNotFoundException, moet u mogelijk automatische bindingsomleidingen inschakelen of handmatig een bindingsomleiding toevoegen. Dit is normaal bij het bijwerken van NuGet-pakketten en is het gevolg van sommige pakketten die zijn gebouwd op basis van een oudere versie van een afhankelijkheid. Met het volgende app-configuratiebestandsfragment wordt een bindingsomleiding toegevoegd voor het System.Memory-pakket:

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

Versies omleiden met behulp van uitgeversbeleid

Leveranciers van assembly's kunnen apps doorsturen naar een nieuwere versie van een assembly door een uitgeversbeleidsbestand met de nieuwe assembly op te slaan. Het uitgeversbeleidsbestand, dat zich in de algemene assemblycache bevindt, bevat instellingen voor assemblyomleiding.

Elke major.minor versie van een assembly heeft een eigen uitgeversbeleidsbestand. Bijvoorbeeld omleidingen van versie 2.0.2.222 naar 2.0.3.000 en van versie 2.0.2.321 naar versie 2.0.3.000 gaan beide naar hetzelfde bestand, omdat ze zijn gekoppeld aan versie 2.0. Een omleiding van versie 3.0.0.999 naar versie 4.0.0.000 wordt echter opgenomen in het bestand voor versie 3.0.0.999. Elke primaire versie van .NET Framework heeft een eigen uitgeversbeleidsbestand.

Als er een uitgeversbeleidsbestand bestaat voor een assembly, controleert de runtime dit bestand na het controleren van het manifest en het app-configuratiebestand van de assembly. Leveranciers moeten uitgeversbeleidsbestanden alleen gebruiken wanneer de nieuwe assembly achterwaarts compatibel is met de assembly die wordt omgeleid.

U kunt het uitgeversbeleid voor uw app overslaan door instellingen op te geven in het app-configuratiebestand, zoals beschreven in de sectie Publicatiebeleid overslaan.

Versies doorverwijzen op app-niveau

Er zijn enkele verschillende technieken voor het wijzigen van het bindingsgedrag voor uw app via het app-configuratiebestand: u kunt het bestand handmatig bewerken, u kunt vertrouwen op automatische bindingomleiding, of u kunt bindingsgedrag opgeven door uitgeverbeleidte omzeilen.

Het app-configuratiebestand handmatig bewerken

U kunt het configuratiebestand van de app handmatig bewerken om assemblyproblemen op te lossen. Als een leverancier bijvoorbeeld een nieuwere versie van een assembly publiceert die door uw app wordt gebruikt zonder een uitgeversbeleid op te geven (omdat deze geen achterwaartse compatibiliteit garanderen), kunt u uw app als volgt omsturen naar het gebruik van de nieuwere versie van de assembly door bindingsgegevens voor assembly's in het configuratiebestand van uw app te plaatsen.

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

Afhankelijk van automatische bindingsomleiding

Wanneer u een bureaublad-app maakt in Visual Studio die is gericht op .NET Framework 4.5.1 of een latere versie, gebruikt de app automatische bindingsomleiding. Dit betekent dat als twee componenten verwijzen naar verschillende versies van dezelfde sterk benoemde assembly, de runtime automatisch een binding-omleiding toevoegt aan de nieuwere versie van de assembly in het uitvoer-app-configuratiebestand (app.config). Deze omleiding neemt voorrang boven de assembly-unificatie die anders zou kunnen plaatsvinden. Het bronbestand app.config wordt niet gewijzigd. Stel dat uw app rechtstreeks verwijst naar een out-of-band .NET Framework-onderdeel, maar een bibliotheek van derden gebruikt die is gericht op een oudere versie van hetzelfde onderdeel. Wanneer u de app compileert, wordt het configuratiebestand van de uitvoer-app gewijzigd om een bindingsomleiding naar de nieuwere versie van het onderdeel te bevatten.

Als u een web-app maakt, ontvangt u een buildwaarschuwing met betrekking tot het bindingsconflict, waardoor u de optie krijgt om de benodigde binding redirect toe te voegen aan het bronwebconfiguratiebestand.

Als u tijdens het compileren handmatig bindingsomleidingen toevoegt aan het bron-app.config-bestand, probeert Visual Studio de assembly's samen te voegen op basis van de bindingsomleidingen die u hebt toegevoegd. Bijvoorbeeld, stel dat u de volgende bindingsomleiding voor een assembly invoegt:

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

Als een ander project in uw app verwijst naar versie 1.0.0.0 van dezelfde assembly, voegt automatische bindingsomleiding de volgende vermelding toe aan het uitvoerbestand app.config, zodat de app is geïntegreerd op versie 2.0.0.0 van deze assembly:

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

U kunt automatische bindingomleiding inschakelen als uw app is gericht op oudere versies van .NET Framework. U kunt dit standaardgedrag overschrijven door bindingsomleidingsgegevens op te geven in het app.config-bestand voor elke assembly of door de functie bindingomleiding uit te schakelen. Zie How to: Enable and Disable Automatic Binding Redirectionvoor meer informatie over het in- of uitschakelen van deze functie.

Uitgeversbeleid overslaan

U kunt het uitgeversbeleid zo nodig overschrijven in het app-configuratiebestand. Nieuwe versies van assembly's die claimen compatibel te zijn met eerdere versies, kunnen bijvoorbeeld nog steeds een app breken. Als u het uitgeversbeleid wilt omzeilen, voegt u een <publisherPolicy>-element toe aan het <afhankelijkEAssembly>-element in het app-configuratiebestand en stelt u het kenmerk apply in op no, waardoor eventuele eerdere yes-instellingen worden overschreven.

<publisherPolicy apply="no" />

Sla uitgeversbeleid over om uw app actief te houden voor uw gebruikers, maar zorg ervoor dat u het probleem aan de leverancier van de assembly rapporteert. Als een assembly een uitgeversbeleidsbestand heeft, moet de leverancier ervoor zorgen dat de assembly achterwaarts compatibel is en dat clients de nieuwe versie zoveel mogelijk kunnen gebruiken.

Versies doorverwijzen voor tests, invoegtoepassingen of bibliotheken die door een ander onderdeel worden gebruikt.

Voor tests moet u een .dll.config-bestand genereren. De meeste bestaande moduletestframeworks respecteren deze bestanden bij het laden van tests.

Invoegtoepassingen kunnen .dll.config bestanden respecteren, maar ze kunnen ook niet. Het enige betrouwbare mechanisme voor omleidingen is door bindingRedirects te verstrekken wanneer de AppDomain wordt gemaakt.

Mogelijk probeert u dit probleem op te lossen met AssemblyResolve-gebeurtenishandlers, maar dat werkt niet omdat deze handlers alleen worden aangeroepen bij een mislukte lading. Als een assembly laden slaagt, hetzij doordat deze is geladen door een andere assembly of de host, of aanwezig was in de GAC, zal er geen AssemblyResolve-handler worden aangeroepen.

Omleidingsversies op machineniveau

Er kunnen zeldzame gevallen zijn wanneer een computerbeheerder wil dat alle apps op een computer een specifieke versie van een assembly gebruiken. Een specifieke versie kan bijvoorbeeld een beveiligingsgat oplossen. Als een assembly wordt omgeleid in het configuratiebestand van de machine, machine.configgenoemd, worden alle apps op die computer die gebruikmaken van de oude versie omgeleid om de nieuwe versie te gebruiken. Het configuratiebestand van de machine overschrijft het app-configuratiebestand en het uitgeversbeleidsbestand. Dit machine.config bestand bevindt zich op %windir%\Microsoft.NET\Framework[version]\config\machine.config voor 32-bits machines of %windir%\Microsoft.NET\Framework64[version]\config\machine.config voor 64-bits machines.

Geef assembly-binding op in de configuratiebestanden

U gebruikt dezelfde XML-indeling om bindingsomleidingen op te geven, ongeacht of deze zich in het app-configuratiebestand, het configuratiebestand van de machine of het uitgeversbeleidsbestand bevindt. Gebruik het element <bindingRedirect> om de ene assemblyversie om te leiden naar een andere assemblyversie. Het kenmerk oldVersion kan één assemblyversie of een reeks versies opgeven. Het kenmerk newVersion moet één versie opgeven. <bindingRedirect oldVersion="1.1.0.0-1.2.0.0" newVersion="2.0.0.0"/> geeft bijvoorbeeld aan dat de runtime versie 2.0.0.0 moet gebruiken in plaats van de assemblyversies tussen 1.1.0.0 en 1.2.0.0.

In het volgende codevoorbeeld ziet u verschillende scenario's voor het omleiden van bindingen. In het voorbeeld wordt een omleiding opgegeven voor een reeks versies voor myAssemblyen één bindingsomleiding voor mySecondAssembly. In het voorbeeld wordt ook aangegeven dat het uitgeversbeleidsbestand de bindingsomleidingen voor myThirdAssemblyniet overschrijft.

Als u een assembly wilt binden, moet u de tekenreeks urn:schemas-microsoft-com:asm.v1 opgeven met het kenmerk xmlns in de tag <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>

Assemblybindingen beperken tot een specifieke versie

U kunt het kenmerk appliesTo op het element <assemblyBinding> in een app-configuratiebestand gebruiken om bindingverwijzingen voor assembly's om te leiden naar een specifieke versie van .NET Framework. Dit optionele kenmerk maakt gebruik van een .NET Framework-versienummer om aan te geven op welke versie het van toepassing is. Als er geen appliesTo kenmerk is opgegeven, is het element <assemblyBinding> van toepassing op alle versies van .NET Framework.

Als u bijvoorbeeld assemblybinding wilt omleiden voor een .NET Framework 3.5-assembly, neemt u de volgende XML-code op in het configuratiebestand van uw app.

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

U dient omleidingsgegevens in te voeren in de volgorde van de versies. Voer bijvoorbeeld assemblybindingsomleidingsinformatie in voor .NET Framework 3.5-assembly's en daarna .NET Framework 4.5-assembly's. Voer ten slotte assemblybindingsinformatie in voor elke .NET Framework-assemblyomleiding die niet gebruikmaakt van het kenmerk appliesTo en dus van toepassing is op alle versies van .NET Framework. Als er een conflict is in omleiding, wordt de eerste overeenkomende omleidingsinstructie in het configuratiebestand gebruikt.

Als u bijvoorbeeld één verwijzing naar een .NET Framework 3.5-assembly en een andere verwijzing naar een .NET Framework 4-assembly wilt omleiden, gebruikt u het patroon dat wordt weergegeven in de volgende pseudocode.

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

Delen via