Udostępnij za pośrednictwem

Wybierz wersję platformy .NET do użycia

  • Artykuł

W tym artykule opisano zasady używane przez narzędzia platformy .NET, zestaw SDK i środowisko uruchomieniowe do wybierania wersji. Te zasady zapewniają równowagę między uruchomionymi aplikacjami przy użyciu określonych wersji i ułatwiają uaktualnianie maszyn deweloperskich i użytkowników końcowych. Te zasady umożliwiają:

  • Łatwe i wydajne wdrażanie platformy .NET, w tym aktualizacje zabezpieczeń i niezawodności.
  • Użyj najnowszych narzędzi i poleceń niezależnych od docelowego środowiska uruchomieniowego.

Następuje wybór wersji:

Pozostała część tego dokumentu analizuje te cztery scenariusze.

Zestaw SDK używa najnowszej zainstalowanej wersji

Polecenia zestawu SDK obejmują dotnet new i dotnet run. Interfejs .NET CLI musi wybrać wersję SDK dla każdego polecenia dotnet. Domyślnie używa najnowszego zestawu SDK zainstalowanego na maszynie, nawet jeśli:

  • Projekt jest przeznaczony dla starszej wersji środowiska uruchomieniowego platformy .NET.
  • Najnowsza wersja zestawu .NET SDK to wersja zapoznawcza.

Korzystając z najnowszych funkcji i ulepszeń zestawu SDK, można korzystać z wcześniejszych wersji środowiska uruchomieniowego platformy .NET. Różne wersje środowiska uruchomieniowego platformy .NET można kierować przy użyciu tych samych narzędzi zestawu SDK.

W niektórych okolicznościach może być konieczne użycie określonej wersji zestawu SDK. Określasz tę wersję w pliku global.json.

global.json można umieścić w dowolnym miejscu w hierarchii plików. Kontrolujesz, do których projektów dane global.json mają zastosowanie, w zależności od ich lokalizacji w systemie plików. Interfejs wiersza polecenia platformy .NET wyszukuje plik global.json iteracyjnie nawigując po ścieżce w górę z bieżącego katalogu roboczego (który nie musi być taki sam jak katalog projektu). Pierwszy znaleziony plik global.json określa używaną wersję. Jeśli ta wersja zestawu SDK jest zainstalowana, używana jest ta wersja. Jeśli zestaw SDK określony w global.json nie zostanie znaleziony, .NET CLI używa pasujących reguł do wybrania zgodnego zestawu SDK, lub operacja kończy się niepowodzeniem, jeśli żaden nie zostanie znaleziony.

W poniższym przykładzie przedstawiono składnię global.json:

{
  "sdk": {
    "version": "5.0.0"
  }
}

Proces wybierania wersji zestawu SDK to:

  1. dotnet wyszukuje plik global.json iteracyjnie odwracając ścieżkę w górę od bieżącego katalogu roboczego.
  2. dotnet używa zestawu SDK określonego w pierwszym napotkanym global.json.
  3. dotnet używa najnowszego zainstalowanego zestawu SDK, jeśli nie znaleziono global.json.

Aby uzyskać więcej informacji na temat wyboru wersji zestawu SDK, zobacz sekcje Matching rules i rollForward w artykule global.json overview (Omówienie).

Aktualizowanie wersji zestawu SDK

Ważne jest regularne aktualizowanie do najnowszej wersji zestawu SDK w celu wdrożenia najnowszych funkcji, ulepszeń wydajności i poprawek błędów. Aby łatwo sprawdzić dostępność aktualizacji zestawu SDK, użyj polecenia dotnet sdk check. Ponadto, jeśli wybierzesz określoną wersję przy użyciu ,global.json,, rozważ narzędzie takie jak Dependabot, aby automatycznie zaktualizować ustaloną wersję zestawu SDK, gdy nowe wersje staną się dostępne.

Identyfikatory docelowych środowisk uruchomieniowych definiują interfejsy API czasu kompilacji

Projekt kompilujesz względem interfejsów API zdefiniowanych w moniker platformy docelowej (TFM). W pliku projektu należy określić platformę docelową. Ustaw element TargetFramework w pliku projektu, jak pokazano w poniższym przykładzie:

<TargetFramework>net8.0</TargetFramework>

Projekt można skompilować na wielu serwerach TFM. Ustawianie wielu platform docelowych jest bardziej powszechne w przypadku bibliotek, ale można je również wykonywać za pomocą aplikacji. Należy określić właściwość TargetFrameworks (liczba mnoga TargetFramework). Docelowe ramy są oddzielone średnikami, jak pokazano w poniższym przykładzie:

<TargetFrameworks>net8.0;net47</TargetFrameworks>

