Migración de DNX a CLI de .NET Core (project.json)Migrating from DNX to .NET Core CLI (project.json)

Información generalOverview

Con la versión RC1 de .NET Core y ASP.NET Core 1.0, presentamos las herramientas DNX.The RC1 release of .NET Core and ASP.NET Core 1.0 introduced DNX tooling. Con la versión RC2 de .NET Core y ASP.NET Core 1.0, hicimos la transición de DNX a .NET Core CLI.The RC2 release of .NET Core and ASP.NET Core 1.0 moved from DNX to the .NET Core CLI.

Resumamos un poco de qué se trata DNX como un breve recordatorio.As a slight refresher, let's recap what DNX was about. DNX era un entorno de ejecución y un conjunto de herramientas para compilar aplicaciones de .NET Core y, más específicamente, de 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. Constaba de 3 componentes principales:It consisted of 3 main pieces:

  1. DNVM: un script de instalación para obtener DNX.DNVM - an install script for obtaining DNX
  2. DNX (entorno de ejecución Dotnet): el entorno de ejecución que ejecuta el código.DNX (Dotnet Execution Runtime) - the runtime that executes your code
  3. DNU (utilidad para desarrolladores de Dotnet): herramientas para administrar dependencias y compilar y publicar las aplicaciones.DNU (Dotnet Developer Utility) - tooling for managing dependencies, building and publishing your applications

Con la presentación de la CLI, todos los componentes anteriores ahora forman parte de un conjunto de herramientas único.With the introduction of the CLI, all of the above are now part of a single toolset. Sin embargo, como DNX estaba disponible en el período de tiempo de RC1, es posible que tenga proyectos que se compilaron así que desearía mover a las nuevas herramientas de 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.

En esta guía de migración se analizarán los aspectos fundamentales sobre cómo migrar proyectos de DNX a la CLI de .NET Core.This migration guide will cover the essentials on how to migrate projects off of DNX and onto .NET Core CLI. Si recién está comenzando un proyecto en .NET Core desde cero, puede omitir sin problemas este documento.If you are just starting a project on .NET Core from scratch, you can freely skip this document.

Principales cambios en las herramientasMain changes in the tooling

En primer lugar, es necesario describir algunos cambios generales en las herramientas.There are some general changes in the tooling that should be outlined first.

No más DNVMNo more DNVM

DNVM, abreviatura para el inglés de Administrador de versiones DotNet era un script de PowerShell/búsqueda intensiva que se usaba para instalar un DNX en la máquina.DNVM, short for DotNet Version Manager was a bash/PowerShell script used to install a DNX on your machine. Ayudó a los usuarios a obtener el DNX que necesitaban a partir de la fuente que especificaban (o la fuente predeterminada), además de marcar cierto DNX como "activo", lo que lo ubicaría en la $PATH de la sesión especificada.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. Esto le permitiría usar las diversas herramientas.This would allow you to use the various tools.

DNVM se interrumpió porque su conjunto de características se volvió redundante debido a los cambios introducidos con las herramientas de la CLI de .NET Core.DNVM was discontinued because its feature set was made redundant by changes coming in the .NET Core CLI tools.

Las herramientas de la CLI vienen empaquetadas de dos maneras principales:The CLI tools come packaged in two main ways:

  1. Instaladores nativos en una plataforma determinada.Native installers for a given platform
  2. Script de instalación para otras situaciones (como los servidores de CI).Install script for other situations (like CI servers)

Por lo tanto, no se necesitan las características de instalación de DNVM.Given this, the DNVM install features are not needed. ¿Qué sucede, entonces, con las características de selección del entorno de ejecución?But what about the runtime selection features?

Si agrega un paquete de cierta versión a las dependencias, hace referencia a un entorno de ejecución en su project.json.You reference a runtime in your project.json by adding a package of a certain version to your dependencies. Con este cambio, la aplicación podrá usar los nuevos bits de entorno de ejecución.With this change, your application will be able to use the new runtime bits. Incorporar estos bits a la máquina es similar a lo que sucede con la CLI: instala el entorno de ejecución a través de los instaladores nativos que admite o a través del script de instalación.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.

Otros comandosDifferent commands

