Переход с DNX на интерфейс CLI .NET Core (project.json)Migrating from DNX to .NET Core CLI (project.json)

ОбзорOverview

В версии-кандидате 1 .NET Core и ASP.NET Core 1.0 были представлены инструменты DNX.The RC1 release of .NET Core and ASP.NET Core 1.0 introduced DNX tooling. С выпуском версии-кандидата 2 .NET Core и ASP.NET Core 1.0 был осуществлен переход на интерфейс командной строки (CLI) .NET Core с DNX.The RC2 release of .NET Core and ASP.NET Core 1.0 moved from DNX to the .NET Core CLI.

Давайте в общих чертах вспомним, что такое DNX.As a slight refresher, let's recap what DNX was about. DNX — это среда выполнения и набор инструментов, которые использовались для создания приложений .NET Core, и в частности приложений ASP.NET Core 1.0.DNX was a runtime and a toolset used to build .NET Core and, more specifically, ASP.NET Core 1.0 applications. Это решение состояло из трех основных компонентов:It consisted of 3 main pieces:

  1. DNVM — скрипт установки для получения DNX;DNVM - an install script for obtaining DNX
  2. DNX (среда выполнения Dotnet) — среда выполнения вашего кода;DNX (Dotnet Execution Runtime) - the runtime that executes your code
  3. DNU (служебная программа для разработки Dotnet) — средство для управления зависимостями, сборки и публикации приложений.DNU (Dotnet Developer Utility) - tooling for managing dependencies, building and publishing your applications

С появлением интерфейса CLI все перечисленные выше компоненты входят в одни набор инструментов.With the introduction of the CLI, all of the above are now part of a single toolset. Однако, поскольку среда DNX была доступна в версии-кандидате 1, у вас могут быть созданные с ее помощью проекты, которые может потребоваться перенести в новый инструментарий CLI.However, since DNX was available in RC1 timeframe, you might have projects that were built using it that you would want to move off to the new CLI tooling.

В этом руководстве рассматриваются основные действия по переносу проектов из DNX в интерфейс CLI .NET Core.This migration guide will cover the essentials on how to migrate projects off of DNX and onto .NET Core CLI. Если вы создаете проект в .NET Core с нуля, то этот документ вам не нужен.If you are just starting a project on .NET Core from scratch, you can freely skip this document.

Основные изменения в инструментарииMain changes in the tooling

В инструментарии реализован ряд важных изменений, с которыми необходимо предварительно ознакомиться.There are some general changes in the tooling that should be outlined first.

Отсутствие DNVMNo more DNVM

DNVM (сокращение от DotNet Version Manager, диспетчер версий DotNet) — это bash-скрипт или скрипт PowerShell, который использовался для установки DNX на компьютере.DNVM, short for DotNet Version Manager was a bash/PowerShell script used to install a DNX on your machine. Он помогал пользователям получить DNX из указанного канала (или канала по умолчанию), а также пометить определенную среду DNX как активную, в результате чего она помещалась в переменную $PATH для данного сеанса.It helped users get the DNX they need from the feed they specified (or default ones) as well as mark a certain DNX "active", which would put it on the $PATH for the given session. Это позволяло использовать различные средства.This would allow you to use the various tools.

Поддержка DNVM прекращена, так как его функциональность стала избыточной вследствие изменений, реализованных в средствах CLI .NET Core.DNVM was discontinued because its feature set was made redundant by changes coming in the .NET Core CLI tools.

Средства CLI упаковываются двумя основными способами:The CLI tools come packaged in two main ways:

  1. собственные установщики для конкретной платформы;Native installers for a given platform
  2. скрипт установки для других ситуаций (например, серверов CI).Install script for other situations (like CI servers)

С учетом этого возможности установки DNVM больше не нужны.Given this, the DNVM install features are not needed. Но как насчет возможностей выбора среды выполнения?But what about the runtime selection features?

Вы ссылаетесь на среду выполнения в файле project.json, добавляя пакет определенной версии в список зависимостей.You reference a runtime in your project.json by adding a package of a certain version to your dependencies. После внесения этого изменения ваше приложение сможет использовать двоичные файлы новой среды выполнения.With this change, your application will be able to use the new runtime bits. Получение этих двоичных файлов на компьютере производится так же, как и при использовании CLI: вы устанавливаете среду выполнения с помощью одного из поддерживаемых собственных установщиков или посредством скрипта установки.Getting these bits to your machine is the same as with the CLI: you install the runtime via one of the native installers it supports or via its install script.

Разные командыDifferent commands

