Omdirigering av sammansättningsversioner

Artikel
03/06/2025

Not

Den här artikeln är specifik för .NET Framework. Det gäller inte för nyare implementeringar av .NET, inklusive .NET 6 och senare versioner.

Du kan omdirigera kompileringsbindningsreferenser till .NET Framework-sammansättningar, tredjepartssammansättningar eller din egen apps sammansättningar. Du kan omdirigera din app till att använda en annan version av en sammansättning på flera olika sätt: via utgivarprincip, via en appkonfigurationsfil eller via datorkonfigurationsfilen. I den här artikeln beskrivs hur sammansättningsbindning fungerar i .NET Framework och hur du kan konfigurera den.

Tips

Den här artikeln är specifik för .NET Framework-appar. Information om sammansättningsinläsning i .NET 5+ (och .NET Core) finns i Beroendeinläsning i .NET.

Sammansättningssammanslagning och standardbindning

Bindningar till .NET Framework-sammansättningar omdirigeras ibland via en process som kallas sammansättningssammanslagning. .NET Framework består av en version av den gemensamma språkkörningen och cirka två dussin .NET Framework-sammansättningar som utgör typbiblioteket. Dessa .NET Framework-sammansättningar behandlas av körtiden som en enda enhet. Som standard, när en app startas, dirigeras alla referenser till typer i kod som körs av runtime-miljön till .NET Framework-assemblys som har samma versionsnummer som runtime-miljön som läses in i en process. Omdirigeringarna som sker med den här modellen är standardbeteendet för körningen.

Om din app till exempel refererar till typer i System.XML namnområdet och skapades med hjälp av .NET Framework 4.5 innehåller den statiska referenser till den System.XML sammansättning som levereras med körningsversion 4.5. Om du vill omdirigera bindningsreferensen så att den pekar på den System.XML sammansättning som levereras med .NET Framework 4 kan du placera omdirigeringsinformation i appkonfigurationsfilen. En bindningsomdirigering i en konfigurationsfil för en enhetlig .NET Framework-sammansättning avbryter sammansättningens enande.

Dessutom kanske du vill omdirigera sammansättningsbindningen manuellt för sammansättningar från tredje part om det finns flera tillgängliga versioner.

Tips

Om du uppdaterar ett NuGet-paket som programmet refererar till indirekt och börjar se nya fel som FileLoadException, MissingMethodException, TypeLoadExceptioneller FileNotFoundExceptionkan du behöva aktivera automatiska bindningsomdirigeringar eller lägga till en bindningsomdirigering manuellt. Detta är normalt när du uppdaterar NuGet-paket och är ett resultat av att vissa paket skapas mot en äldre version av ett beroende. Följande appkonfigurationsfilutdrag lägger till en bindningsomdirigering för System.Memory-paketet:

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

Omdirigera versioner med hjälp av publiceringsprincip

Leverantörer av sammansättningar kan dirigera appar till en nyare version av en sammansättning genom att inkludera en utgivarprincipfil med den nya sammansättningen. Utgivarpolicyfilen, som finns i den globala samlingen, innehåller inställningar för omdirigering av assemblies.

Varje större.mindre version av en sammansättning har en egen principfil för utgivare. Omdirigeringar från version 2.0.2.222 till 2.0.3.000 och från version 2.0.2.321 till version 2.0.3.000 går båda till samma fil eftersom de är associerade med version 2.0. En omdirigering från version 3.0.0.999 till version 4.0.0.000 hamnar dock i filen för version 3.0.999. Varje huvudversion av .NET Framework har en egen principfil för utgivare.

Om det finns en utgivarprincipfil för en sammansättning kontrollerar körmiljön den här filen efter att ha kontrollerat sammansättningens manifest och appens konfigurationsfil. Leverantörer bör endast använda utgivarprincipfiler när den nya sammansättningen är bakåtkompatibel med sammansättningen som omdirigeras.

