Versionsverwaltung

Eine Softwarebibliothek ist in Version 1.0 selten vollständig. Gute Bibliotheken entwickeln sich im Laufe der Zeit, fügen Features hinzu, beheben Fehler und verbessern die Leistung. Es ist wichtig, dass Sie neue Versionen einer .NET-Bibliothek freigeben können, ohne vorhandene Benutzer zu unterbrechen.

Wichtige Änderungen

Weitere Informationen zur Verarbeitung von Breaking Changes zwischen den Versionen finden Sie unter Breaking Changes.

Versionsnummern

Eine .NET-Bibliothek verfügt über viele Möglichkeiten zum Angeben einer Version. Diese Versionen sind die wichtigsten:

• NuGet-Paketversion
• Assemblyversion
• Assemblydateiversion
• Assemblyinformationsversion

NuGet-Paketversion

Die NuGet-Paketversion wird auf NuGet.org und im Visual Studio NuGet-Paket-Manager angezeigt und beim Verwenden des Pakets dem Quellcode hinzugefügt. Die NuGet-Paketversion ist die Versionsnummer, die Benutzer häufig sehen, und sie beziehen sich darauf, wenn sie über die Version einer Bibliothek sprechen, die sie verwenden. Die NuGet-Paketversion wird von NuGet verwendet und hat keine Auswirkungen auf das Laufzeitverhalten.

<PackageVersion>1.0.0-alpha1</PackageVersion>

Der NuGet-Paketbezeichner in Kombination mit der NuGet-Paketversion wird verwendet, um ein Paket in NuGet zu identifizieren. Beispiel: Newtonsoft.Json + 11.0.2. Ein Paket mit einem Suffix ist ein Vorabversionspaket und verfügt über ein spezielles Verhalten, das es ideal zum Testen macht. Weitere Informationen finden Sie unter den Vorabversionspaketen .

Da die NuGet-Paketversion für Entwickler die sichtbarste Version ist, empfiehlt es sich, sie mithilfe semantischen Versionsverwaltung (SemVer)zu aktualisieren. SemVer gibt die Bedeutung von Änderungen zwischen Versionen an und hilft Entwicklern, bei der Auswahl der zu verwendenden Version eine fundierte Entscheidung zu treffen. Wenn Sie beispielsweise von 1.0 auf 2.0 wechseln, zeigt dies an, dass es möglicherweise Änderungen gibt, die den Prozess unterbrechen.

✔️ ERWÄGEN SIE die Verwendung von SemVer 2.0.0 zur Versionierung Ihres NuGet-Pakets.

✔️ Verwenden Sie die NuGet-Paketversion in der öffentlichen Dokumentation, da sie die Versionsnummer ist, die Benutzer häufig sehen.

✔️ Fügen Sie ein Prerelease-Suffix hinzu, wenn Sie ein nicht stabiles Paket veröffentlichen. (Weitere Informationen zum Markieren von APIs als Vorschau oder experimentell finden Sie unter Vorschau-APIs.)

Benutzer müssen sich dafür entscheiden, Vorabversionen von Paketen zu erhalten, damit sie verstehen, dass das Paket nicht abgeschlossen ist.

Assemblyversion

Die Assemblyversion ist das, was die CLR zur Laufzeit verwendet, um auszuwählen, welche Version einer Assembly geladen werden soll. Die Auswahl einer Assembly mit Versionsverwaltung gilt nur für Assemblys mit starkem Namen.

<AssemblyVersion>1.0.0.0</AssemblyVersion>

Die .NET Framework-CLR verlangt eine genaue Übereinstimmung, um eine Assembly mit einem starken Namen zu laden. Beispielsweise wurde Library1, Version=1.0.0.0 mit einem Verweis auf Newtonsoft.Json, Version=11.0.0.0kompiliert. .NET Framework lädt nur diese genaue Version 11.0.0.0. Um zur Laufzeit eine andere Version zu laden, muss eine Bindungsumleitung zur Konfigurationsdatei der .NET-Anwendung hinzugefügt werden.

