Migrieren von DNX zur .NET Core-CLI (project.json)Migrating from DNX to .NET Core CLI (project.json)

ÜbersichtOverview

Im RC1-Release von .NET Core und ASP.NET Core 1.0 wurde DNX eingeführt.The RC1 release of .NET Core and ASP.NET Core 1.0 introduced DNX tooling. Im RC2-Release von .NET Core und ASP.NET Core 1.0 wurde der Wechsel von DNX auf die NET Core-CLI vollzogen.The RC2 release of .NET Core and ASP.NET Core 1.0 moved from DNX to the .NET Core CLI.

Lassen Sie uns als kurze Auffrischung noch einmal zusammenfassen, worum es bei DNX ging.As a slight refresher, let's recap what DNX was about. DNX war eine Laufzeit und ein Toolset, das zum Erstellen von .NET Core und, genauer gesagt, ASP.NET Core 1.0-Anwendungen verwendet wurde.DNX was a runtime and a toolset used to build .NET Core and, more specifically, ASP.NET Core 1.0 applications. DNX bestand aus 3 Hauptteilen:It consisted of 3 main pieces:

  1. DNVM – ein Installationsskript zum Abrufen von DNXDNVM - an install script for obtaining DNX
  2. DNX (Dotnet Execution Runtime) – die Laufzeit, die Ihren Code ausführtDNX (Dotnet Execution Runtime) - the runtime that executes your code
  3. DNU (Dotnet Developer Utility) – Tools zum Verwalten von Abhängigkeiten, Erstellen und Veröffentlichen Ihrer AnwendungenDNU (Dotnet Developer Utility) - tooling for managing dependencies, building and publishing your applications

Mit der Einführung der CLI (command line interface, Befehlszeilenschnittstelle) sind alle oben genannten Teile jetzt Bestandteil eines einzigen Toolsets.With the introduction of the CLI, all of the above are now part of a single toolset. Nachdem DNX im RC1-Zeitrahmen verfügbar war, könnten Sie allerdings noch über Projekte verfügen, die mit DNX erstellt wurden, und die Sie möglicherweise zu den neuen CLI-Tools verschieben möchten.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.

Dieses Migrationshandbuch behandelt die Grundlagen, wie Sie Projekte weg von DNX und zur .NET Core-CLI migrieren können.This migration guide will cover the essentials on how to migrate projects off of DNX and onto .NET Core CLI. Wenn Sie ein Projekt auf .NET Core von Grund auf neu erstellen, können Sie dieses Dokument getrost überspringen.If you are just starting a project on .NET Core from scratch, you can freely skip this document.

Wichtigste Änderungen in den ToolsMain changes in the tooling

Es gibt einige allgemeine Änderungen in den Tools, die zuerst ausgeführt werden sollten.There are some general changes in the tooling that should be outlined first.

DNVM ist nicht mehr vorhandenNo more DNVM

DNVM, kurz für DotNet Version Manager war ein Bash/PowerShell-Skript mit dem ein DNX auf Ihrem Computer installiert wurde.DNVM, short for DotNet Version Manager was a bash/PowerShell script used to install a DNX on your machine. Benutzer konnten dadurch das benötigte DNX von einem von ihnen angegebenen Feed (oder Standard-Feeds) erhalten sowie ein bestimmtes DNX als „aktiv“ markieren, das $PATH für die jeweilige Sitzung als Umgebungsvariable setzte.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. Dies ermöglichte die Nutzung der verschiedenen Tools.This would allow you to use the various tools.

DNVM wurde eingestellt, da dessen Featuregruppe durch die geplanten Änderungen in den .NET Core-CLI-Tools überflüssig wurde.DNVM was discontinued because its feature set was made redundant by changes coming in the .NET Core CLI tools.

Die CLI-Tools können auf zwei Arten verpackt werden:The CLI tools come packaged in two main ways:

  1. Native Installationsprogramme für eine bestimmte PlattformNative installers for a given platform
  2. Installationsskript für andere Situationen (wie CI-Server)Install script for other situations (like CI servers)

