Umleiten von Assemblyversionen

Artikel
05/10/2023

Hinweis

Dieser Artikel gilt für das .NET Framework. Er gilt nicht für neuere Implementierungen von .NET, einschließlich .NET 6 und höherer Versionen.

Sie können Bindungsverweise zu .NET Framework-Assemblys oder Assemblys, die von Drittanbietern oder aus Ihrer eigenen App stammen, zum Zeitpunkt der Kompilierung umleiten. Es gibt mehrere Möglichkeiten, eine App so umzuleiten, dass sie eine andere Version einer Assembly verwendet: per Herausgeberrichtlinie, über eine App-Konfigurationsdatei oder mithilfe der Computerkonfigurationsdatei. In diesem Artikel wird erklärt, wie die Assemblybindung in .NET Framework funktioniert und wie diese konfiguriert werden kann.

Tipp

Dieser Artikel gilt für .NET Framework-Apps. Weitere Informationen zum Laden von Assemblys in .NET 5 und höher (und .NET Core) finden Sie unter Laden von Abhängigkeiten in .NET.

Assemblyvereinheitlichung und Standardbindung

Bindungen zu .NET Framework-Assemblys werden in einigen Fällen durch einen Prozess umgeleitet, der als Assemblyvereinheitlichungbezeichnet wird. .NET Framework besteht aus einer Version der Common Language Runtime und über zwanzig .NET Framework-Assemblys, die die Typbibliothek bilden. Diese .NET Framework-Assemblys werden von der Common Language Runtime als abgeschlossene Einheit behandelt. Standardmäßig werden beim Start einer Anwendung alle in von der Runtime ausgeführtem Code enthaltenen Verweise auf Typen zu .NET Framework-Assemblys umgeleitet, die die gleiche Versionsnummer wie die Runtime haben, die in einem Prozess geladen wird. Die bei diesem Modell auftretenden Umleitungen sind das Standardverhalten der Common Language Runtime.

Wenn zum Beispiel eine App, die unter Verwendung von .NET Framework 4.5 erstellt wurde, auf Typen im System.XML-Namespace verweist, enthält sie statische Verweise auf die System.XML-Assembly, die in der Version 4.5 der Runtime enthalten ist. Wenn Sie den Bindungsverweis so umleiten möchten, dass er auf die System.XML-Assembly aus .NET Framework 4 verweist, können Sie die Informationen zur Umleitung in die App-Konfigurationsdatei einfügen. Durch eine Bindungsumleitung in einer Konfigurationsdatei für eine vereinheitlichte .NET Framework-Assembly wird die Vereinheitlichung für diese Assembly abgebrochen.

Außerdem können Sie eine manuelle Umleitung von Assemblybindungen auch bei Assemblys von Drittanbietern vornehmen, wenn davon mehrere Versionen verfügbar sind.

Umleiten von Versionen mithilfe der Herausgeberrichtlinie

Anbieter von Assemblys können Apps zu einer neueren Version einer Assembly umleiten, indem sie der neuen Assembly eine Herausgeberrichtliniendatei hinzufügen. Die Herausgeberrichtliniendatei befindet sich im globalen Assemblycache und enthält Einstellungen für die Umleitung der Assembly.

Jede Version einer Assembly im Format major.minor verfügt über eine eigene Herausgeberrichtliniendatei. So werden zum Beispiel Umleitungen von der Version 2.0.2.222 zu 2.0.3.000 und der Version 2.0.2.321 zu 2.0.3.000 beide in der gleichen Datei eingetragen, da beide zu der gleichen Version 2.0 gehören. Eine Umleitung von Version 3.0.0.999 zu 4.0.0.000 müsste jedoch in der Datei für die Version 3.0.999 stehen. Jede Hauptversion des .NET Framework verfügt über eine eigene Herausgeberrichtliniendatei.

Wenn eine Herausgeberrichtliniendatei für eine Assembly vorhanden ist, wird diese nach Prüfung des Assemblymanifests und der App-Konfigurationsdatei von der Runtime überprüft. Anbieter sollten Herausgeberrichtlinien nur dann einsetzen, wenn die neue Assembly abwärts kompatibel zu der Assembly ist, die umgeleitet werden soll.

Sie können die Herausgeberrichtlinie bei Ihrer App umgehen, indem Sie in der App-Konfigurationsdatei Einstellungen angeben, wie im Abschnitt Umgehen der Herausgeberrichtlinieerläutert.