Si usó DNX, usaba algunos comandos provenientes de uno de sus tres componentes (DNX, DNU o DNVM).If you were using DNX, you used some commands from one of its three parts (DNX, DNU or DNVM). Con la CLI, algunos de estos comandos cambian, algunos no están disponibles y otros son iguales, pero con pequeñas diferencias semánticas.With the CLI, some of these commands change, some are not available and some are the same but have slightly different semantics.

La tabla siguiente muestra la asignación entre los comandos de DNX/DNU y sus contrapartes de la CLI.The table below shows the mapping between the DNX/DNU commands and their CLI counterparts.

Comando de DNXDNX command Comando de la CLICLI command DescripciónDescription
dnx rundnx run dotnet rundotnet run Ejecute el código desde el origen.Run code from source.
dnu builddnu build dotnet builddotnet build Compile un archivo binario de IL del código.Build an IL binary of your code.
dnu packdnu pack dotnet packdotnet pack Cree un paquete NuGet del código.Package up a NuGet package of your code.
dnx [comando] (por ejemplo, "dnx web")dnx [command] (for example, "dnx web") no disponible*N/A* Si se usa DNX, ejecute un comando según lo definido en project.json.In DNX world, run a command as defined in the project.json.
dnu installdnu install no disponible*N/A* Si se usa DNX, instale un paquete como dependencia.In the DNX world, install a package as a dependency.
dnu restorednu restore dotnet restoredotnet restore Restaure las dependencias especificadas en project.json.Restore dependencies specified in your project.json. (vea la nota)(see note)
dnu publishdnu publish dotnet publishdotnet publish Publique la aplicación para su implementación en una de tres formas (portátil, portátil con nativo e independiente).Publish your application for deployment in one of the three forms (portable, portable with native and standalone).
dnu wrapdnu wrap no disponible*N/A* Si se usa DNX, encapsule un archivo project.json en csproj.In DNX world, wrap a project.json in csproj.
dnu commandsdnu commands no disponible*N/A* Si se usa DNX, administre los comandos instalados globalmente.In DNX world, manage the globally installed commands.

(*): por diseño, la CLI no admite estas características.(*) - these features are not supported in the CLI by design.

Características de DNX no admitidasDNX features that are not supported

Tal como muestra la tabla anterior, hay características de DNX que decidimos no admitir en la CLI, al menos por el momento.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. En esta sección se analizarán las más importantes y se describe el razonamiento detrás de la decisión de no admitirlas, además de las soluciones que puede implementar si las necesita.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.

Comandos globalesGlobal commands

DNU incluía un concepto llamado "comandos globales".DNU came with a concept called "global commands". En esencia, se trataba de aplicaciones de consola empaquetadas como paquetes NuGet con un script de shell que podría invocar el DNX especificado para ejecutar la aplicación.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.

La CLI no admite este concepto.The CLI does not support this concept. Sin embargo, sí admite el concepto de agregar comandos por proyecto que se pueden invocar con la conocida sintaxis dotnet <command>.It does, however, support the concept of adding per-project commands that can be invoked using the familiar dotnet <command> syntax.

Instalación de dependenciasInstalling dependencies

A partir de la versión v1, las herramientas de la CLI de .NET Core no tienen un comando install para instalar dependencias.As of v1, the .NET Core CLI tools don't have an install command for installing dependencies. Para instalar un paquete desde NuGet, necesita agregarlo como una dependencia al archivo project.json y, luego, ejecutar dotnet restore (vea la nota).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).

Ejecución del códigoRunning your code

Existen dos formas principales de ejecutar el código.There are two main ways to run your code. Una es desde el origen, con dotnet run.One is from source, with dotnet run. A diferencia de dnx run, no hará ninguna compilación en memoria.Unlike dnx run, this will not do any in-memory compilation. En realidad, invocará a dotnet build para compilar el código y, luego, ejecutar el archivo binario compilado.It will actually invoke dotnet build to build your code and then run the built binary.

La otra forma es usar el dotnet mismo para ejecutar el código.Another way is using the dotnet itself to run your code. Para ello, proporcione una ruta de acceso al ensamblado: dotnet path/to/an/assembly.dll.This is done by providing a path to your assembly: dotnet path/to/an/assembly.dll.

