Vyberte verzi .NET, která se má použít.

Článek
03/12/2024

Tento článek vysvětluje zásady používané nástroji .NET, sadou SDK a modulem runtime pro výběr verzí. Tyto zásady poskytují rovnováhu mezi spouštěním aplikací pomocí zadaných verzí a usnadňují upgrade počítačů pro vývojáře i koncové uživatele. Tyto zásady umožňují:

Snadné a efektivní nasazení rozhraní .NET, včetně aktualizací zabezpečení a spolehlivosti
Používejte nejnovější nástroje a příkazy nezávislé na cílovém modulu runtime.

Výběr verze nastane:

Když spustíte příkaz sady SDK, sada SDK používá nejnovější nainstalovanou verzi.
Když sestavíte sestavení, cílové rozhraní monikers definují rozhraní API času sestavení.
Když spustíte aplikaci .NET, cílové rozhraní závislé aplikace se postupně přepojí.
Když publikujete samostatnou aplikaci, zahrnují samostatná nasazení vybraný modul runtime.

Zbývající část tohoto dokumentu zkoumá tyto čtyři scénáře.

Sada SDK používá nejnovější nainstalovanou verzi.

Příkazy sady SDK zahrnují dotnet new a dotnet run. Rozhraní příkazového řádku .NET musí pro každý dotnet příkaz zvolit verzi sady SDK. Ve výchozím nastavení používá nejnovější sadu SDK nainstalovanou na počítači, i když:

Projekt cílí na starší verzi modulu runtime .NET.
Nejnovější verze sady .NET SDK je verze Preview.

Při cílení na starší verze modulu runtime .NET můžete využít nejnovější funkce a vylepšení sady SDK. Pomocí stejných nástrojů sady SDK můžete cílit na různé verze modulu runtime .NET.

Ve výjimečných případech možná budete muset použít starší verzi sady SDK. Tuto verzi zadáte v souboru global.json. Zásada "použít nejnovější" znamená, že používáte pouze global.json k určení verze sady .NET SDK starší než nejnovější nainstalovaná verze.

global.json lze umístit kdekoli v hierarchii souborů. Rozhraní příkazového řádku vyhledá první global.json nalezené v adresáři projektu směrem nahoru. Určujete, na které projekty se daná global.json vztahuje podle jeho místa v systému souborů. Rozhraní příkazového řádku .NET vyhledá soubor global.json iterativním procházením cesty směrem nahoru z aktuálního pracovního adresáře. První nalezený global.json soubor určuje použitou verzi. Pokud je tato verze sady SDK nainstalovaná, použije se tato verze. Pokud sada SDK zadaná v global.json nebyla nalezena, rozhraní příkazového řádku .NET k výběru kompatibilní sady SDK použije odpovídající pravidla nebo selže, pokud se nenajde.

Následující příklad ukazuje syntaxi global.json :

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

Proces výběru verze sady SDK je následující:

dotnetvyhledá soubor global.json iterativním obrácením cesty směrem nahoru z aktuálního pracovního adresáře.
dotnet používá sadu SDK zadanou v první global.json nalezené.
dotnet používá nejnovější nainstalovanou sadu SDK, pokud se nenajde žádná global.json .

Další informace o výběru verze sady SDK najdete v částech s odpovídajícími pravidly a vrácením zpět v článku s přehledem global.json.

Monikers cílové architektury definují rozhraní API pro čas sestavení

Projekt sestavíte pomocí rozhraní API definovaných v monikeru cílové architektury (TFM). V souboru projektu zadáte cílovou architekturu . Nastavte TargetFramework prvek v souboru projektu, jak je znázorněno v následujícím příkladu:

<TargetFramework>net8.0</TargetFramework>

Projekt můžete sestavit proti více TFM. Nastavení více cílových architektur je pro knihovny častější, ale lze je provádět i s aplikacemi. Zadáte TargetFrameworks vlastnost (množné číslo TargetFramework). Cílové architektury jsou oddělené středníkem, jak je znázorněno v následujícím příkladu:

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

