Wybierz wersję programu .NET do użycia

W tym artykule wyjaśniono zasady używane przez narzędzia platformy .NET, zestaw SDK i środowisko uruchomieniowe do wybierania wersji. Te zasady zapewniają równowagę między uruchamianiem aplikacji przy użyciu określonych wersji i umożliwieniem łatwego uaktualniania maszyn dewelopera i użytkownika końcowego. Te zasady umożliwiają:

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

Wybór wersji:

W pozostałej części tego dokumentu przeanalizowano te cztery scenariusze.

Zestaw SDK używa najnowszej zainstalowanej wersji

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

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

Możesz korzystać z najnowszych funkcji i ulepszeń zestawu SDK, a jednocześnie korzystać ze starszych wersji środowiska uruchomieniowego platformy .NET. Możesz wybrać różne wersje środowiska uruchomieniowego platformy .NET przy użyciu tych samych narzędzi zestawu SDK.

W rzadkich przypadkach może być konieczne użycie starszej wersji zestawu SDK. Ta wersja jest określana w pliku global.json. Zasady "użyj najnowszej" oznaczają, że do określenia wersji zestawu .NET SDK starszej niż najnowsza zainstalowana wersja używasz tylko pliku global.json .

Plik global.json można umieścić w dowolnym miejscu w hierarchii plików. Interfejs wiersza polecenia wyszukuje pierwszy znalezione przez niego global.json w górę od katalogu projektu. Możesz kontrolować, do których projektów dany plik global.json ma zastosowanie jego miejsce w systemie plików. Interfejs wiersza polecenia .NET wyszukuje plik global.json iteracyjnie przechodząc w górę od bieżącego katalogu roboczego. Pierwszy znaleziony plik global.json określa używaną wersję. Jeśli ta wersja zestawu SDK jest zainstalowana, ta wersja jest używana. Jeśli zestaw SDK określony w pliku global.json nie zostanie znaleziony, interfejs wiersza polecenia platformy .NET użyje reguł dopasowania do wybrania zgodnego zestawu SDK lub ulegnie awarii, jeśli nie zostanie znaleziony.

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

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

Proces wybierania wersji zestawu SDK jest:

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

Aby uzyskać więcej informacji na temat wyboru wersji zestawu SDK, zobacz sekcje Matching rules and rollForward (Reguły dopasowywania i rollForward ) artykułu global.json overview (Omówienie pliku global.json ).

Monikery struktury docelowej definiują interfejsy API czasu kompilacji

Projekt jest kompilowany na podstawie interfejsów API zdefiniowanych w monikerze struktury 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>net5.0</TargetFramework>

Projekt można skompilować na wielu serwerach TFM. Ustawianie wielu platform docelowych jest częściej spotykane w przypadku bibliotek, ale można je również wykonać z aplikacjami. Należy określić właściwość TargetFrameworks (w liczbie mnogiej TargetFramework). Struktury docelowe są rozdzielane średnikami, jak pokazano w poniższym przykładzie:

<TargetFrameworks>net5.0;netcoreapp3.1;net47</TargetFrameworks>

Dany zestaw SDK obsługuje stały zestaw platform ograniczony do platformy docelowej środowiska uruchomieniowego, z które jest dostarczany. Na przykład zestaw .NET 5 SDK zawiera środowisko uruchomieniowe .NET 5, które jest implementacją platformy net5.0 docelowej. Zestaw .NET 5 SDK obsługuje netcoreapp2.0funkcje , netcoreapp2.1, netcoreapp3.0itd., ale nie net6.0 (lub wyższe). Zainstaluj zestaw SDK platformy .NET 6 w celu skompilowania dla programu net6.0.

.NET Standard

.NET Standard to sposób na ukierunkowanie powierzchni interfejsu API współużytkowanej przez różne implementacje platformy .NET. Począwszy od wydania platformy .NET 5, która jest standardem interfejsu API, .NET Standard ma niewielkie znaczenie, z wyjątkiem jednego scenariusza: program .NET Standard jest przydatny, gdy chcesz kierować zarówno do platformy .NET, jak i .NET Framework. .NET 5 implementuje wszystkie .NET Standard wersji.

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

Aplikacje zależne od struktury — roll-forward

W przypadku uruchamiania dotnet rundotnet run aplikacji ze źródła za pomocą programu z wdrożenia zależnego od struktury za pomocą programu lub z pliku wykonywalnego zależnego od struktury za pomocą programu plik wykonywalny jest hostem aplikacji.

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

Jeśli nie zostanie znaleziona 5.0.* akceptowalna wersja, zostanie użyta 5.* nowa wersja. Jeśli na przykład określono i zainstalowano net5.05.1.0 tylko program , aplikacja będzie uruchamiana przy użyciu środowiska uruchomieniowego 5.1.0 . To zachowanie jest określane jako "wersja pomocnicza do przodu". Niższe wersje również nie będą rozważane. Jeśli nie zainstalowano akceptowalnego środowiska uruchomieniowego, aplikacja nie zostanie uruchomiony.

