Выбор версии .NET Core для использованияSelect the .NET Core version to use

В этой статье описаны политики, используемые средствами .NET Core, пакетом SDK и средой выполнения для выбора версии.This article explains the policies used by the .NET Core tools, SDK, and runtime for selecting versions. Эти политики обеспечивают баланс между запуском приложений с помощью указанных версий и упрощенным процессом обновления компьютеров разработчика и конечного пользователя.These policies provide a balance between running applications using the specified versions and enabling ease of upgrading both developer and end-user machines. Эти политики выполняют следующие действия:These policies perform the following actions:

  • Простое и эффективное развертывание .NET Core, включая обновления безопасности и надежности.Easy and efficient deployment of .NET Core, including security and reliability updates.
  • Использование новейших средств и команд независимо от целевой среды выполнения.Use the latest tools and commands independent of target runtime.

Ситуации выбора версии:Version selection occurs:

В остальной части этой статьи рассматриваются эти четыре сценария.The rest of this document examines those four scenarios.

Пакет SDK использует последнюю установленную версиюThe SDK uses the latest installed version

Команды пакета SDK включают dotnet new и dotnet run.SDK commands include dotnet new and dotnet run. В .NET Core CLI нужно выбрать версию пакета SDK для каждой команды dotnet.The .NET Core CLI must choose an SDK version for every dotnet command. В CLI используется пакет SDK последней версии, установленный на компьютере по умолчанию, даже если:It uses the latest SDK installed on the machine by default, even if:

  • проект предназначен для более ранней версии среды выполнения .NET Core;The project targets an earlier version of the .NET Core runtime.
  • последняя версия пакета SDK для .NET Core доступна в виде предварительной версии.The latest version of the .NET Core SDK is a preview version.

Вы можете воспользоваться последними преимуществами и улучшениями пакета SDK при работе с более ранними версиями среды выполнения .NET Core.You can take advantage of the latest SDK features and improvements while targeting earlier .NET Core runtime versions. Вы можете выбирать несколько версий среды выполнения .NET Core в разных проектах, используя одинаковые средства пакета SDK для всех проектов.You can target multiple runtime versions of .NET Core on different projects, using the same SDK tools for all projects.

В редких случаях вам потребуется использовать более раннюю версию пакета SDK.On rare occasions, you may need to use an earlier version of the SDK. Укажите эту версию в файле global.json.You specify that version in a global.json file. Политика использования последней версии означает, что вам придется использовать файл global.json, чтобы указать версию пакета SDK для .NET Core, если она раньше последней установленной версии.The "use latest" policy means you only use global.json to specify a .NET Core SDK version earlier than the latest installed version.

Файл global.json можно поместить в любое место в иерархии файлов.global.json can be placed anywhere in the file hierarchy. Интерфейс командной строки выполняет поиск, переходя вверх от каталога проекта до первого найденного файла global.json.The CLI searches upward from the project directory for the first global.json it finds. Вы сами выбираете, на какие проекты распространяется конкретный файл global.json, когда размещаете его в файловой системе.You control which projects a given global.json applies to by its place in the file system. .NET CLI ищет файл global.json последовательно, двигаясь вверх от текущего рабочего каталога.The .NET CLI searches for a global.json file iteratively navigating the path upward from the current working directory. Первый найденный файл global.json задает используемую версию.The first global.json file found specifies the version used. Если эта версия установлена, она будет использоваться.If that version is installed, that version is used. Если пакет SDK, указанный в файле global.json, не найден, .NET CLI выполняет накат к последнему установленному пакету SDK.If the SDK specified in the global.json is not found, the .NET CLI rolls forward to the latest SDK installed. Накат аналогичен поведению по умолчанию, если файл global.json не найден.Roll-forward is the same as the default behavior, when no global.json file is found.

В следующем примере приводится синтаксис файла global.json.The following example shows the global.json syntax:

{
  "sdk": {
    "version": "2.0.0"
  }
}

Процесс выбора версии пакета SDK выглядит следующим образом:The process for selecting an SDK version is:

  1. dotnet ищет файл global.json последовательно, двигаясь вверх от текущего рабочего каталога.dotnet searches for a global.json file iteratively reverse-navigating the path upward from the current working directory.
  2. dotnet использует пакет SDK, указанный в первом найденном файле global.json.dotnet uses the SDK specified in the first global.json found.
  3. dotnet использует последнюю установленную версию пакета SDK, если файл global.json не найден.dotnet uses the latest installed SDK if no global.json is found.