Angesichts dessen werden die Installationsfeatures von DNVM nicht benötigt.Given this, the DNVM install features are not needed. Was ist aber mit den Features zur Auswahl von Laufzeiten?But what about the runtime selection features?

Sie verweisen auf eine Laufzeit in Ihrer project.json-Datei, indem Sie ein Paket einer bestimmten Version zu Ihren Abhängigkeiten hinzufügen.You reference a runtime in your project.json by adding a package of a certain version to your dependencies. Durch diese Änderung kann die Anwendung die neuen Laufzeit-Bits verwenden.With this change, your application will be able to use the new runtime bits. Diese Bits auf Ihren Computer zu verschieben ist der gleiche Prozess wie bei der CLI: Sie installieren die Laufzeit über eines der unterstützten nativen Installationsprogramme oder das Installationsskript.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.

Unterschiedliche BefehleDifferent commands

Wenn Sie DNX verwendet haben, haben Sie bisher einige Befehle aus einem der drei Teile genutzt (DNX, DNU oder DNVM).If you were using DNX, you used some commands from one of its three parts (DNX, DNU or DNVM). Mit der CLI ändern sich manche dieser Befehle, manche sind nicht mehr verfügbar und manche bleiben gleich, verfügen jedoch über eine etwas andere Semantik.With the CLI, some of these commands change, some are not available and some are the same but have slightly different semantics.

Die folgende Tabelle stellt die Zuordnung zwischen DNX-/DNU-Befehlen und ihren CLI-Gegenstücken dar.The table below shows the mapping between the DNX/DNU commands and their CLI counterparts.

DNX-BefehlDNX command CLI-BefehlCLI command BeschreibungDescription
dnx rundnx run dotnet rundotnet run Code aus Quelle ausführen.Run code from source.
dnu builddnu build dotnet builddotnet build Erstellen einer IL-Binärdatei des Codes.Build an IL binary of your code.
dnu packdnu pack dotnet packdotnet pack Verpacken eines NuGet-Pakets Ihres Codes.Package up a NuGet package of your code.
dnx [command] (z.B. „dnx web“)dnx [command] (for example, "dnx web") NICHT VERFÜGBAR*N/A* In DNX, Ausführen eines Befehls wie in der Datei „project.json“ definiert.In DNX world, run a command as defined in the project.json.
dnu installdnu install NICHT VERFÜGBAR*N/A* In DNX, Installieren eines Pakets als Abhängigkeit.In the DNX world, install a package as a dependency.
dnu restorednu restore dotnet restoredotnet restore Wiederherstellen von Abhängigkeiten, die in der Datei „project.json“ angegeben sind.Restore dependencies specified in your project.json. (Siehe Hinweis)(see note)
dnu publishdnu publish dotnet publishdotnet publish Veröffentlichen Ihrer Anwendung für die Bereitstellung in einer der drei Formen (portabel, portabel-nativ und eigenständig).Publish your application for deployment in one of the three forms (portable, portable with native and standalone).
dnu wrapdnu wrap NICHT VERFÜGBAR*N/A* In DNX, Umschließen von „project.json“ in „csproj“.In DNX world, wrap a project.json in csproj.
dnu commandsdnu commands NICHT VERFÜGBAR*N/A* In DNX, Verwalten der global installierten Befehle.In DNX world, manage the globally installed commands.

(*) – diese Features werden in der CLI nicht unterstützt (dies ist beabsichtigt).(*) - these features are not supported in the CLI by design.

DNX-Features, die nicht unterstützt werdenDNX features that are not supported

Wie in der obigen Tabelle gezeigt, gibt es Features in DNX, die absichtlich nicht in der CLI unterstützt werden, zumindest für den Moment.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. In diesem Abschnitt werden die wichtigsten Features aufgezählt und die Gründe, warum diese nicht unterstützt werden, beschrieben. Außerdem wird beschrieben, wie Sie dies umgehen können, falls Sie die Features benötigen.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.

Globale BefehleGlobal commands