Du kan kringgå utgivarprincipen för din app genom att ange inställningar i appkonfigurationsfilen, enligt beskrivningen i avsnittet Kringgå utgivarprincip.

Versioner för omdirigering på appnivå

Det finns några olika metoder för att ändra bindningsbeteendet för din app via appkonfigurationsfilen: du kan redigera filen manuelltkan du förlita dig på automatisk omdirigering av bindningareller ange bindningsbeteende genom att kringgå utgivarprincipen.

Redigera appkonfigurationsfilen manuellt

Du kan redigera appkonfigurationsfilen manuellt för att lösa sammansättningsproblem. Om en leverantör till exempel släpper en nyare version av en sammansättning som appen använder utan att ange en utgivarprincip (eftersom de inte garanterar bakåtkompatibilitet) kan du dirigera appen att använda den nyare versionen av sammansättningen genom att placera information om sammansättningsbindning i appens konfigurationsfil på följande sätt.

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

Förlita dig på automatisk länkomdirigering

När du skapar en skrivbordsapp i Visual Studio som är avsedd för .NET Framework 4.5.1 eller senare använder appen automatisk omdirigering av bindningar. Det innebär att om två komponenter refererar till olika versioner av samma starka namngivna sammansättning lägger körningen automatiskt till en bindningsomdirigering till den nyare versionen av sammansättningen i utdataappens konfigurationsfil (app.config). Den här omdirigeringen åsidosätter den sammansättningssammanslagning som annars skulle kunna äga rum. Källfilen app.config ändras inte. Anta till exempel att din app direkt refererar till en out-of-band .NET Framework-komponent men använder ett bibliotek från tredje part som riktar sig till en äldre version av samma komponent. När du kompilerar appen ändras konfigurationsfilen för utdataappen så att den innehåller en bindningsomdirigering till den nyare versionen av komponenten.

Om du skapar en webbapp får du en byggvarning om bindningskonflikten, vilket i sin tur ger dig möjlighet att lägga till den nödvändiga bindningsomdirigeringen till källwebbkonfigurationsfilen.

Om du lägger till bindningsomdirigeringar manuellt till källfilen app.config försöker Visual Studio vid kompileringstillfället att förena sammansättningarna baserat på de bindningsomdirigeringar som du har lagt till. Anta till exempel att du infogar följande bindningsomdirigering för en sammansättning:

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

Om ett annat projekt i appen refererar till version 1.0.0.0 av samma sammansättning lägger automatisk bindningsomdirigering till följande post i utdatafilen app.config så att appen är enhetlig på version 2.0.0.0 av den här sammansättningen:

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

Du kan aktivera automatisk omdirigering av bindning om din app riktar sig till äldre versioner av .NET Framework. Du kan åsidosätta det här standardbeteendet genom att ange information om bindningsomdirigering i app.config-filen för alla sammansättningar eller genom att inaktivera funktionen för bindningsomdirigering. Information om hur du aktiverar eller inaktiverar den här funktionen finns i How to: Enable and Disable Automatic Binding Redirection.

Kringgå utgivarens policy

Du kan åsidosätta utgivarprincipen i appkonfigurationsfilen om det behövs. Till exempel kan nya versioner av sammansättningar som påstår sig vara bakåtkompatibla fortfarande bryta en app. Om du vill kringgå utgivarprincipen lägger du till ett <publisherPolicy->-element i <beroendeAssembly->-elementet i appkonfigurationsfilen och anger attributet apply till no, som åsidosätter eventuella tidigare yes inställningar.

<publisherPolicy apply="no" />

Kringgå utgivarens princip för att hålla appen igång för användarna, men se till att du rapporterar problemet till sammansättningsleverantören. Om en sammansättning har en utgivarprincipfil bör leverantören se till att sammansättningen är bakåtkompatibel och att klienterna kan använda den nya versionen så mycket som möjligt.

Omdirigeringsversioner för tester, plugin-program eller bibliotek som används av en annan komponent

För tester bör du generera en .dll.config fil. De flesta befintliga enhetstestramverk respekterar dessa filer vid inläsning av tester.