Daná sada SDK podporuje pevnou sadu architektur, která je omezena na cílovou architekturu modulu runtime, se kterým se dodává. Například sada .NET 8 SDK zahrnuje modul runtime .NET 8, což je implementace net8.0 cílové architektury. Sada .NET 8 SDK podporuje net7.0, net6.0a net5.0, ale ne net9.0 (nebo vyšší). Nainstalujete sadu .NET 9 SDK pro sestavení pro net9.0.

.NET Standard

.NET Standard byl způsob, jak cílit na povrch rozhraní API sdílený různými implementacemi .NET. Počínaje vydáním rozhraní .NET 5, což je samotný standard rozhraní API, má .NET Standard malý význam, s výjimkou jednoho scénáře: .NET Standard je užitečné, když chcete cílit na .NET i .NET Framework. .NET 5 implementuje všechny verze .NET Standard.

Další informace najdete v tématu .NET 5 a .NET Standard.

Postupné zavedení aplikací závislých na architektuře

Když spustíte aplikaci ze zdroje pomocí dotnet run, z nasazení závislého na rozhraní nebo dotnet myapp.dllze spustitelného souboru závislého na rozhraní s myapp.exe, dotnet spustitelný soubor je hostitelem aplikace.

Hostitel zvolí nejnovější verzi opravy nainstalovanou na počítači. Pokud jste například zadali net5.0 v souboru projektu a 5.0.2 je nainstalovaný nejnovější modul runtime .NET, použije se 5.0.2 modul runtime.

Pokud se nenajde žádná přijatelná 5.0.* verze, použije se nová 5.* verze. Pokud jste například zadali net5.0 a nainstalovali jste pouze 5.1.0 aplikaci, spustí se pomocí 5.1.0 modulu runtime. Toto chování se označuje jako "roll-forward podverze". Nižší verze se také nebudou brát v úvahu. Pokud není nainstalovaný žádný přijatelný modul runtime, aplikace se nespustí.

Několik příkladů použití ukazuje chování, pokud cílíte na verzi 5,0:

✔️ Je zadána hodnota 5.0. 5.0.3 je nejvyšší nainstalovaná verze opravy. Používá se 5.0.3.
❌ Je zadána hodnota 5.0. Nejsou nainstalovány žádné verze 5.0.*. 3.1.1 je nejvyšší nainstalovaný modul runtime. Zobrazí se chybová zpráva.
✔️ Je zadána hodnota 5.0. Nejsou nainstalovány žádné verze 5.0.*. 5.1.0 je nejvyšší nainstalovaná verze modulu runtime. Používá se 5.1.0.
❌ Je zadána hodnota 3.0. Nejsou nainstalovány žádné verze 3.x. 5.0.0 je nejvyšší nainstalovaný modul runtime. Zobrazí se chybová zpráva.

Vrácení podverze má jeden vedlejší účinek, který může mít vliv na koncové uživatele. Zvažte následující scénář:

Aplikace určuje, že se vyžaduje hodnota 5.0.
Při spuštění se verze 5.0.* nenainstaluje, ale 5.1.0 je. Použije se verze 5.1.0.
Později uživatel nainstaluje verzi 5.0.3 a znovu spustí aplikaci, použije se teď verze 5.0.3.

Je možné, že se verze 5.0.3 a 5.1.0 chovají odlišně, zejména pro scénáře, jako je serializace binárních dat.

Řízení chování roll-forward

Před přepsáním výchozího chování roll-forward se seznamte s úrovní kompatibility modulu runtime .NET.

Roll-forward chování pro aplikaci lze nakonfigurovat čtyřmi různými způsoby:

Nastavení na úrovni projektu nastavením <RollForward> vlastnosti:

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

Soubor *.runtimeconfig.json .