In DNU war ein Konzept namens „globale Befehle“ enthalten.DNU came with a concept called "global commands". Im Wesentlichen waren dies Konsolenanwendungen, die als NuGet Pakete mit einem Shell-Skript verpackt waren, und das angegebene DNX aufriefen, die Sie zum Ausführen der Anwendung angegeben hatten.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.

Dieses Konzept wird in CLI nicht unterstützt.The CLI does not support this concept. CLI unterstützt jedoch das Konzept, Befehle pro Projekt hinzuzufügen, die mithilfe der bekannten Syntax dotnet <command> aufgerufen werden können.It does, however, support the concept of adding per-project commands that can be invoked using the familiar dotnet <command> syntax.

Installieren von AbhängigkeitenInstalling dependencies

Seit V1 verfügen die .NET Core-CLI-Tools nicht mehr über einen Befehl install für das Installieren von Abhängigkeiten.As of v1, the .NET Core CLI tools don't have an install command for installing dependencies. Um ein Paket von NuGet zu installieren, müssen Sie es als eine Abhängigkeit hinzufügen Ihrer project.json Datei, und führen Sie dotnet restore (Siehe Hinweis).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).

Ausführen des CodesRunning your code

Im Wesentlichen gibt es zwei Möglichkeiten, den Code auszuführen.There are two main ways to run your code. Eine Möglichkeit ist das Ausführen von der Quelle mit dem Befehl dotnet run.One is from source, with dotnet run. Im Gegensatz zu dnx run führt dieser keine Kompilierung im Speicher durch.Unlike dnx run, this will not do any in-memory compilation. Stattdessen wird dotnet build aufgerufen, um den Code zu erstellen und dann die erstellte Binärdatei auszuführen.It will actually invoke dotnet build to build your code and then run the built binary.

Eine andere Möglichkeit ist das Verwenden von dotnet selbst zum Ausführen des Codes.Another way is using the dotnet itself to run your code. Dies erfolgt durch das Bereitstellen eines Pfads zu Ihrer Assembly: dotnet path/to/an/assembly.dll.This is done by providing a path to your assembly: dotnet path/to/an/assembly.dll.

Migrieren Ihres DNX-Projekts zur .NET Core-CLIMigrating your DNX project to .NET Core CLI

Zusätzlich zur Nutzung von neuen Befehlen, wenn Sie mit Code arbeiten, gibt es noch drei weitere wichtige Punkte beim Migrieren von DNX:In addition to using new commands when working with your code, there are three major things left in migrating from DNX:

  1. Migrieren Sie die Datei global.json (wenn diese vorhanden ist) um CLI (Command Line Interface, Befehlszeilenschnittstelle) verwenden zu können.Migrate the global.json file if you have it to be able to use CLI.
  2. Migrieren der Projektdatei (project.json) selbst zu den CLI-Tools.Migrating the project file (project.json) itself to the CLI tooling.
  3. Migrieren weg von beliebigen DNX-APIs zu ihren BLC-Entsprechungen.Migrating off of any DNX APIs to their BCL counterparts.

Ändern der Datei „global.json“Changing the global.json file

Die Datei global.json verhält sich wie eine Projektmappendatei für RC1- und RC2- Projekte (oder höhere).The global.json file acts like a solution file for both the RC1 and RC2 (or later) projects. Damit die CLI-Tools (wie auch Visual Studio) zwischen RC1 und höheren Versionen unterscheiden können, verwenden sie die Eigenschaft "sdk": { "version" }, um zu unterscheiden, welches Projekt RC1 oder höher ist.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. Wenn global.json nicht über diesen Knoten verfügt, wird davon ausgegangen, dass die höchste Version verwendet wird.If global.json doesn't have this node at all, it is assumed to be the latest.

Entfernen Sie entweder die Eigenschaft, um die Datei global.json zu aktualisieren, oder stellen Sie sie auf die genaue Version der Tools ein, die Sie verwenden möchten, in diesem Fall 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"
    }
}

Migrieren der ProjektdateiMigrating the project file

