Assemblyversies omleiden

Artikel
03/05/2024

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 deze kan worden geconfigureerd.

Tip

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

Assembly-eenwording en standaardbinding

Bindingen met .NET Framework-assembly's worden soms omgeleid via een proces dat assembly-eenwording wordt genoemd. Het .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 standaard alle verwijzingen naar typen code die door de runtime worden uitgevoerd, 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 verzonden met .NET Framework 4, kunt u omleidingsgegevens 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.

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 majoor.secundaire 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 gaat echter naar het bestand voor versie 3.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 alleen uitgeversbeleidsbestanden gebruiken wanneer de nieuwe assembly achterwaarts compatibel is met de assembly die wordt omgeleid.

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

Versies omleiden 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 omleiding van bindingen of u kunt bindingsgedrag opgeven door het uitgeversbeleid te 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 vrijgeeft 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 onderdelen verwijzen naar verschillende versies van dezelfde sterk benoemde assembly, de runtime automatisch een bindingsomleiding toevoegt aan de nieuwere versie van de assembly in het bestand app-configuratie (app.config). Deze omleiding overschrijft de eenwording van de assembly die anders zou kunnen plaatsvinden. Het bronbestand app.config is 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. Op zijn beurt kunt u de benodigde bindingsomleiding toevoegen aan het bronwebconfiguratiebestand.

Als u tijdens het compileren handmatig bindingsomleidingen toevoegt aan het bron-app.config-bestand, probeert Visual Studio de assembly's te samenvoegen op basis van de bindingsomleidingen die u hebt toegevoegd. 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 bestand app.config voor elke assembly of door de functie bindingomleiding uit te schakelen. Zie How to: Enable and Disable Automatic Binding Redirection (Automatische bindingsomleiding in- en uitschakelen) voor 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 toepassen in op nee, waardoor eventuele eerdere ja-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.

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, genaamd machine.config, worden alle apps op die computer die de oude versie gebruiken, omgeleid om de nieuwe versie te gebruiken. Het configuratiebestand van de machine overschrijft het app-configuratiebestand en het uitgeversbeleidsbestand. Dit bestand machine.config 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.

Assemblybinding opgeven in 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. Als u de ene assemblyversie naar een andere wilt omleiden, gebruikt u het element bindingRedirect>.< Het kenmerk oldVersion kan één assemblyversie of een reeks versies opgeven. Het newVersion kenmerk moet één versie opgeven. Hiermee geeft u bijvoorbeeld <bindingRedirect oldVersion="1.1.0.0-1.2.0.0" newVersion="2.0.0.0"/> op 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 myAssembly, en éé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 xmlns-kenmerk in de< assemblyBinding-tag>.

<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 in het <assemblyBinding-element> in een app-configuratiebestand gebruiken om assemblybindingsverwijzingen 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 attribute appliesTo is opgegeven, is het <assemblyBinding-element> van toepassing op alle versies van het .NET Framework.

Als u bijvoorbeeld assemblybinding wilt omleiden voor een .NET Framework 3.5-assembly, moet u de volgende XML-code opnemen in uw app-configuratiebestand.

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

U moet omleidingsgegevens invoeren in de versievolgorde. Voer bijvoorbeeld assemblybindingsinformatie in voor .NET Framework 3.5-assembly's, gevolgd door .NET Framework 4.5-assembly's. Voer ten slotte informatie over assemblybindingsomleiding in voor een .NET Framework-assemblyomleiding die niet gebruikmaakt van het kenmerk appliesTo en dus van toepassing 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