Plugin-program kan hedra .dll.config filer, men de kanske inte heller. Den enda säkra mekanismen för omdirigeringar är att tillhandahålla bindingRedirects när AppDomain skapas.

Du kan försöka lösa det här problemet med AssemblyResolve händelsehanterare, men det fungerar inte eftersom dessa hanterare bara anropas vid en misslyckad inläsning. Om inladdningen av en sammansättning lyckas, antingen för att den laddades av en annan sammansättning eller av värdprogrammet, eller om den redan fanns i GAC, anropas inte en AssemblyResolve-hanterare.

Omdirigeringsversioner på datornivå

Det kan finnas sällsynta fall när en datoradministratör vill att alla appar på en dator ska använda en viss version av en sammansättning. En specifik version kan till exempel åtgärda ett säkerhetshål. Om en sammansättning omdirigeras i datorns konfigurationsfil, som kallas machine.config, dirigeras alla appar på den datorn som använder den gamla versionen till att använda den nya versionen. Datorkonfigurationsfilen åsidosätter appkonfigurationsfilen och utgivarens principfil. Den här machine.config filen finns på %windir%\Microsoft.NET\Framework[version]\config\machine.config för 32-bitarsdatorer eller %windir%\Microsoft.NET\Framework64[version]\config\machine.config för 64-bitarsdatorer.

Ange sammansättningsbindning i konfigurationsfiler

Du använder samma XML-format för att ange bindningsomdirigeringar oavsett om det finns i appkonfigurationsfilen, datorkonfigurationsfilen eller utgivarens principfil. Om du vill omdirigera en sammansättningsversion till en annan använder du elementet <bindingRedirect>. Attributet oldVersion kan ange en enskild sammansättningsversion eller ett intervall med versioner. Attributet newVersion ska ange en enskild version. Till exempel anger <bindingRedirect oldVersion="1.1.0.0-1.2.0.0" newVersion="2.0.0.0"/> att körningen ska använda version 2.0.0.0 i stället för sammansättningsversionerna mellan 1.1.0.0 och 1.2.0.0.

I följande kodexempel visas en mängd olika scenarier för bindningsomdirigering. Exemplet anger en omdirigering för ett intervall med versioner för myAssemblyoch en enda bindningsomdirigering för mySecondAssembly. Exemplet anger också att utgivarprincipfilen inte åsidosätter bindningsomdirigeringarna för myThirdAssembly.

Om du vill binda en sammansättning måste du ange strängen "urn:schemas-microsoft-com:asm.v1" med attributet xmlns i taggen <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>

Begränsa sammansättningsbindningar till en viss version

Du kan använda attributet appliesTo på <assemblyBinding>-elementet i en appkonfigurationsfil för att omdirigera sammansättningsbindningsreferenser till en viss version av .NET Framework. Det här valfria attributet använder ett .NET Framework-versionsnummer för att ange vilken version det gäller för. Om inget appliesTo attribut anges gäller elementet <assemblyBinding> för alla versioner av .NET Framework.

Om du till exempel vill omdirigera sammansättningsbindning för en .NET Framework 3.5-sammansättning skulle du inkludera följande XML-kod i appkonfigurationsfilen.

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

Du bör ange omdirigeringsinformation i versionsordning. Ange till exempel information om omdirigering av sammansättningsbindningar för .NET Framework 3.5-sammansättningar följt av .NET Framework 4.5-sammansättningar. Ange slutligen information om omdirigering av sammansättningsbindning för alla .NET Framework-sammansättningsomdirigeringar som inte använder attributet appliesTo och därför gäller för alla versioner av .NET Framework. Om en omdirigeringskonflikt uppstår används den första matchande omdirigeringsinstruktionen i konfigurationsfilen.

Om du till exempel vill omdirigera en referens till en .NET Framework 3.5-sammansättning och en annan referens till en .NET Framework 4-sammansättning använder du mönstret som visas i följande pseudokod.

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

Dela via