Wersje

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, zapewniając dodatkową wartość dla każdej wersji 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 Istotne zmiany.

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 w NuGet.org, menedżerze pakietów NuGet programu Visual Studio i jest dodawana do kodu źródłowego, gdy pakiet jest używany. Wersja pakietu NuGet jest często widocznym numerem wersji, który użytkownicy będą odwoływać się do tej wersji, gdy mówią o używanej wersji biblioteki. Wersja pakietu NuGet jest używana przez pakiet NuGet i nie ma wpływu na zachowanie środowiska uruchomieniowego.

<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 wersji wstępnej.

Ponieważ wersja pakietu NuGet jest najbardziej widoczną wersją dla deweloperów, dobrym pomysłem jest zaktualizowanie go przy użyciu semantycznego przechowywania wersji (SemVer). SemVer wskazuje znaczenie zmian między wydaniem 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 powodujące niezgodność zmiany.

✔️ ROZWAŻ użycie programu SemVer 2.0.0 do wersji pakietu NuGet.

✔️ Użyj wersji pakietu NuGet w publicznej dokumentacji, ponieważ jest to numer wersji, który użytkownicy będą często widzieć.

✔️ Do dołączania sufiksu wersji wstępnej podczas wydawania niestabilnego pakietu.

Użytkownicy muszą wyrazić zgodę na uzyskanie pakietów w wersji wstępnej, aby zrozumieć, że pakiet nie został ukończony.

Wersja zestawu

Wersja zestawu jest używana przez clr w czasie wykonywania, 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>

ClR programu .NET Framework wymaga dokładnego dopasowania, aby załadować zestaw o silnej nazwie. Na przykład Library1, Version=1.0.0.0 został skompilowany przy użyciu odwołania do Newtonsoft.Json, Version=11.0.0.0elementu . 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 silna nazwa biblioteki ma wiele korzyści, często powoduje wyjątki czasu wykonywania, których nie można odnaleźć zestawu i wymagają przekierowań powiązań w app.config systemie lub web.config ich naprawienia. W programie .NET Core ładowanie zestawów jest bardziej zrelaksowany. Środowisko uruchomieniowe platformy .NET Core automatycznie ładuje zestawy z wyższą wersją w czasie wykonywania.

✔️ ROZWAŻ uwzględnienie tylko wersji głównej w wersji AssemblyVersion.

Na przykład biblioteka 1.0 i biblioteka 1.0.1 mają wartość AssemblyVersion , natomiast biblioteka 2.0 ma wartość AssemblyVersion 1.0.0.0.2.0.0.0 Gdy wersja zestawu zmienia się rzadziej, zmniejsza przekierowania powiązań.

✔️ ROZWAŻ zachowanie numeru wersji głównej wersji elementu AssemblyVersion i wersji pakietu NuGet w synchronizacji.

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. Obsługa relacji między wersjami zawiera więcej informacji dla deweloperów na temat używanej wersji.

❌ NIE MA stałej wersji assemblyVersion.

Podczas gdy zmiana elementu AssemblyVersion pozwala uniknąć konieczności przekierowywania powiązań, oznacza to, że w globalnej pamięci podręcznej zestawów 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 zestawu służy do wyświetlania wersji pliku w systemie Windows i nie ma wpływu na zachowanie 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 ciągłej integracji jako poprawki AssemblyFileVersion.

Na przykład kompilujesz wersję 1.0.0 projektu, a numer kompilacji ciągłej integracji to 99, więc element AssemblyFileVersion to 1.0.0.99.

✔️ Do użyj formatu Major.Minor.Build.Revision dla wersji pliku.

Chociaż wersja pliku nigdy nie jest używana przez platformę .NET, system Windows oczekuje, że wersja pliku będzie mieć Major.Minor.Build.Revision format. Jeśli wersja nie jest zgodna z tym formatem, zostanie wyświetlone ostrzeżenie.

Wersja informacyjna zestawu

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 linku źródłowego, ta wersja zostanie ustawiona na kompilacji z wersją pakietu NuGet i wersją kontroli źródła. Na przykład 1.0.0-beta1+204ff0a zawiera skrót zatwierdzenia kodu źródłowego, na podstawie 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>

Uwaga

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.

PoprzedniNastępny