Если вы использовали среду DNX, то применяли некоторые команды из трех ее компонентов (DNX, DNU и DNVM).If you were using DNX, you used some commands from one of its three parts (DNX, DNU or DNVM). В CLI некоторые из этих команд изменились, некоторые стали недоступны, а другие сохранились, но имеют немного другую семантику.With the CLI, some of these commands change, some are not available and some are the same but have slightly different semantics.

В таблице ниже приведены команды DNX и DNU и их аналоги в CLI.The table below shows the mapping between the DNX/DNU commands and their CLI counterparts.

Команда DNXDNX command Команда CLICLI command ОписаниеDescription
dnx rundnx run dotnet rundotnet run Выполнение кода из источника.Run code from source.
dnu builddnu build dotnet builddotnet build Сборка двоичного файла с кодом на языке IL.Build an IL binary of your code.
dnu packdnu pack dotnet packdotnet pack Упаковка кода в пакет NuGet.Package up a NuGet package of your code.
dnx [команда] (например, dnx web)dnx [command] (for example, "dnx web") Н/Д *N/A* Выполнение команды в среде DNX в соответствии с определением в файле project.json.In DNX world, run a command as defined in the project.json.
dnu installdnu install Н/Д *N/A* В среде DNX установка пакета в качестве зависимости.In the DNX world, install a package as a dependency.
dnu restorednu restore dotnet restoredotnet restore Восстановление зависимостей, указанных в файле project.json.Restore dependencies specified in your project.json. (см. примечание)(see note)
dnu publishdnu publish dotnet publishdotnet publish Публикация приложения для развертывания в одной из трех форм (переносимое, переносимое с машинным кодом или автономное).Publish your application for deployment in one of the three forms (portable, portable with native and standalone).
dnu wrapdnu wrap Н/Д *N/A* В среде DNX упаковка файла project.json в файл CSPROJ.In DNX world, wrap a project.json in csproj.
dnu commandsdnu commands Н/Д *N/A* В среде DNX управление глобально установленными командами.In DNX world, manage the globally installed commands.

(*) — поддержка этих возможностей в CLI не предусмотрена.(*) - these features are not supported in the CLI by design.

Неподдерживаемые возможности DNXDNX features that are not supported

Как видно в приведенной выше таблице, в среде DNX имелись возможности, которые мы решили не поддерживать в CLI, по крайней мере на данный момент.As the table above shows, there are features from the DNX world that we decided not to support in the CLI, at least for the time being. В этом разделе будут рассмотрены наиболее важные из них, а также приведено обоснование прекращению их поддержки и обходные решения для их реализации.This section will go through the most important ones and outline the rationale behind not supporting them as well as workarounds if you do need them.

Глобальные командыGlobal commands

В DNU появилось такое понятие, как "глобальные команды".DNU came with a concept called "global commands". По существу, это консольные приложения, упакованные в виде пакетов NuGet со скриптом оболочки, который вызывает указанную среду DNX для запуска приложения.These were, essentially, console applications packaged up as NuGet packages with a shell script that would invoke the DNX you specified to run the application.

В интерфейсе CLI такого понятия нет.The CLI does not support this concept. Однако он поддерживает добавление команд для отдельных проектов, которые можно вызывать с помощью привычного синтаксиса dotnet <command>.It does, however, support the concept of adding per-project commands that can be invoked using the familiar dotnet <command> syntax.

Установка зависимостейInstalling dependencies

Начиная с версии 1, в средствах CLI .NET Core нет команды install для установки зависимостей.As of v1, the .NET Core CLI tools don't have an install command for installing dependencies. Чтобы установить пакет из NuGet, его нужно добавить как зависимость в файл project.json, а затем выполнить команду dotnet restore (см. примечание).In order to install a package from NuGet, you would need to add it as a dependency to your project.json file and then run dotnet restore (see note).

Выполнение кодаRunning your code

Выполнять код можно двумя основными способами.There are two main ways to run your code. Один из них — выполнение из источника с помощью команды dotnet run.One is from source, with dotnet run. В отличие от команды dnx run, компиляция в памяти при этом не производится.Unlike dnx run, this will not do any in-memory compilation. Эта команда вызывает dotnet build для сборки кода, а затем запускает собранный двоичный файл.It will actually invoke dotnet build to build your code and then run the built binary.

Другой способ — использовать сам драйвер dotnet для выполнения кода.Another way is using the dotnet itself to run your code. Для этого нужно указать путь к сборке: dotnet path/to/an/assembly.dll.This is done by providing a path to your assembly: dotnet path/to/an/assembly.dll.

Перенос проекта DNX в CLI .NET CoreMigrating your DNX project to .NET Core CLI