Tento soubor se vytvoří při kompilaci aplikace. <RollForward> Pokud byla vlastnost nastavena v projektu, je reprodukována v *.runtimeconfig.json souboru jako rollForward nastavení. Uživatelé můžou tento soubor upravit, aby změnili chování aplikace.
```
{
  "runtimeOptions": {
    "tfm": "net5.0",
    "rollForward": "LatestMinor",
    "framework": {
      "name": "Microsoft.NETCore.App",
      "version": "5.0.0"
    }
  }
}
```
Vlastnost dotnet příkazu --roll-forward <value> .

Při spuštění aplikace můžete řídit chování posouvání přes příkazový řádek:
```
dotnet run --roll-forward LatestMinor
dotnet myapp.dll --roll-forward LatestMinor
myapp.exe --roll-forward LatestMinor
```
Proměnná DOTNET_ROLL_FORWARD prostředí.

Pořadí podle priority

Při spuštění aplikace je chování roll forward nastaveno následujícím pořadím, vyšší číslovaný položky mají přednost před nižšími číslovanými položkami:

*.runtimeconfig.json Nejprve se vyhodnotí konfigurační soubor.
DOTNET_ROLL_FORWARD Dále se považuje proměnná prostředí, která přepíše předchozí kontrolu.
Nakonec všechny --roll-forward parametry předané spuštěné aplikaci přepíší všechno ostatní.

Hodnoty

K nastavení chování však použijte jednu z následujících hodnot:

Hodnota	Popis
`Minor`	Výchozí, pokud není zadáno. Pokud chybí požadovaná podverze, přejděte na nejnižší nižší podverzi. Pokud je požadovaná podverze k dispozici, použije se `LatestPatch` zásada.
`Major`	Pokud chybí požadovaná hlavní verze, přejděte k další dostupné vyšší hlavní verzi a nejnižší podverzi. Pokud je požadovaná hlavní verze přítomen, použije se `Minor` zásada.
`LatestPatch`	Přechod na nejvyšší verzi opravy Tato hodnota zakáže vrácení podverze vpřed.
`LatestMinor`	Roll-forward to highest minor version, even if requested minor version is present.
`LatestMajor`	Roll-forward to highest major and highest minor version, even ifed major is present.
`Disable`	Nepřecházejte dál, vytvořte vazbu pouze na zadanou verzi. Tato zásada se nedoporučuje pro obecné použití, protože zakazuje přechod na nejnovější opravy. Tato hodnota se doporučuje jenom pro testování.

Samostatná nasazení zahrnují vybraný modul runtime.

Aplikaci můžete publikovat jako samostatnou distribuci. Tento přístup spojuje modul runtime a knihovny .NET s vaší aplikací. Samostatná nasazení nemají závislost na prostředích runtime. Výběr verze modulu runtime probíhá v době publikování, ne v době běhu.

Událost obnovení , ke které dochází při publikování, vybere nejnovější verzi opravy dané řady modulů runtime. Pokud se jedná například o nejnovější verzi opravy v rodině modulu runtime .NET 5, dotnet publish vybereme .NET 5.3. Cílová architektura (včetně nejnovějších nainstalovaných oprav zabezpečení) je zabalená s aplikací.

Pokud není splněná minimální verze zadaná pro aplikaci, dojde k chybě. dotnet publish vytvoří vazbu na nejnovější verzi opravy modulu runtime (v rámci dané řady hlavních verzí podverze). dotnet publish nepodporuje sémantiku sémantiky dotnet run. Další informace o opravách a samostatných nasazeních najdete v článku o výběru opravy modulu runtime při nasazování aplikací .NET.

Samostatná nasazení můžou vyžadovat konkrétní verzi opravy. V souboru projektu můžete přepsat minimální verzi opravy modulu runtime (na vyšší nebo nižší verze), jak je znázorněno v následujícím příkladu:

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

Element RuntimeFrameworkVersion přepíše výchozí zásady verze. Pro samostatná nasazení RuntimeFrameworkVersion určuje přesnou verzi rozhraní runtime. Pro aplikace závislé na rozhraní určuje RuntimeFrameworkVersionminimální požadovanou verzi modulu runtime.