Дополнительные сведения о выборе версии пакета SDK см. в разделе о правилах сопоставления в статье о файле global.json.You can learn more about selecting an SDK version in the Matching rules section of the article on global.json.

Моникеры целевой платформы определяют API во время сборкиTarget Framework Monikers define build time APIs

Вы создаете проект на основе API, определенных в моникере целевой платформы (TFM).You build your project against APIs defined in a Target Framework Moniker (TFM). Вы указываете целевую платформу в файле проекта.You specify the target framework in the project file. Укажите элемент TargetFramework в файле проекта, как показано в следующем примере:Set the TargetFramework element in your project file as shown in the following example:

<TargetFramework>netcoreapp2.0</TargetFramework>

Вы можете создать проект на основе нескольких моникеров целевой платформы.You may build your project against multiple TFMs. Обычно несколько целевых платформ указываются для библиотек, но с приложениями это тоже возможно.Setting multiple target frameworks is more common for libraries but can be done with applications as well. Укажите свойство TargetFrameworks (множественное число от TargetFramework).You specify a TargetFrameworks property (plural of TargetFramework). Целевые платформы разделяются точкой с запятой, как показано в следующем примере:The target frameworks are semicolon-delimited as shown in the following example:

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

Данный пакет SDK поддерживает фиксированный набор платформ, вплоть до целевой платформы среды выполнения, с которой он поставляется.A given SDK supports a fixed set of frameworks, capped to the target framework of the runtime it ships with. Например, пакет SDK для .NET Core 2.0 включает среду выполнения .NET Core 2.0, которая представляет собой реализацию целевой платформы netcoreapp2.0.For example, the .NET Core 2.0 SDK includes the .NET Core 2.0 runtime, which is an implementation of the netcoreapp2.0 target framework. Пакет SDK для .NET Core 2.0 поддерживает netcoreapp1.0, netcoreapp1.1 и netcoreapp2.0, но не netcoreapp2.1 (или более поздней версии).The .NET Core 2.0 SDK supports netcoreapp1.0, netcoreapp1.1, and netcoreapp2.0 but not netcoreapp2.1 (or higher). Установите пакет SDK для .NET Core 2.1 для сборки netcoreapp2.1.You install the .NET Core 2.1 SDK to build for netcoreapp2.1.

Целевая платформа .NET Standard также ограничена целевой платформой среды выполнения, с которой поставляется пакет SDK..NET Standard target frameworks are also capped to the target framework of the runtime the SDK ships with. Пакет SDK для .NET Core 2.0 ограничен версией netstandard2.0.The .NET Core 2.0 SDK is capped to netstandard2.0.

Накат платформозависимых приложенийFramework-dependent apps roll forward

Если вы запускаете приложение из источника с dotnet run из зависящего от платформы развертывания с использованием dotnet myapp.dll или из зависящего от платформы исполняемого файла с использованиемmyapp.exe, исполняемый файл dotnet будет узлом для приложения.When you run an application from source with dotnet run, from a framework-dependent deployment with dotnet myapp.dll, or from a framework-dependent executable with myapp.exe, the dotnet executable is the host for the application.

Узел выбирает версию с последними исправлениями, установленную на компьютере.The host chooses the latest patch version installed on the machine. Например, если вы указали netcoreapp2.0 в файле проекта, а 2.0.4 является последней установленной версией среды выполнения .NET, будет использоваться среда выполнения 2.0.4.For example, if you specified netcoreapp2.0 in your project file, and 2.0.4 is the latest .NET runtime installed, the 2.0.4 runtime is used.

Если допустимая версия 2.0.* не найдена, используется новая версия 2.*.If no acceptable 2.0.* version is found, a new 2.* version is used. Например, если вы указали netcoreapp2.0 и только 2.1.0 установлена, приложение будет работать в среде выполнения 2.1.0.For example, if you specified netcoreapp2.0 and only 2.1.0 is installed, the application runs using the 2.1.0 runtime. Это поведение называется накатом до дополнительной версии.This behavior is referred to as "minor version roll-forward." Более ранние версии не будут рассматриваться.Lower versions also won't be considered. Если допустимая среда выполнения не установлена, приложение не будет работать.When no acceptable runtime is installed, the application won't run.