Помимо использования новых команд для работы с кодом, переход с DNX также требует выполнения еще трех важных действий:In addition to using new commands when working with your code, there are three major things left in migrating from DNX:

  1. перенос файла global.json, если он должен использовать CLI;Migrate the global.json file if you have it to be able to use CLI.
  2. перенос самого файла проекта (project.json) в инструментарий CLI;Migrating the project file (project.json) itself to the CLI tooling.
  3. переход с интерфейсов API среды DNX на их аналоги в BCL.Migrating off of any DNX APIs to their BCL counterparts.

Изменение файла global.jsonChanging the global.json file

Файл global.json выступает в роли файла решения как для проектов версии-кандидата 1, так и для проектов версии-кандидата 2 (или более поздней версии).The global.json file acts like a solution file for both the RC1 and RC2 (or later) projects. Для различения проектов версии-кандидата 1 и проектов более поздних версий средства CLI (а также Visual Studio) используют свойство "sdk": { "version" }.In order for the CLI tools (as well as Visual Studio) to differentiate between RC1 and later versions, they use the "sdk": { "version" } property to make the distinction which project is RC1 or later. Если в файле global.json вообще нет этого узла, предполагается, что проект относится к последней версии.If global.json doesn't have this node at all, it is assumed to be the latest.

Чтобы обновить файл global.json, удалите это свойство или задайте в качестве его значения точную версию средств, которую необходимо использовать. В данном случае это версия 1.0.0-preview2-003121:In order to update the global.json file, either remove the property or set it to the exact version of the tools that you wish to use, in this case 1.0.0-preview2-003121:

{
    "sdk": {
        "version": "1.0.0-preview2-003121"
    }
}

Перенос файл проектаMigrating the project file

Интерфейс CLI и среда DNX используют одну и ту же базовую систему проектов, основанную на файле project.json.The CLI and DNX both use the same basic project system based on project.json file. Синтаксис и семантика файла проекта в целом совпадают, за небольшими исключениями в некоторых ситуациях.The syntax and the semantics of the project file are pretty much the same, with small differences based on the scenarios. В схеме есть небольшие изменения. С ними можно ознакомиться в файле схемы.There are also some changes to the schema which you can see in the schema file.

Если вы создаете консольное приложение, в файл проекта нужно добавить следующий фрагмент кода:If you are building a console application, you need to add the following snippet to your project file:

"buildOptions": {
    "emitEntryPoint": true
}

Он предписывает команде dotnet build создать точку входа для приложения, что делает код готовым к выполнению.This instructs dotnet build to emit an entry point for your application, effectively making your code runnable. Если вы создаете библиотеку классов, просто опустите приведенный выше раздел.If you are building a class library, simply omit the above section. Само собой, после добавления приведенного выше фрагмента в файл project.json необходимо добавить статическую точку входа.Of course, once you add the above snippet to your project.json file, you need to add a static entry point. После перехода с DNX предоставляемые этой средой службы DI становятся недоступны, поэтому это должна быть базовая точка входа .NET: static void Main().With the move off DNX, the DI services it provided are no longer available and thus this needs to be a basic .NET entry point: static void Main().

Если в файле project.json есть раздел commands, его можно удалить.If you have a "commands" section in your project.json, you can remove it. Некоторые команды, которые существовали как команды DNU, например команды интерфейса CLI для Entity Framework, переносятся в CLI как расширения на уровне отдельных проектов.Some of the commands that used to exist as DNU commands, such as Entity Framework CLI commands, are being ported to be per-project extensions to the CLI. Если вы создали собственные команды, которые используете в проектах, то их надо заменить на расширения CLI.If you built your own commands that you are using in your projects, you need to replace them with CLI extensions. В этом случае узел commands в файле project.json нужно заменить на узел tools, в котором должны быть перечислены зависимости средств.In this case, the commands node in project.json needs to be replaced by the tools node and it needs to list the tools dependencies.

После выполнения этих действий необходимо решить, какой тип переносимости требуется для приложения.After these things are done, you need to decide which type of portability you wish for you app. В .NET Core мы реализовали целый спектр вариантов переносимости.With .NET Core, we have invested into providing a spectrum of portability options that you can choose from. Например, приложение может быть полностью переносимым или автономным.For instance, you may want to have a fully portable application or you may want to have a self-contained application. Переносимое приложение работает примерно так же, как приложение .NET Framework: ему требуется общий компонент для выполнения на целевом компьютере (.NET Core).The portable application option is more like .NET Framework applications work: it needs a shared component to execute it on the target machine (.NET Core). Автономное приложение не требует установки среды .NET Core на целевом компьютере, но для каждой поддерживаемой ОС необходимо создать отдельное приложение.The self-contained application doesn't require .NET Core to be installed on the target, but you have to produce one application for each OS you wish to support. Эти и другие типы переносимости рассматриваются в документе, посвященном типам переносимости приложений.These portability types and more are discussed in the application portability type document.