Dany zestaw SDK obsługuje stały zestaw struktur, ograniczony do docelowej struktury środowiska uruchomieniowego, z który jest dostarczany. Na przykład zestaw .NET 8 SDK zawiera środowisko uruchomieniowe platformy .NET 8, które jest implementacją platformy docelowej net8.0. Zestaw SDK platformy .NET 8 obsługuje net7.0, net6.0i net5.0, ale nie net9.0 (lub nowsze). Instalujesz pakiet .NET 9 SDK do tworzenia dla net9.0.

.NET Standard

.NET Standard to sposób na ukierunkowanie powierzchni interfejsu API współużytkowanego przez różne implementacje platformy .NET. Począwszy od wydania .NET 5, który sam w sobie jest standardem API, .NET Standard ma niewielkie znaczenie, z wyjątkiem jednego scenariusza: .NET Standard jest przydatny, gdy chcesz celować zarówno w .NET, jak i .NET Framework. Platforma .NET 5 implementuje wszystkie wersje platformy .NET Standard.

Aby uzyskać więcej informacji, zobacz .NET 5 i .NET Standard.

Wdrażanie aplikacji zależnych od platformy

Po uruchomieniu aplikacji ze źródła za pomocą dotnet run, z wdrożenia zależnego od platformy z dotnet myapp.dlllub z pliku wykonywalnego zależnego od platformy z myapp.exe, plik wykonywalny dotnet działa jako host dla aplikacji.

Host wybiera najnowszą wersję poprawki zainstalowaną na maszynie. Jeśli na przykład określono net5.0 w pliku projektu, a 5.0.2 jest zainstalowane najnowsze środowisko uruchomieniowe platformy .NET, używane jest środowisko uruchomieniowe 5.0.2.

Jeśli nie zostanie znaleziona akceptowalna wersja 5.0.*, zostanie użyta nowa wersja 5.*. Jeśli na przykład określono net5.0 i zainstalowano tylko 5.1.0, aplikacja jest uruchamiana przy użyciu środowiska uruchomieniowego 5.1.0. To zachowanie jest określane jako "przechodzenie do wyższej wersji pomocniczej". Niższych wersji również nie będzie się brać pod uwagę. Jeśli nie zostanie zainstalowane akceptowalne środowisko uruchomieniowe, aplikacja nie zostanie uruchomiona.

W kilku przykładach użycia pokazano zachowanie, jeśli jest to cel 5.0:

  • ✔️ Określono wartość 5.0. 5.0.3 to zainstalowana najwyższa wersja poprawki. Używana jest wersja 5.0.3.
  • określono ❌ 5.0. Nie zainstalowano wersji 5.0.* 3.1.1 jest najwyższym zainstalowanym środowiskiem uruchomieniowym. Zostanie wyświetlony komunikat o błędzie.
  • ✔️ Określono wartość 5.0. Nie zainstalowano wersji 5.0.* 5.1.0 to zainstalowana najwyższa wersja środowiska uruchomieniowego. Używana jest wersja 5.1.0.
  • określono ❌ 3.0. Nie zainstalowano wersji 3.x. 5.0.0 jest najwyższym zainstalowanym środowiskiem uruchomieniowym. Zostanie wyświetlony komunikat o błędzie.

Wprowadzanie wersji pomocniczej ma jeden efekt uboczny, który może mieć wpływ na użytkowników końcowych. Rozważmy następujący scenariusz:

  1. Aplikacja określa, że wymagana jest 5.0.
  2. Po uruchomieniu wersja 5.0.* nie jest zainstalowana, jednak jest to wersja 5.1.0. Będzie używana wersja 5.1.0.
  3. Później użytkownik zainstaluje 5.0.3 i ponownie uruchomi aplikację, będzie teraz używana wersja 5.0.3.

Możliwe, że 5.0.3 i 5.1.0 zachowują się inaczej, szczególnie w przypadku scenariuszy, takich jak serializowanie danych binarnych.

Sterowanie zachowaniem wysuwania do przodu

Przed zastąpieniem domyślnego zachowania wycofywania zapoznaj się z poziomem zgodności środowiska uruchomieniowego platformy .NET .NET.

Zachowanie przesunięcia do przodu dla aplikacji można skonfigurować na cztery różne sposoby.

  1. Ustawienie poziomu projektu przez ustawienie właściwości <RollForward>:

    <PropertyGroup>
  <RollForward>LatestMinor</RollForward>
</PropertyGroup>

  2. Plik *.runtimeconfig.json.

    Ten plik jest generowany podczas kompilowania aplikacji. Jeśli właściwość <RollForward> została ustawiona w projekcie, jest ona odtwarzana w pliku *.runtimeconfig.json jako ustawienie rollForward. Użytkownicy mogą edytować ten plik, aby zmienić zachowanie aplikacji.

    {
  "runtimeOptions": {
    "tfm": "net5.0",
    "rollForward": "LatestMinor",
    "framework": {
      "name": "Microsoft.NETCore.App",
      "version": "5.0.0"
    }
  }
}

  3. Właściwość --roll-forward <value> polecenia dotnet.

    Po uruchomieniu aplikacji możesz kontrolować zachowanie ruchu do przodu za pomocą wiersza polecenia:

    dotnet run --roll-forward LatestMinor
