Wersjonowanie
Biblioteka oprogramowania jest rzadko kompletna w wersji 1.0. Dobre biblioteki ewoluują wraz z upływem czasu, dodając funkcje, naprawiając błędy i poprawiając wydajność. Ważne jest, aby można było wydać nowe wersje biblioteki .NET bez przerywania istniejących użytkowników.
Zmiany powodujące niezgodność
Aby uzyskać informacje na temat obsługi zmian powodujących niezgodność między wersjami, zobacz Zmiany powodujące niezgodność.
Numery wersji
Biblioteka .NET ma wiele sposobów określania wersji. Te wersje są najważniejsze:
Wersja pakietu NuGet
Wersja pakietu NuGet jest wyświetlana na NuGet.org i w menedżerze pakietów NuGet programu Visual Studio i jest dodawana do kodu źródłowego, gdy pakiet jest używany. Wersja pakietu NuGet to numer wersji, który użytkownicy widzą i do którego się odnoszą, gdy mówią o wersji używanej biblioteki. Wersja pakietu NuGet jest używana przez NuGet i nie ma wpływu na zachowanie uruchomieniowe.
<PackageVersion>1.0.0-alpha1</PackageVersion>
Identyfikator pakietu NuGet połączony z wersją pakietu NuGet służy do identyfikowania pakietu w pakiecie NuGet. Na przykład Newtonsoft.Json + 11.0.2. Pakiet z sufiksem jest pakietem w wersji wstępnej i ma specjalne zachowanie, które sprawia, że idealnie nadaje się do testowania. Aby uzyskać więcej informacji, zobacz pakiety przedpremierowe .
Ponieważ wersja pakietu NuGet jest najbardziej widoczną wersją dla deweloperów, dobrze jest ją zaktualizować, używając wersjonowania semantycznego (SemVer). SemVer wskazuje znaczenie zmian między wydaniami i pomaga deweloperom podjąć świadomą decyzję podczas wybierania wersji do użycia. Na przykład przejście z 1.0 do 2.0 wskazuje, że istnieją potencjalnie istotne zmiany.
✔️ Rozważ użycie SemVer 2.0.0 do wersjonowania pakietu NuGet.
✔️ Użyj wersji pakietu NuGet w publicznej dokumentacji, ponieważ jest to numer wersji, który użytkownicy będą często widzieć.
✔️ Należy dołączyć sufiks wersji wstępnej podczas wydawania pakietu niestabilnego. (Aby uzyskać więcej informacji na temat oznaczania interfejsów API jako wersji zapoznawczej lub eksperymentalnej, zobacz Interfejsy API w wersji zapoznawczej).
Użytkownicy muszą wyrazić zgodę na uzyskanie pakietów wstępnych, aby zrozumieć, że pakiet nie jest kompletny.
Wersja zestawu
Wersja zestawu jest używana przez CLR podczas działania, aby wybrać wersję zestawu do załadowania. Wybranie zestawu przy użyciu przechowywania wersji dotyczy tylko zestawów o silnej nazwie.
<AssemblyVersion>1.0.0.0</AssemblyVersion>
Środowisko CLR platformy .NET Framework wymaga dokładnego dopasowania, aby załadować zestaw o mocnej nazwie. Na przykład Library1, Version=1.0.0.0 został skompilowany przy użyciu odwołania do Newtonsoft.Json, Version=11.0.0.0. Program .NET Framework załaduje tylko taką dokładną wersję 11.0.0.0. Aby załadować inną wersję w czasie wykonywania, należy dodać przekierowanie powiązania do pliku konfiguracji aplikacji .NET.
Silne nazewnictwo połączone z wersją zestawu umożliwia ścisłe ładowanie wersji zestawu. Mimo że silne nazewnictwo biblioteki ma wiele zalet, często prowadzi do wyjątków występujących w czasie wykonywania, spowodowanych brakiem możliwości odnalezienia zestawu, co wymaga przekierowań powiązań w za pomocą w app.config lub web.config, aby to naprawić. W programie .NET (Core) ładowanie zestawów jest bardziej zrelaksowane. Środowisko uruchomieniowe platformy .NET (Core) automatycznie ładuje zestawy z wyższą wersją podczas działania.
✔️ ROZWAŻ uwzględnienie tylko wersji głównej w wersji AssemblyVersion.
Na przykład biblioteka 1.0 i biblioteka 1.0.1 mają wartość AssemblyVersion
1.0.0.0, natomiast biblioteka 2.0 ma wartość AssemblyVersion2.0.0.0. Gdy wersja zestawu zmienia się rzadziej, zmniejsza przekierowania powiązań.
✔️ ROZWAŻ zachowanie głównego numeru wersji AssemblyVersion i wersji pakietu NuGet w zgodności.
Element AssemblyVersion jest uwzględniany w niektórych komunikatach informacyjnych wyświetlanych użytkownikowi, na przykład nazwy zestawu i kwalifikowanych nazw typów zestawu w komunikatach o wyjątkach. Utrzymanie relacji między wersjami zapewnia deweloperom więcej informacji o tym, której wersji używają.
❌ nie mają stałej wersji AssemblyVersion.
Podczas gdy niezmienna wersja AssemblyVersion pozwala uniknąć konieczności przekierowywania powiązań, oznacza to, że w Global Assembly Cache (GAC) można zainstalować tylko jedną wersję zestawu. Ponadto aplikacje odwołujące się do zestawu w GAC zostaną przerwane, jeśli inna aplikacja zaktualizuje zestaw GAC z powodu zmian powodujących niezgodność.
Wersja pliku zestawu
Wersja pliku w zestawie jest używana do wyświetlania wersji pliku w systemie Windows i nie ma wpływu na działanie w czasie wykonywania. Ustawienie tej wersji jest opcjonalne. Jest on widoczny w oknie dialogowym Właściwości pliku w Eksploratorze Windows:
<FileVersion>11.0.2.21924</FileVersion>
✔️ ROZWAŻ dołączenie numeru kompilacji w ramach ciągłej integracji jako wersji AssemblyFileVersion.
Na przykład kompilujesz wersję 1.0.0 projektu, a numer kompilacji z ciągłej integracji to 99, więc wartość AssemblyFileVersion to 1.0.0.99.
✔️ użyj formatu Major.Minor.Build.Revision dla wersji pliku.
Wersja pliku nigdy nie jest używana przez platformę .NET, system Windows oczekuje wersji pliku w formacie
Major.Minor.Build.Revision. Jeśli wersja nie jest zgodna z tym formatem, zostanie wyświetlone ostrzeżenie.
Wersja informacyjna kompilacji
Wersja informacyjna zestawu służy do rejestrowania dodatkowych informacji o wersji i nie ma wpływu na zachowanie środowiska uruchomieniowego. Ustawienie tej wersji jest opcjonalne. Jeśli używasz Source Link, wersja ta zostanie ustawiona podczas kompilacji z uwzględnieniem wersji pakietu NuGet oraz wersji kontroli źródła. Na przykład 1.0.0-beta1+204ff0a zawiera skrót zatwierdzenia kodu źródłowego, z którego został skompilowany zestaw. Aby uzyskać więcej informacji, zobacz Link źródłowy.
<InformationalVersion>The quick brown fox jumped over the lazy dog.</InformationalVersion>
Notatka
Starsze wersje programu Visual Studio zgłaszają ostrzeżenie kompilacji, jeśli ta wersja nie jest zgodna z formatem Major.Minor.Build.Revision. Ostrzeżenie można bezpiecznie zignorować.
❌ UNIKAJ samodzielnego ustawiania wersji informacyjnej zestawu.
Zezwalaj aplikacji SourceLink na automatyczne generowanie wersji zawierającej metadane narzędzia NuGet i kontroli źródła.