Ein starker Name in Kombination mit der Assemblyversion ermöglicht das strikte Laden der Assemblyversion. Obwohl ein starker Name einer Bibliothek eine Reihe von Vorteilen hat, führt dies oft zu Laufzeit-ausnahmen, dass eine Assembly nicht gefunden werden kann und dass Bindungsumleitungen in app.config oder web.config korrigiert werden müssen. In .NET (Core) ist das Laden von Assemblys entspannter. Die .NET (Core) Runtime lädt Assemblys mit einer höheren Version zur Laufzeit automatisch.

✔️ ERWÄGEN Sie, nur eine Hauptversion in der AssemblyVersion anzugeben.

Beispielsweise verfügen Library 1.0 und Library 1.0.1 über eine AssemblyVersion von 1.0.0.0, während Library 2.0 assemblyVersion von 2.0.0.0hat. Wenn sich die Assemblyversion weniger häufig ändert, werden Bindungsumleitungen reduziert.

✔️ ERWÄGEN SIE, die Hauptversionsnummer der AssemblyVersion und die NuGet-Paketversion synchron zu halten.

Die Assemblyversion ist in einigen Informationsmeldungen enthalten, die dem Benutzer angezeigt werden, zum Beispiel der Assemblyname und Typnamen mit Assemblyqualifikation in Ausnahmemeldungen. Die Aufrechterhaltung einer Beziehung zwischen den Versionen bietet Entwicklern weitere Informationen darüber, welche Version sie verwenden.

❌ Verwenden Sie keine feste AssemblyVersion.

Während eine nicht geänderte AssemblyVersion die Notwendigkeit von Bindungsumleitungen vermeidet, bedeutet dies, dass nur eine einzelne Version der Assembly im globalen Assemblycache (GAC) installiert werden kann. Außerdem werden die Anwendungen, die auf die Assembly im GAC verweisen, nicht mehr funktionieren, wenn eine andere Anwendung die GAC-Assembly mit einschneidenden Änderungen aktualisiert.

Assemblydateiversion

Die Assemblydateiversion wird verwendet, um eine Dateiversion in Windows anzuzeigen und hat keine Auswirkungen auf das Laufzeitverhalten. Das Festlegen dieser Version ist optional. Sie ist im Dialogfeld "Dateieigenschaften" im Windows-Explorer sichtbar:

<FileVersion>11.0.2.21924</FileVersion>

✔️ Erwägen Sie, eine fortlaufenden Continuous Integration-Buildnummer als AssemblyFileVersion-Revision hinzuzufügen.

Sie erstellen beispielsweise Version 1.0.0 Ihres Projekts, und die Fortlaufende Integrationsbuildnummer ist 99, sodass Ihre AssemblyFileVersion 1.0.0.99 ist.

✔️ Verwenden Sie das Format Major.Minor.Build.Revision für die Dateiversion.

Während die Dateiversion nie von .NET verwendet wird, erwartet Windows, dass die Dateiversion im Major.Minor.Build.Revision Format enthalten ist. Eine Warnung wird ausgelöst, wenn die Version diesem Format nicht folgt.

Assemblyinformationsversion

Die Assemblyinformationsversion wird verwendet, um zusätzliche Versionsinformationen aufzuzeichnen und hat keine Auswirkungen auf das Laufzeitverhalten. Das Festlegen dieser Version ist optional. Wenn Sie den Quelllink verwenden, wird diese Version beim Build mit der NuGet-Paketversion plus einer Versionskontrollversion festgelegt. Beispielsweise enthält 1.0.0-beta1+204ff0a den Commit-Hash des Quellcodes, aus dem die Assembly erstellt wurde. Weitere Informationen finden Sie unter Quelllink.

<InformationalVersion>The quick brown fox jumped over the lazy dog.</InformationalVersion>

❌ Vermeiden Sie, die Assemblyinformationsversion selbst festzulegen.

Zulassen, dass SourceLink automatisch die Version generiert, die NuGet- und Quellcodeverwaltungsmetadaten enthält.