Несколько примеров для демонстрации такого поведения, если вы используете версию 2.0:A few usage examples demonstrate the behavior, if you target 2.0:

  • Указана версия 2.0.2.0 is specified. Последняя установленная версия с исправлениями — 2.0.5.2.0.5 is the highest patch version installed. Используется версия 2.0.5.2.0.5 is used.
  • Указана версия 2.0.2.0 is specified. Нет установленных версий 2.0.*.No 2.0.* versions are installed. Последняя установленная версия среды выполнения — 1.1.1.1.1.1 is the highest runtime installed. Отображается сообщение об ошибке.An error message is displayed.
  • Указана версия 2.0.2.0 is specified. Нет установленных версий 2.0.*.No 2.0.* versions are installed. Последняя установленная версия среды выполнения 2.x — 2.2.2.2.2.2 is the highest 2.x runtime version installed. Используется версия 2.2.2.2.2.2 is used.
  • Указана версия 2.0.2.0 is specified. Нет установленных версий 2.x.No 2.x versions are installed. Установлена версия 3.0.0.3.0.0 is installed. Отображается сообщение об ошибке.An error message is displayed.

Накат до дополнительной версии имеет побочный эффект для конечных пользователей.Minor version roll-forward has one side-effect that may affect end users. Рассмотрим следующий сценарий.Consider the following scenario:

  1. Приложение требует установки версии 2.0.The application specifies that 2.0 is required.
  2. При запуске версия 2.0.* не установлена, зато установлена версия 2.2.2.When run, version 2.0.* is not installed, however, 2.2.2 is. Будет использоваться версия 2.2.2.Version 2.2.2 will be used.
  3. Позже пользователь устанавливает 2.0.5 и запускает приложение еще раз, теперь будет использоваться 2.0.5.Later, the user installs 2.0.5 and runs the application again, 2.0.5 will now be used.

Версии 2.0.5 и 2.2.2 могут вести себя по-разному, особенно в таких сценариях, как сериализация двоичных данных.It's possible that 2.0.5 and 2.2.2 behave differently, particularly for scenarios like serializing binary data.

Автономные развертывания включают выбранную среду выполненияSelf-contained deployments include the selected runtime

Вы можете опубликовать приложение как автономный дистрибутив.You can publish an application as a self-contained distribution. При таком подходе среда выполнения .NET Core и библиотеки объединяются с вашим приложением.This approach bundles the .NET Core runtime and libraries with your application. Автономные развертывания не зависят от среды выполнения.Self-contained deployments don't have a dependency on runtime environments. Выбор версии среды выполнения происходит во время публикации, а не запуска.Runtime version selection occurs at publishing time, not run time.

Процесс публикации выбирает последнюю версию исправления определенного семейства сред выполнения.The publishing process selects the latest patch version of the given runtime family. Например, dotnet publish выберет .NET Core 2.0.4, если это последняя версия исправления семейства среды выполнения .NET Core 2.0.For example, dotnet publish will select .NET Core 2.0.4 if it is the latest patch version in the .NET Core 2.0 runtime family. Целевая платформа (включая последние установленные обновления безопасности) упаковывается с приложением.The target framework (including the latest installed security patches) is packaged with the application.

Возникает ошибка, если минимальная версия, указанная для приложения, не предоставляется.It's an error if the minimum version specified for an application isn't satisfied. dotnet publish привязывает последнюю версию среды выполнения с исправлениями (без определенного семейства с основным и дополнительным номером версии).dotnet publish binds to the latest runtime patch version (within a given major.minor version family). dotnet publish не поддерживает семантику наката dotnet run.dotnet publish doesn't support the roll-forward semantics of dotnet run. Дополнительные сведения об исправлениях и автономных развертываниях см. в статье о выборе версии среды выполнения с исправлениями при развертывании приложений .NET Core.For more information about patches and self-contained deployments, see the article on runtime patch selection in deploying .NET Core applications.

Для автономных развертываний может потребоваться определенная версия исправления.Self-contained deployments may require a specific patch version. Минимальную версию среды выполнения с исправлениями можно переопределить (выбрав более позднюю или раннюю версию) в файле проекта, как показано в следующем примере:You can override the minimum runtime patch version (to higher or lower versions) in the project file, as shown in the following example:

<RuntimeFrameworkVersion>2.0.4</RuntimeFrameworkVersion>

Элемент RuntimeFrameworkVersion переопределяет политику версии по умолчанию.The RuntimeFrameworkVersion element overrides the default version policy. Для автономных развертываний RuntimeFrameworkVersion указывает точную версию платформы среды выполнения.For self-contained deployments, the RuntimeFrameworkVersion specifies the exact runtime framework version. Для платформозависимых приложений RuntimeFrameworkVersion указывает минимальную требуемую версию платформы среды выполнения.For framework-dependent applications, the RuntimeFrameworkVersion specifies the minimum required runtime framework version.