Выбрав нужный тип переносимости, необходимо изменить целевые платформы.Once you make a call on what type of portability you want, you need to change your targeted framework(s). Если вы создавали приложения для .NET Core, то, скорее всего, использовали dnxcore50 в качестве целевой платформы.If you were writing applications for .NET Core, you were most likely using dnxcore50 as your targeted framework. В контексте CLI и изменений, связанных с библиотекой .NET Standard, необходимо использовать одну из следующих платформ:With the CLI and the changes that the new .NET Standard brought, the framework needs to be one of the following:

  1. netcoreapp1.0 — если вы создаете приложения в .NET (включая приложения ASP.NET Core);- if you are writing applications on .NET Core (including ASP.NET Core applications)
  2. netstandard1.6 — если вы создаете библиотеки классов для .NET Core.- if you are writing class libraries for .NET Core

При использовании других целевых платформ dnx, например dnx451, их также необходимо изменить.If you are using other dnx targets, like dnx451 you will need to change those as well. dnx451 следует изменить на net451.should be changed to net451. Дополнительные сведения см. в разделе о .NET Standard.Please refer to the .NET Standard topic for more information.

Ваш файл project.json в основном готов.Your project.json is now mostly ready. Теперь нужно проверить список зависимостей и обновить их до более новых версий, особенно если вы используете зависимости ASP.NET Core.You need to go through your dependencies list and update the dependencies to their newer versions, especially if you are using ASP.NET Core dependencies. Если вы применяли отдельные пакеты для интерфейсов API BCL, то можете использовать пакет среды выполнения, как описано в документе, посвященном типам переносимости приложений.If you were using separate packages for BCL APIs, you can use the runtime package as explained in the application portability type document.

Когда вы будете готовы, можно попробовать выполнить восстановление с помощью команды dotnet restore (см. примечание).Once you are ready, you can try restoring with dotnet restore (see note). В зависимости от версии зависимостей могут возникнуть ошибки, если системе NuGet не удастся разрешить зависимости для одной из перечисленных выше целевых платформ.Depending on the version of your dependencies, you may encounter errors if NuGet cannot resolve the dependencies for one of the targeted frameworks above. Это временная проблема: со временем все большее число пакетов будет поддерживать эти платформы.This is a "point-in-time" problem; as time progresses, more and more packages will include support for these frameworks. Пока же вы можете использовать оператор imports в узле framework, чтобы сообщить системе NuGet, что она может восстановить указанные в этом операторе пакеты, предназначенные для соответствующей платформы.For now, if you run into this, you can use the imports statement within the framework node to specify to NuGet that it can restore the packages targeting the framework within the "imports" statement. В этом случае при возникновении ошибок восстановления вы должны получить достаточно информации, чтобы понять, какие платформы следует импортировать.The restoring errors you get in this case should provide enough information to tell you which frameworks you need to import. Если вы немного запутались в этом, то просто помните, что, как правило, указание платформ dnxcore50 и portable-net45+win8 в операторе imports позволяет добиться желаемого результата.If you are slightly lost or new to this, in general, specifying dnxcore50 and portable-net45+win8 in the imports statement should do the trick. В приведенном ниже фрагменте кода в формате JSON показано, как это должно выглядеть.The JSON snippet below shows how this looks like:

    "frameworks": {
        "netcoreapp1.0": {
            "imports": ["dnxcore50", "portable-net45+win8"]
        }
    }

При выполнении dotnet build будут выведены все итоговые ошибки сборки, хотя их не должно быть много.Running dotnet build will show any eventual build errors, though there shouldn't be too many of them. После того как код будет собран и будет правильно выполняться, вы можете протестировать его с помощью средства запуска.After your code is building and running properly, you can test it out with the runner. Выполните команду dotnet <path-to-your-assembly> и понаблюдайте за выполнением.Execute dotnet <path-to-your-assembly> and see it run.

Примечание

Начиная с пакета SDK для .NET Core 2.0 нет необходимости выполнять команду dotnet restore, так как она выполняется неявно всеми командами, которые требуют восстановления, например dotnet new, dotnet build и dotnet run.Starting with .NET Core 2.0 SDK, you don't have to run dotnet restore because it's run implicitly by all commands that require a restore to occur, such as dotnet new, dotnet build and dotnet run. Эту команду по-прежнему можно использовать в некоторых сценариях, где необходимо явное восстановление, например в сборках с использованием непрерывной интеграции в Azure DevOps Services или системах сборки, где требуется явно контролировать время восстановления.It's still a valid command in certain scenarios where doing an explicit restore makes sense, such as continuous integration builds in Azure DevOps Services or in build systems that need to explicitly control the time at which the restore occurs.