Migración del proyecto DNX a la CLI de .NET CoreMigrating your DNX project to .NET Core CLI

Además de usar los comandos nuevos cuando se trabaja con el código, hay 3 aspectos importantes que se dejaron en la migración desde DNX:In addition to using new commands when working with your code, there are three major things left in migrating from DNX:

  1. Si lo tiene, migre el archivo global.json para usar la CLI.Migrate the global.json file if you have it to be able to use CLI.
  2. Migración del archivo del proyecto (project.json) mismo a las herramientas de la CLI.Migrating the project file (project.json) itself to the CLI tooling.
  3. Migración de cualquier API de DNX a sus contrapartes de BCL.Migrating off of any DNX APIs to their BCL counterparts.

Cambio del archivo global.jsonChanging the global.json file

El archivo global.json actúa como un archivo de solución tanto para los proyectos de RC1 como para los de RC2 (o posteriores).The global.json file acts like a solution file for both the RC1 and RC2 (or later) projects. A fin de que las herramientas de la CLI (como también Visual Studio) diferencien entre RC1 y las versiones posteriores, usan la propiedad "sdk": { "version" } para hacer la distinción entre qué proyecto es RC1 o posterior.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. Si global.json no tiene este nodo, se supone que es la versión más reciente.If global.json doesn't have this node at all, it is assumed to be the latest.

Con el fin de actualizar el archivo global.json, quite la propiedad o establézcala en la versión exacta de las herramientas que desea usar; en este caso, 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"
    }
}

Migración del archivo del proyectoMigrating the project file

Tanto la CLI como DNX usan el mismo sistema de proyectos básico basado en el archivo project.json.The CLI and DNX both use the same basic project system based on project.json file. La sintaxis y la semántica del archivo del proyecto son prácticamente iguales, con pequeñas diferencias en función de los escenarios.The syntax and the semantics of the project file are pretty much the same, with small differences based on the scenarios. También hay algunos cambios en el esquema que puede ver en el archivo del esquema.There are also some changes to the schema which you can see in the schema file.

Si compila una aplicación de consola, debe agregar el siguiente fragmento de código al archivo del proyecto:If you are building a console application, you need to add the following snippet to your project file:

"buildOptions": {
    "emitEntryPoint": true
}

Esto indica a dotnet build que emita un punto de entrada para la aplicación, lo que permitirá que el código se pueda ejecutar.This instructs dotnet build to emit an entry point for your application, effectively making your code runnable. Si compila una biblioteca de clases, simplemente debe omitir la sección anterior.If you are building a class library, simply omit the above section. Por supuesto, una vez que agregue el fragmento de código anterior al archivo project.json, deberá agregar un punto de entrada estático.Of course, once you add the above snippet to your project.json file, you need to add a static entry point. Con la migración de DNX, los servicios de DI que proporcionaba ya no están disponibles y, por lo tanto, debe tratarse de un punto de entrada .NET básico: 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().

Si tiene una sección de "comandos" en su project.json, puede quitarla.If you have a "commands" section in your project.json, you can remove it. Algunos de los comandos que existían como comandos de DNU, como los comandos de la CLI de Entity Framework, se trasladan para convertirse en extensiones por proyecto en la 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. Si compila sus propios comandos que usa en los proyectos, debe reemplazarlos con extensiones de la CLI.If you built your own commands that you are using in your projects, you need to replace them with CLI extensions. En este caso, el nodo commands de project.json debe reemplazarse por el nodo tools y se deben enumerar las dependencias de herramientas.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.

Una vez hecho esto, deberá decidir qué tipo de portabilidad desea para la aplicación.After these things are done, you need to decide which type of portability you wish for you app. Con .NET Core, invertimos en proporcionar un espectro de opciones de portabilidad entre las que puede elegir.With .NET Core, we have invested into providing a spectrum of portability options that you can choose from. Por ejemplo, podría tener una aplicación completamente portátil, o bien podría querer tener una aplicación autocontenida.For instance, you may want to have a fully portable application or you may want to have a self-contained application. La opción de la aplicación portátil es más similar a cómo funcionan las aplicaciones de .NET Framework: necesita un componente compartido para ejecutarlo en la máquina de destino (.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). La aplicación autocontenida no requiere que .NET Core esté instalado en el destino, pero es necesario generar una aplicación para cada SO que desea admitir.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. Estos tipos de portabilidad, y otros más, se analizan en el documento sobre los tipos de portabilidad de aplicaciones.These portability types and more are discussed in the application portability type document.