Die CLI und DNX verwenden dasselbe grundlegende Projektsystem basierend auf der Datei project.json.The CLI and DNX both use the same basic project system based on project.json file. Die Syntax und Semantik der Projektdatei sind weitgehend identisch, abgesehen von kleinen Unterschieden abhängig von den Szenarios.The syntax and the semantics of the project file are pretty much the same, with small differences based on the scenarios. Es gibt auch einige Änderungen am Schema, die Sie in der Schemadatei einsehen können.There are also some changes to the schema which you can see in the schema file.

Wenn Sie eine Konsolenanwendung erstellen, müssen Sie den folgenden Ausschnitt zu Ihrer Projektdatei hinzufügen:If you are building a console application, you need to add the following snippet to your project file:

"buildOptions": {
    "emitEntryPoint": true
}

Dies weist dotnet build an, einen Einstiegspunkt für Ihre Anwendung auszugeben, und macht Ihren Code dadurch ausführbar.This instructs dotnet build to emit an entry point for your application, effectively making your code runnable. Wenn Sie eine Klassenbibliothek erstellen, lassen Sie einfach den obigen Abschnitt aus.If you are building a class library, simply omit the above section. Sobald Sie den oben angezeigten Ausschnitt zu Ihrer Datei project.json hinzugefügt haben, müssen Sie natürlich einen statischen Einstiegspunkt hinzufügen.Of course, once you add the above snippet to your project.json file, you need to add a static entry point. Mit dem Wechsel weg von DNX sind die DI-Dienste nicht mehr verfügbar, deswegen muss ein einfacher .NET-Einstiegspunkt hinzugefügt werden: 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().

Wenn sich ein Abschnitt „commands“ in Ihrer Datei project.json befindet, können Sie ihn entfernen.If you have a "commands" section in your project.json, you can remove it. Manche der Befehle, die es als DNU-Befehle gab, zum Beispiel Entity Framework-CLI-Befehle, werden als pro Projekt-Erweiterung in die CLI portiert.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. Falls Sie eigene Befehle erstellt haben, die Sie in Ihren Projekten verwenden, müssen Sie diese mit der CLI-Erweiterung ersetzen.If you built your own commands that you are using in your projects, you need to replace them with CLI extensions. In diesem Fall muss der Knoten commands in der Datei project.json durch den Knoten tools ersetzt werden, und muss die Tool-Abhängigkeiten auflisten.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.

Nachdem diese Schritte abgeschlossen sind, müssen Sie entscheiden, über welche Art von Portabilität Ihre App verfügen soll.After these things are done, you need to decide which type of portability you wish for you app. Wir haben mit .NET Core darin investiert, Ihnen eine Bandbreite von Optionen zur Portabilität anzubieten, aus denen Sie auswählen können.With .NET Core, we have invested into providing a spectrum of portability options that you can choose from. Sie können zum Beispiel zwischen einer voll portablen Anwendung oder einer eigenständigen Anwendung wählen.For instance, you may want to have a fully portable application or you may want to have a self-contained application. Die Option für die portable Anwendung entspricht eher der Arbeitsweise von .NET Framework-Anwendungen: Sie benötigt eine freigegebene Komponente, um sie auf dem Zielcomputer (.NET Core) auszuführen.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). Bei der eigenständigen Anwendung muss .NET Core nicht auf dem Zielcomputer installiert werden. Sie müssen allerdings für jedes Betriebssystem, das Sie unterstützen möchten, eine Anwendung erzeugen.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. Genauere Informationen zu diesen und weiteren Arten der Portabilität finden Sie im Dokument application portability type (Typen der Portabilität von Anwendungen) .These portability types and more are discussed in the application portability type document.