Kilka przykładów użycia demonstruje zachowanie, jeśli elementem docelowym jest 5.0:

  • ✔️ Określono wartość 5.0. 5.0.3 to najwyższa zainstalowana wersja poprawki. Używana jest 5.0.3.
  • ❌ Określono wartość 5.0. Nie są instalowane żadne wersje 5.0.*. 3.1.1 to najwyższe zainstalowane środowisko uruchomieniowe. Zostanie wyświetlony komunikat o błędzie.
  • ✔️ Określono wartość 5.0. Nie są instalowane żadne wersje 5.0.*. 5.1.0 to najwyższa zainstalowana wersja środowiska uruchomieniowego. Używana jest 5.1.0.
  • ❌ Określono wartość 3.0. Nie są instalowane żadne wersje 3.x. 5.0.0 to najwyższe zainstalowane środowisko uruchomieniowe. Zostanie wyświetlony komunikat o błędzie.

Przekazywanie wersji pomocniczej ma jeden efekt uboczny, który może mieć wpływ na użytkowników końcowych. Poniżej przedstawiono przykładowy scenariusz:

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

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

Kontrolowanie zachowania rzutowania do przodu

Zachowanie wywłaszczania dla aplikacji można skonfigurować na cztery różne sposoby:

  1. Project na poziomie, ustawiając właściwość <RollForward> :

    <PropertyGroup>
      <RollForward>LatestMinor</RollForward>
    </PropertyGroup>
    
  2. Plik *.runtimeconfig.json .

    Ten plik jest kompilowany podczas kompilowania aplikacji. Jeśli właściwość <RollForward> została ustawiona w projekcie, zostanie odtąd *.runtimeconfig.json odtworzyć ją w pliku jako rollForward ustawienie. 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. --roll-forward <value> Właściwość dotnet polecenia.

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

    dotnet run --roll-forward LatestMinor
    dotnet myapp.dll --roll-forward LatestMinor
    myapp.exe --roll-forward LatestMinor
    
  4. Zmienna DOTNET_ROLL_FORWARD środowiskowa.

Pierwszeństwo

Zachowanie podczas uruchamiania aplikacji jest ustawiane w następującej kolejności. Elementy o wyższych numerach mają pierwszeństwo przed elementami o mniejszej numerze:

  1. Najpierw jest *.runtimeconfig.json oceniany plik konfiguracji.
  2. Następnie rozważana DOTNET_ROLL_FORWARD jest zmienna środowiskowa, zastępując poprzednia kontrola.
  3. Na koniec każdy parametr --roll-forward przekazany do uruchomionej aplikacji zastępuje wszystkie inne.

Wartości

Jednak w przypadku ustawienia rzutowania do przodu użyj jednej z następujących wartości, aby ustawić zachowanie:

Wartość Opis
Minor Wartość domyślna , jeśli nie zostanie określona.
Przekieruj do najniższej wyższej wersji pomocniczej, jeśli brakuje żądanej wersji pomocniczej. Jeśli istnieje żądana wersja pomocnicza, używane są LatestPatch zasady.
Major Jeśli żądana wersja główna nie jest dostępna, przekieruj do następnej dostępnej wersji wyższej i najniższej wersji pomocniczej. Jeśli żądana wersja główna jest obecna, używane są Minor zasady.
LatestPatch Przekieruj do najwyższej wersji poprawki. Ta wartość wyłącza funkcję przekazywania wersji pomocniczej.
LatestMinor Przekieruj do najwyższej wersji pomocniczej, nawet jeśli istnieje żądana wersja pomocnicza.
LatestMajor Przekieruj do wersji najwyższej i najwyższej wersji pomocniczej, nawet jeśli istnieje żądana wersja główna.
Disable Nie przekieruj do przodu, powiąż tylko z określoną wersją. Te zasady nie są zalecane do użytku ogólnego, ponieważ wyłącza możliwość przekazywania do najnowszych poprawek. Ta wartość jest zalecana tylko do testowania.

Wdrożenia samodzielne obejmują wybrane środowisko uruchomieniowe

Aplikację można opublikować jako samodzielną dystrybucję. Takie podejście dołącza środowisko uruchomieniowe .NET i biblioteki do aplikacji. Wdrożenia samodzielne nie są zależne od środowisk uruchomieniowych. Wybór wersji środowiska uruchomieniowego odbywa się w czasie publikowania, a nie w czasie wykonywania.

Zdarzenie przywracania , które występuje podczas publikowania, wybiera najnowszą wersję poprawki danej rodziny środowiska uruchomieniowego. Na przykład program wybierze dotnet publish platformę .NET 5.0.3, jeśli jest to najnowsza wersja poprawki z rodziny środowiska uruchomieniowego .NET 5. Docelowa framework (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 główna.pomocnicza). dotnet publish nie obsługuje semantyki rzutowania dotnet run. Aby uzyskać więcej informacji na temat poprawek i samodzielnych wdrożeń, zobacz artykuł na temat wyboru poprawek środowiska uruchomieniowego podczas wdrażania aplikacji .NET.

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

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

Element RuntimeFrameworkVersion zastępuje domyślne zasady wersji. W przypadku wdrożeń samodzielnych określa RuntimeFrameworkVersion dokładną RuntimeFrameworkVersion środowiska uruchomieniowego. Dla aplikacji zależnych od struktury określa RuntimeFrameworkVersionRuntimeFrameworkVersion wersję środowiska uruchomieniowego.

Zobacz też