Umleiten von Versionen auf App-Ebene

Es gibt verschiedene Verfahren, um das Bindungsverhalten einer App per App-Konfigurationsdatei zu ändern: Sie können die Datei manuell bearbeiten, sich auf die automatische Bindungsumleitung verlassen oder das Bindungsverhalten durch Umgehung der Herausgeberrichtlinie selbst festlegen.

Manuelles Bearbeiten der App-Konfigurationsdatei

Sie können die App-Konfigurationsdatei manuell bearbeiten, um Assemblyprobleme aufzulösen. Wenn ein Anbieter zum Beispiel eine neuere Assemblyversion veröffentlicht, die von Ihrer App ohne Angabe einer Herausgeberrichtlinie verwendet wird, da diese keine Abwärtskompatibilität garantiert, können Sie die App auf die neuere Version der Assembly umleiten, indem Sie wie folgt Assemblybindungsinformationen in die Konfigurationsdatei eintragen.

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

Nutzen der automatische Bindungsumleitung

Wenn Sie eine Desktop-App in Visual Studio erstellen, die auf .NET Framework 4.5.1 oder höher ausgerichtet ist, verwendet die App die automatische Bindungsumleitung. Das bedeutet Folgendes: Wenn zwei Komponenten auf unterschiedliche Versionen der gleichen Assembly mit starkem Namen verweisen, fügt die Runtime automatisch eine Bindungsumleitung auf die neuere Version der Assembly in der app.config-Ausgabedatei hinzu. Diese Umleitung überschreibt die Assemblyvereinheitlichung, die sonst erfolgen würde. Die app.config-Quelldatei wird nicht geändert. Beispiel: Ihre App verweist direkt auf eine Out-of-Band-.NET Framework-Komponente, verwendet jedoch eine Bibliothek von einem Drittanbieter, die sich auf eine frühere Version der gleichen Komponente bezieht. Wenn Sie die App kompilieren, wird die app.config-Ausgabedatei so geändert, dass sie eine Umleitung zu der neueren Version der Komponente enthält. Beim Erstellen einer Web-App erhalten Sie eine Buildwarnung bezüglich des Bindungskonflikts, was Ihnen wiederum die Möglichkeit gibt, der web.config-Quelldatei die erforderliche Bindungsumleitung hinzuzufügen.

Wenn Sie der app.config-Quelldatei manuell Bindungsumleitungen hinzufügen, versucht Visual Studio beim Kompilieren, die Assemblys anhand der von Ihnen hinzugefügten Bindungsumleitungen zu vereinheitlichen. Wenn Sie zum Beispiel die folgende Bindungsumleitung für eine Assembly einfügen:

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

Wenn ein anderes Projekt in Ihrer App auf die Version 1.0.0.0 der gleichen Assembly verweist, fügt die automatische Bindungsumleitung den folgende Eintrag zur app.config-Ausgabedatei hinzu, damit die App auf die Version 2.0.0.0 dieser Assemblys vereinheitlicht wird:

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

Sie können die automatische Bindungsumleitung aktivieren, wenn Ihre App für frühere Versionen von .NET Framework ausgelegt ist. Dieses Standardverhalten können Sie außer Kraft setzen, indem Sie in der app.config-Datei für jede Assembly Informationen zur Bindungsumleitung angeben oder das Feature zur automatischen Bindungsumleitung deaktivieren. Weitere Informationen zum Aktivieren oder Deaktivieren dieses Features finden Sie unter Vorgehensweise: Aktivieren und Deaktivieren der automatischen Bindungsumleitung.

Umgehen der Herausgeberrichtlinie

Falls erforderlich, können Sie Herausgeberrichtlinien in der App-Konfigurationsdatei überschreiben. So können zum Beispiel neue Versionen von Assemblys, die als abwärts kompatibel gelten, eine Anwendung trotzdem lahmlegen. Wenn Sie die Herausgeberrichtlinie umgehen möchten, fügen Sie in der App-Konfigurationsdatei dem <dependentAssembly>-Element ein <publisherPolicy>-Element hinzu, und legen Sie das apply-Attribut auf no fest, damit mögliche vorherige yes-Einstellungen überschrieben werden.

<publisherPolicy apply="no" />