Sobald Sie sich für eine Art der Portabilität entschieden haben, müssen Sie Ihr(e) Zielframework(s) ändern.Once you make a call on what type of portability you want, you need to change your targeted framework(s). Wenn Sie Anwendungen für .NET Core geschrieben haben, haben Sie wahrscheinlich dnxcore50 als Zielframework verwendet.If you were writing applications for .NET Core, you were most likely using dnxcore50 as your targeted framework. Aufgrund der CLI und der Änderungen durch den neuen .NET-Standard muss eines der folgenden Frameworks verwendet werden:With the CLI and the changes that the new .NET Standard brought, the framework needs to be one of the following:

  1. netcoreapp1.0 – wenn Sie Anwendungen in .NET Core (einschließlich ASP.NET Core-Anwendungen) schreibennetcoreapp1.0 - if you are writing applications on .NET Core (including ASP.NET Core applications)
  2. netstandard1.6 – wenn Sie Klassenbibliotheken für .NET Core schreibennetstandard1.6 - if you are writing class libraries for .NET Core

Wenn Sie andere dnx-Ziele verwenden, wie z.B. dnx451, müssen diese ebenfalls geändert werden.If you are using other dnx targets, like dnx451 you will need to change those as well. dnx451 sollte in net451 geändert werden.dnx451 should be changed to net451. Weitere Informationen finden Sie im Thema .NET Standard.Please refer to the .NET Standard topic for more information.

Ihre Datei project.json ist nun weitgehend bereit.Your project.json is now mostly ready. Sie müssen nun Ihre Liste der Abhängigkeiten durchgehen und die Abhängigkeiten auf deren neuere Versionen aktualisieren, besonders, wenn Sie Abhängigkeiten von ASP.NET Core verwenden.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. Wenn Sie separate Pakete für BLC APIs verwenden, können Sie das Laufzeitpaket verwenden, wie im Dokument application portability type (Arten der Portabilität von Anwendungen) erklärt.If you were using separate packages for BCL APIs, you can use the runtime package as explained in the application portability type document.

Sobald Sie bereit sind, können Sie versuchen, eine Wiederherstellung mit dotnet restore (Siehe Hinweis).Once you are ready, you can try restoring with dotnet restore (see note). Je nach Version Ihrer Abhängigkeiten könnten Fehler auftreten, wenn NuGet die Abhängigkeiten für eines der oben genannten Zielframeworks nicht lösen kann.Depending on the version of your dependencies, you may encounter errors if NuGet cannot resolve the dependencies for one of the targeted frameworks above. Dies ist ein „Zeitpunkt“-Problem; im Lauf der Zeit werden immer mehr Pakete eine Unterstützung dieser Frameworks bieten.This is a "point-in-time" problem; as time progresses, more and more packages will include support for these frameworks. Wenn dieses Problem auftritt, können Sie vorläufig die Anweisung imports innerhalb des Knotens framework verwenden, um NuGet mitzuteilen, dass es die Pakete, die das Framework als Ziel haben, innerhalb der „imports“-Anweisung wiederherstellen kann.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. Die Fehler beim Wiederherstellen, die in diesem Fall auftreten, sollten genügend Informationen bereitstellen, damit Sie entscheiden können, welches Framework Sie importieren müssen.The restoring errors you get in this case should provide enough information to tell you which frameworks you need to import. Wenn Sie sich hiermit nicht auskennen behebt normalerweise auch das Angeben von dnxcore50 und portable-net45+win8 in der imports-Anweisung das Problem.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. Der folgende JSON-Ausschnitt zeigt, wie dies aussieht:The JSON snippet below shows how this looks like:

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

Das Ausführen von dotnet build zeigt mögliche Buildfehler an, auch wenn es nicht zu viele geben sollte.Running dotnet build will show any eventual build errors, though there shouldn't be too many of them. Wenn Ihr Code ordnungsgemäß erstellt und ausgeführt wird, können Sie ihn ohne Runner testen.After your code is building and running properly, you can test it out with the runner. Führen Sie dotnet <path-to-your-assembly> aus, und beobachten Sie die Ausführung.Execute dotnet <path-to-your-assembly> and see it run.

Hinweis

Starting with .NET Core 2.0, you don't have to run dotnet restore because it's run implicitly by all commands, such as dotnet build and dotnet run, that require a restore to occur. It's still a valid command in certain scenarios where doing an explicit restore makes sense, such as continuous integration builds in Visual Studio Team Services or in build systems that need to explicitly control the time at which the restore occurs.