dotnet myapp.dll --roll-forward LatestMinor
myapp.exe --roll-forward LatestMinor

  4. Zmienna środowiskowa DOTNET_ROLL_FORWARD.

Pierwszeństwo

Zachowanie przesuwania do przodu jest ustawiane według następującej kolejności po uruchomieniu aplikacji, wyższe wartości mają pierwszeństwo przed niższymi wartościami:

  1. Najpierw zostanie oceniony plik konfiguracji *.runtimeconfig.json.
  2. Następnie brana jest pod uwagę zmienna środowiskowa DOTNET_ROLL_FORWARD, zastępując poprzednie sprawdzenie.
  3. Na koniec każdy parametr --roll-forward przekazany do uruchomionej aplikacji zastępuje wszystkie inne elementy.

Wartości

Jednak ustawiwszy opcję przesunięcia wprzód, użyj jednej z następujących wartości, aby określić zachowanie:

Wartość Opis
Minor domyślna, jeśli nie zostanie określona.
Przerzuć do najniższej wyższej wersji pomocniczej, jeśli brakuje żądanej wersji pomocniczej. Jeśli żądana mniejsza wersja jest dostępna, wtedy używana jest zasada LatestPatch.
Major Przejdź do następnej dostępnej wyższej wersji głównej i najniższej wersji pomocniczej, jeśli żądana wersja główna jest niedostępna. Jeśli żądana wersja główna jest obecna, zostanie użyta zasada Minor.
LatestPatch Przejdź do najwyższej wersji aktualizacji. Ta wartość wyłącza przejście do nowszej wersji pomocniczej.
LatestMinor Przejdź do najwyższej wersji pomocniczej, nawet jeśli istnieje już żądana wersja pomocnicza.
LatestMajor Przerzuć do najwyższej wersji głównej i najwyższej wersji pomocniczej, nawet jeśli zażądano wersji głównej.
Disable Nie przekazuj do przodu, zwiąż się tylko z określoną wersją. Ta polityka nie jest zalecana do użytku ogólnego, ponieważ wyłącza możliwość aktualizacji do najnowszych poprawek. Ta wartość jest zalecana tylko do testowania.

Wdrożenia samodzielne obejmują wybrane środowisko uruchomieniowe

Aplikację można opublikować jako samodzielna dystrybucja . Takie podejście łączy środowisko uruchomieniowe i biblioteki platformy .NET z aplikacją. Wdrożenia samodzielne nie mają zależności od środowisk uruchomieniowych. Wybór wersji środowiska uruchomieniowego odbywa się w czasie publikowania, a nie w czasie wykonywania.

Zdarzenie przywracania występujące podczas publikowania wybiera najnowszą wersję poprawki danej rodziny środowiska uruchomieniowego. Na przykład dotnet publish wybierze .NET 5.0.3, jeśli jest to najnowsza wersja poprawki w rodzinie środowiska uruchomieniowego .NET 5. Platforma docelowa (w tym najnowsze zainstalowane poprawki zabezpieczeń) jest spakowana z aplikacją.

Błąd występuje, jeśli minimalna wersja określona dla aplikacji nie jest spełniona. dotnet publish wiąże się z najnowszą wersją poprawki środowiska uruchomieniowego (w ramach danej rodziny wersji major.minor). dotnet publish nie obsługuje semantyki przesuwania do przodu dotnet run. Aby uzyskać więcej informacji na temat poprawek i wdrożeń samodzielnych, zapoznaj się z artykułem na temat wyboru poprawek środowiska uruchomieniowego przy wdrażaniu aplikacji platformy .NET.

Wdrożenia samodzielne mogą wymagać określonej wersji poprawki. W pliku projektu można zastąpić minimalną wersję poprawki środowiska uruchomieniowego (do wyższych lub niższych wersji), jak pokazano w poniższym przykładzie:

<PropertyGroup>
  <RuntimeFrameworkVersion>5.0.7</RuntimeFrameworkVersion>
</PropertyGroup>

Element RuntimeFrameworkVersion zastępuje domyślne zasady wersji. W przypadku samodzielnych wdrożeń RuntimeFrameworkVersion określa się dokładną wersję platformy środowiska uruchomieniowego. W przypadku aplikacji zależnych od platformy RuntimeFrameworkVersion określa minimalną wymaganą wersję platformy uruchomieniowej.

Zobacz też