Durch das Umgehen der Herausgeberrichtlinie bleibt Ihre App zwar lauffähig, doch sollten Sie dieses Problem auf jeden Fall dem Anbieter der Assembly mitteilen. Wenn eine Assembly über eine Herausgeberrichtliniendatei verfügt, sollte der Anbieter sicherstellen, dass seine Assembly abwärts kompatibel ist und Clients die neue Version in vollem Umfang nutzen können.

Umleiten von Versionen auf Computerebene

In seltenen Fällen kann es vorkommen, dass der Administrator möchte, dass sämtliche Apps auf einem Computer eine bestimmte Version einer Assembly verwenden. Beispielsweise kann eine bestimmte Version eine Sicherheitslücke beheben. Wenn eine Assembly in der Konfigurationsdatei des Computers (machine.config) umgeleitet wird, werden alle auf diesem Computer installierten Apps, die bisher die alte Version verwendet haben, zur neuen Version umgeleitet. Die Konfigurationsdatei des Computers überschreibt die per App-Konfigurationsdatei und Herausgeberrichtliniendatei getroffenen Festlegungen. Die Datei machine.config befindet sich auf 32-Bit-Computern unter %windir%\Microsoft.NET\Framework[Version]\config\machine.config und auf 64-Bit-Computern unter %windir%\Microsoft.NET\Framework64[Version]\config\machine.config.

Angeben der Assemblybindung in Konfigurationsdateien

Verwenden Sie beim Festlegen von Bindungsumleitungen in sämtlichen Dateien das gleiche XML-Format, also in der App-Konfigurationsdatei, der Computer-Konfigurationsdatei oder der Herausgeberrichtliniendatei. Verwenden Sie zum Umleiten von einer Assemblyversion zu einer anderen das <bindingRedirect>-Element. Mit dem oldVersion -Attribut kann sowohl eine einzelne Assemblyversion als auch ein Bereich von Versionen angegeben werden. Mit dem newVersion -Attribut sollte nur eine einzige Version angegeben werden. Beispielsweise wird durch <bindingRedirect oldVersion="1.1.0.0-1.2.0.0" newVersion="2.0.0.0"/> angegeben, dass die Common Language Runtime die Version 2.0.0.0 statt der Assemblyversionen zwischen 1.1.0.0 und 1.2.0.0 verwenden soll.

Im folgenden Codebeispiel werden die unterschiedlichsten Szenarien von Bindungsumleitungen gezeigt. In diesem Beispiel wird für myAssemblyeine Umleitung für einen Bereich von Versionen und für mySecondAssemblyeine einzelne Bindungsumleitung angegeben. Außerdem wird festgelegt, dass die Herausgeberrichtliniendatei nicht die Bindungsumleitungen für myThirdAssemblyüberschreiben soll.

Zum Binden einer Assembly müssen Sie die Zeichenfolge „urn:schemas-microsoft-com:asm.v1“ mit dem xmlns-Attribut im <assemblyBinding>-Tag angeben.

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

Beschränken von Assemblybindungen auf eine bestimmte Version

Mithilfe des appliesTo-Attributs im <assemblyBinding>-Element einer App-Konfigurationsdatei können Sie Assemblybindungsverweise auf eine bestimmte Version von .NET Framework umleiten. Dieses optionale Attribut verwendet eine .NET Framework-Versionsnummer, um anzugeben, welche Version verwendet wird. Ohne Angabe eines appliesTo-Attributs gilt das <assemblyBinding>-Element für alle Versionen von .NET Framework.

Um zum Beispiel die Assemblybindung einer .NET Framework 3.5-Assembly umzuleiten, müssten Sie den folgenden XML-Code in die App-Konfigurationsdatei einfügen:

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

Die Informationen für Umleitungen sind in Reihenfolge der Versionen einzugeben. So geben Sie beispielsweise erst die Informationen zum Umleiten der Assemblybindung für .NET Framework 3.5-Assemblys und dann die für .NET Framework 4.5-Assemblys ein. Geben Sie zuletzt die Informationen zum Umleiten der Assemblybindung für alle .NET Framework-Assemblyumleitungen ein, bei denen nicht das appliesTo-Attribut verwendet wird und die daher für alle .NET Framework-Versionen gelten. Falls bei der Umleitung Konflikte auftreten, wird die erste passende Umleitungsanweisung in der Konfigurationsdatei verwendet.

Beispiel: Zum Umleiten eines Verweises auf eine .NET Framework 3.5-Assembly und eines anderen Verweises auf eine .NET Framework 4-Assembly müssten Sie nach dem folgenden Muster vorgehen:

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

Freigeben über