Wybierz wersję platformy .NET do użycia

Artykuł
03/05/2024

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:

Po uruchomieniu polecenia zestawu SDK zestaw SDK używa najnowszej zainstalowanej wersji.
Podczas tworzenia zestawu monikers platformy docelowej definiują interfejsy API czasu kompilacji.
Po uruchomieniu aplikacji .NET aplikacje zależne od platformy docelowej są wdrażane.
Podczas publikowania samodzielnej aplikacji wdrożenia samodzielne obejmują wybrane środowisko uruchomieniowe.

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

Zestaw SDK używa najnowszej zainstalowanej wersji

Polecenia zestawu SDK obejmują dotnet new polecenia i dotnet run. Interfejs wiersza polecenia platformy .NET musi wybrać wersję zestawu SDK dla każdego dotnet polecenia. 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 rzadkich przypadkach może być konieczne użycie starszej wersji zestawu SDK. Należy określić wersję w pliku global.json. Zasady "użyj najnowszej" oznacza, że używasz tylko global.json do określenia wersji zestawu SDK platformy .NET starszej niż najnowsza zainstalowana wersja.

global.json można umieścić w dowolnym miejscu w hierarchii plików. Interfejs wiersza polecenia wyszukuje w górę z katalogu projektu pierwszy global.json odnajdywania. Kontrolujesz, które projekty danego global.json mają zastosowanie w jego miejscu 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. 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, interfejs wiersza polecenia platformy .NET używa reguł dopasowania do wybierania zgodnego zestawu SDK lub kończy się niepowodzeniem, jeśli nie zostanie znaleziony żaden.

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

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

Proces wybierania wersji zestawu SDK to:

dotnetwyszukuje plik global.json iteracyjnie odwrotnie przechodząc ścieżkę w górę z bieżącego katalogu roboczego.
dotnet używa zestawu SDK określonego w pierwszym global.json znalezionym .
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 Dopasowywanie reguł i rollForward w artykule przeglądu global.json.

Interfejsy Monikers platformy docelowej definiują interfejsy API czasu kompilacji

Projekt jest kompilowane na podstawie interfejsów API zdefiniowanych w programie Target Framework Moniker (TFM). Należy określić strukturę docelową w pliku projektu. TargetFramework Ustaw element 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 bardziej powszechne w przypadku bibliotek, ale można je również wykonywać za pomocą aplikacji. Należy określić TargetFrameworks właściwość (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 struktur, ograniczony do docelowej struktury środowiska uruchomieniowego, z który jest dostarczany. Na przykład zestaw .NET 5 SDK zawiera środowisko uruchomieniowe platformy .NET 5, które jest implementacją platformy net5.0 docelowej. Zestaw .NET 5 SDK obsługuje elementy netcoreapp2.0, netcoreapp2.1, netcoreapp3.0i tak dalej, ale nie net6.0 (lub nowsze). Zainstaluj zestaw .NET 6 SDK do skompilowania dla programu net6.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 platformy .NET 5, która jest samym standardem interfejsu API, platforma .NET Standard ma niewielkie znaczenie, z wyjątkiem jednego scenariusza: platforma .NET Standard jest przydatna, gdy chcesz kierować programy zarówno .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 dotnet runza pomocą polecenia , z wdrożenia zależnego od platformy z dotnet myapp.dllprogramem lub pliku wykonywalnego zależnego od platformy z myapp.exedotnet programem plik wykonywalny jest hostem aplikacji.

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

Jeśli nie zostanie znaleziona akceptowalna 5.0.* wersja, zostanie użyta nowa 5.* wersja. Jeśli na przykład określono wartość net5.0 i jest zainstalowana tylko 5.1.0 , aplikacja jest uruchamiana przy użyciu środowiska uruchomieniowego 5.1.0 . To zachowanie jest określane jako "wycofywanie wersji pomocniczej". Niższe wersje również nie będą brane 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 wartość 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 wartość 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:

Aplikacja określa, że wymagana jest 5.0.
Po uruchomieniu wersja 5.0.* nie jest zainstalowana, jednak jest to wersja 5.1.0. Będzie używana wersja 5.1.0.
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 wycofywania

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

Zachowanie wprowadzania dla aplikacji można skonfigurować na cztery różne sposoby:

Ustawienie na poziomie projektu przez ustawienie <RollForward> właściwości:
```
<PropertyGroup>
  <RollForward>LatestMinor</RollForward>
</PropertyGroup>
```
Plik *.runtimeconfig.json .

Ten plik jest generowany podczas kompilowania aplikacji. <RollForward> Jeśli właściwość została ustawiona w projekcie, jest ona odtwarzana w *.runtimeconfig.json 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"
    }
  }
}
```
dotnet Właściwość polecenia--roll-forward <value>.

Po uruchomieniu aplikacji możesz kontrolować zachowanie wycofywania za pomocą wiersza polecenia:
```
dotnet run --roll-forward LatestMinor
dotnet myapp.dll --roll-forward LatestMinor
myapp.exe --roll-forward LatestMinor
```
Zmienna DOTNET_ROLL_FORWARD środowiskowa.

Pierwszeństwo

Zachowanie wycofywania jest ustawiane według następującej kolejności po uruchomieniu aplikacji, większa liczba elementów, które mają pierwszeństwo przed niższymi liczbami elementów:

*.runtimeconfig.json Najpierw zostanie oceniony plik konfiguracji.
Następnie zmienna środowiskowa jest brana DOTNET_ROLL_FORWARD pod uwagę, przesłaniając poprzednią kontrolę.
Na koniec każdy --roll-forward parametr przekazany do uruchomionej aplikacji zastępuje wszystkie inne elementy.

Wartości

Jednak ustawisz ustawienie wycofywania, użyj jednej z następujących wartości, aby ustawić zachowanie:

Wartość	Opis
`Minor`	Wartość 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 wersja pomocnicza jest obecna, `LatestPatch` zostaną użyte zasady.
`Major`	Przejdź do następnej dostępnej nowszej wersji głównej i najniższej wersji pomocniczej, jeśli zażądano wersji głównej. Jeśli żądana wersja główna jest obecna, `Minor` zostaną użyte zasady.
`LatestPatch`	Przerzuć do najwyższej wersji poprawki. Ta wartość wyłącza wycofywanie wersji pomocniczej.
`LatestMinor`	Przerzuć do najwyższej wersji pomocniczej, nawet jeśli zażądano wersji pomocniczej.
`LatestMajor`	Przerzuć do najwyższej wersji głównej i najwyższej wersji pomocniczej, nawet jeśli zażądano wersji głównej.
`Disable`	Nie przesyłaj dalej, 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 łą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 wybierze platformę .NET 5.0.3, dotnet publish jeśli jest to najnowsza wersja poprawki w rodzinie środowiska uruchomieniowego platformy .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 zgodna. dotnet publish wiąże się z najnowszą wersją poprawki środowiska uruchomieniowego (w ramach danej rodziny wersji głównej.pomocniczej). dotnet publish nie obsługuje semantyki rzutowania elementu dotnet run. Aby uzyskać więcej informacji na temat poprawek i wdrożeń samodzielnie zawartych, zobacz artykuł dotyczący wyboru poprawek środowiska uruchomieniowego w 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 wdrożeń RuntimeFrameworkVersion samodzielnie określa dokładną wersję struktury środowiska uruchomieniowego. W przypadku aplikacji RuntimeFrameworkVersion zależnych od platformy określa minimalną wymaganą wersję platformy uruchomieniowej.