Una vez que decide el tipo de portabilidad que desea, deberá cambiar las plataformas de destino.Once you make a call on what type of portability you want, you need to change your targeted framework(s). Si escribiera aplicaciones para .NET Core, es probable que use dnxcore50 como la plataforma de destino.If you were writing applications for .NET Core, you were most likely using dnxcore50 as your targeted framework. Con la CLI y los cambios que trajo la nueva especificación .NET Standard, la plataforma debe ser una de las siguientes:With the CLI and the changes that the new .NET Standard brought, the framework needs to be one of the following:

  1. netcoreapp1.0, si escribe aplicaciones en .NET Core (incluidas las aplicaciones de ASP.NET Core).netcoreapp1.0 - if you are writing applications on .NET Core (including ASP.NET Core applications)
  2. netstandard1.6, si escribe las bibliotecas de clases para .NET Core.netstandard1.6 - if you are writing class libraries for .NET Core

Si usa otros destinos dnx, como dnx451, también deberá cambiarlos.If you are using other dnx targets, like dnx451 you will need to change those as well. dnx451se debe cambiar a net451.dnx451 should be changed to net451. Consulte el tema Estándar .NET para obtener más información.Please refer to the .NET Standard topic for more information.

El archivo project.json está casi listo.Your project.json is now mostly ready. Debe revisar la lista de dependencias y actualizarlas a sus versiones más recientes, especialmente si usa las dependencias de 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. Si usará los paquetes independientes para las API de BCL, puede usar el paquete del entorno de ejecución tal como se explica en el documento sobre los tipos de portabilidad de aplicaciones.If you were using separate packages for BCL APIs, you can use the runtime package as explained in the application portability type document.

Cuando esté listo, puede intentar la restauración con dotnet restore (vea la nota).Once you are ready, you can try restoring with dotnet restore (see note). En función de la versión de las dependencias, puede encontrar errores si NuGet no puede resolver las dependencias de una de las plataformas de destino anteriormente mencionadas.Depending on the version of your dependencies, you may encounter errors if NuGet cannot resolve the dependencies for one of the targeted frameworks above. Este es un problema "en un momento específico"; a medida que pase el tiempo, cada vez más paquetes incluirán compatibilidad con estos marcos de trabajo.This is a "point-in-time" problem; as time progresses, more and more packages will include support for these frameworks. Por ahora, si se enfrenta con este problema, puede usar la instrucción imports dentro del nodo framework para especificar a NuGet que puede restaurar los paquetes que tienen como destino el marco de trabajo que se encuentra dentro de la instrucción de "importaciones".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. Los errores de restauración que recibe en este caso deben proporcionar información suficiente que le permita distinguir los marcos de trabajo que debe importar.The restoring errors you get in this case should provide enough information to tell you which frameworks you need to import. Si está un poco confundido o es nuevo en esto, en palabras generales, bastaría con especificar dnxcore50 y portable-net45+win8 en la instrucción 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. El fragmento de código JSON siguiente muestra cómo se verá:The JSON snippet below shows how this looks like:

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

La ejecución de dotnet build mostrará cualquier posible error de compilación, aunque no debería haber muchos.Running dotnet build will show any eventual build errors, though there shouldn't be too many of them. Una vez que el código se compile y ejecute correctamente, puede probarlo con el ejecutor.After your code is building and running properly, you can test it out with the runner. Ejecute dotnet <path-to-your-assembly> y vea si se ejecuta correctamente.Execute dotnet <path-to-your-assembly> and see it run.

Nota

A partir del SDK de .NET Core 2.0, no es necesario ejecutar dotnet restore porque lo ejecutan implícitamente todos los comandos que requieren que se produzca una restauración, como dotnet new, dotnet build y 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. Sigue siendo un comando válido en algunos escenarios donde tiene sentido realizar una restauración explícita, como las compilaciones de integración continua en Azure DevOps Services o en los sistemas de compilación que necesitan controlar explícitamente la hora a la que se produce la restauración.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.