Migrieren von .NET Core-Projekten in das .csproj-FormatMigrating .NET Core projects to the .csproj format

Dieses Dokument behandelt Migrationsszenarios für .NET Core-Projekte und die folgenden drei Migrationsszenarios:This document will cover migration scenarios for .NET Core projects and will go over the following three migration scenarios:

  1. Migration von einem gültigen neuesten Schema von project.json zu csprojMigration from a valid latest schema of project.json to csproj
  2. Migration von DNX zu csprojMigration from DNX to csproj
  3. Migration von RC3 und früheren .NET Core csproj-Projekten in das endgültige FormatMigration from RC3 and previous .NET Core csproj projects to the final format

Migration von project.json zu csprojMigration from project.json to csproj

Die Migration von project.json zu csproj kann mithilfe einer der folgenden Methoden erfolgen:Migration from project.json to .csproj can be done using one of the following methods:

Beide Methoden verwenden das gleiche zugrunde liegende Modul, um die Projekte zu migrieren, sodass die Ergebnisse bei beiden gleich sind.Both methods use the same underlying engine to migrate the projects, so the results will be the same for both. In den meisten Fällen genügt eine der folgenden beiden Methoden zum Migrieren von project.json zu csproj und es ist keine weitere manuelle Bearbeitung der Projektdatei erforderlich.In most cases, using one of these two ways to migrate the project.json to csproj is the only thing that is needed and no further manual editing of the project file is necessary. Die resultierende .csproj-Datei erhält denselben Namen wie das Verzeichnis, in dem sie enthalten ist.The resulting .csproj file will be named the same as the containing directory name.

Visual Studio 2017Visual Studio 2017

Beim Öffnen einer .xproj-Datei oder einer Projektmappendatei, die auf .xproj-Dateien verweist, wird das Dialogfeld Unidirektionales Upgrade angezeigt.When you open a .xproj file or a solution file which references .xproj files, the One-way upgrade dialog appears. Das Dialogfeld zeigt die Projekte, die migriert werden sollen.The dialog displays the projects to be migrated. Wenn Sie eine Projektmappendatei öffnen, werden alle Projekte aufgeführt, die in der Projektmappendatei angegeben sind.If you open a solution file, all the projects specified in the solution file will be listed. Überprüfen Sie die Liste der Projekte, die migriert werden sollen, und wählen Sie OK.Review the list of projects to be migrated and select OK.

Unidirektionales Upgrade-Dialogfeld mit der Liste der zu migrierenden Projekte

Visual Studio wird die ausgewählten Projekte automatisch migrieren.Visual Studio will migrate the projects chosen automatically. Wenn Sie bei der Migration einer Projektmappe nicht alle Projekte auswählen, erscheint das gleiche Dialogfeld und Sie werden aufgefordert, die übrigen Projekte der Projektmappe upzugraden.When migrating a solution, if you don't choose all projects, the same dialog will appear asking you to upgrade the remaining projects from that solution. Nachdem das Projekt migriert wurde, können Sie sich seine Inhalt anzeigen lassen und diese ändern, indem Sie mit der rechten Maustaste auf das Projekt im Fenster Projektmappen-Explorer und anschließend auf Bearbeiten <Projektname>.csproj klicken.After the project is migrated, you can see and modify its contents by right-clicking the project in the Solution Explorer window and selecting Edit <project name>.csproj.

Dateien, die migriert wurden (project.json, global.json, .xproj und Projektmappendatei), werden in einen Sicherung-Ordner verschoben.Files that were migrated (project.json, global.json, .xproj and solution file) will be moved to a Backup folder. Die migrierte Projektmappendatei wird auf Visual Studio 2017 upgegradet und es wird nicht mehr möglich sein, diese Projektmappendatei in früheren Versionen von Visual Studio zu öffnen.The solution file that is migrated will be upgraded to Visual Studio 2017 and you won't be able to open that solution file in previous versions of Visual Studio. Eine Datei namens UpgradeLog.htm, die einen Migrationsbericht enthält, wird ebenfalls gespeichert und automatisch geöffnet.A file named UpgradeLog.htm is also saved and automatically opened that contains a migration report.

Wichtig

Die neuen Tools sind nicht in Visual Studio 2015 verfügbar und Sie können Ihre Projekte mit dieser Version von Visual Studio nicht migrieren.The new tooling is not available in Visual Studio 2015, so you cannot migrate your projects using that version of Visual Studio.

dotnet migratedotnet migrate

Im Befehlszeilenszenario können Sie den Befehl dotnet migrate verwenden.In the command-line scenario, you can use the dotnet migrate command. Dadurch werden ein Projekt, eine Projektmappe oder eine Reihe von Ordnern in dieser Reihenfolge migriert, je nachdem ob sie gefunden wurden.It will migrate a project, a solution or a set of folders in that order, depending on which ones were found. Wenn Sie ein Projekt migrieren, werden das Projekt und alle zugehörigen Abhängigkeiten migriert.When you migrate a project, the project and all its dependencies are migrated.

Dateien, die migriert wurden (project.json, global.json und .xproj), werden in einen Sicherung-Ordner verschoben.Files that were migrated (project.json, global.json and .xproj) will be moved to a backup folder.

Hinweis

Bei Verwendung von Visual Studio Code ändert der Befehl dotnet migrate Visual Studio Code-spezifische Dateien wie z.B. tasks.json nicht.If you are using Visual Studio Code, the dotnet migrate command will not modify Visual Studio Code-specific files such as tasks.json. Diese Dateien müssen manuell geändert werden.These files need to be changed manually. Dies gilt auch, wenn Sie Project Ryder oder einen anderen Editor oder eine andere Integrierte Entwicklungsumgebung (IDE) als Visual Studio verwenden.This is also true if you are using Project Ryder or any editor or Integrated Development Environment (IDE) other than Visual Studio.

Einen Vergleich der Formate project.json und csproj finden Sie unter Die Zuordnung zwischen project.json und csproj-Eigenschaften.See A mapping between project.json and csproj properties for a comparison of project.json and csproj formats.

Häufig auftretende ProblemeCommon issues

  • Wenn Sie die Fehlermeldung „No executable found matching command dotnet-migrate“ (Es konnte keine ausführbare Datei gefunden werden, die mit dem Befehl dotnet-migrate übereinstimmt) erhalten:If you get an error: "No executable found matching command dotnet-migrate":

Führen Sie dotnet --version aus, um zu sehen, welche Version Sie verwenden.Run dotnet --version to see which version you are using. dotnet migrate erfordert .NET Core-CLI RC3 oder höher.dotnet migrate requires .NET Core CLI RC3 or higher. Sie erhalten diese Fehlermeldung, wenn sich eine global.json-Datei im aktuellen oder übergeordneten Verzeichnis befindet und die sdk-Version auf eine ältere Version festgelegt ist.You’ll get this error if you have a global.json file in the current or parent directory and the sdk version is set to an older version.

Migration von DNX zu csprojMigration from DNX to csproj

Wenn Sie für die .NET Core-Entwicklung noch immer DNX verwenden, sollte der Migrationsvorgang in zwei Phasen erfolgen:If you are still using DNX for .NET Core development, your migration process should be done in two stages:

  1. Verwenden Sie die existing DNX migration guidance (Hinweise zur Migration von einer vorhandenen DNX), um von DNX zu project-json-aktivierter CLI zu migrieren.Use the existing DNX migration guidance to migrate from DNX to project-json enabled CLI.
  2. Führen Sie die Schritte aus dem vorherigen Abschnitt zum Migrieren von project.json zu .csproj aus.Follow the steps from the previous section to migrate from project.json to .csproj.

Hinweis

DNX gilt seit der Preview 1-Version der .NET Core-CLI offiziell als veraltet.DNX has become officially deprecated during the Preview 1 release of the .NET Core CLI.

Migration von früheren .NET Core-csproj-Formaten zu RTM-csprojMigration from earlier .NET Core csproj formats to RTM csproj

Das .NET Core-csproj-Format ändert und entwickelt sich mit jeder neuen Vorabversion der Tools.The .NET Core csproj format has been changing and evolving with each new pre-release version of the tooling. Es gibt kein Tool, das die Projektdatei von früheren csproj-Versionen zur neuesten migriert, sodass Sie die Projektdatei manuell bearbeiten müssen.There is no tool that will migrate your project file from earlier versions of csproj to the latest, so you need to manually edit the project file. Die tatsächlichen Schritte hängen von der Version der Projektdatei ab, die Sie migrieren.The actual steps depend on the version of the project file you are migrating. Nachfolgend finden Sie einige zu berücksichtigenden Hinweise, die auf den Änderungen von Version zu Version basieren:The following is some guidance to consider based on the changes that happened between versions:

  • Entfernen Sie die Tools-Version-Eigenschaft aus dem <Project>-Element, sofern vorhanden.Remove the tools version property from the <Project> element, if it exists.
  • Entfernen Sie den XML-Namespace (xmlns) aus dem <Project>-Element.Remove the XML namespace (xmlns) from the <Project> element.
  • Wenn es nicht vorhanden ist, fügen Sie das Sdk-Attribut dem <Project>-Element hinzu, und legen Sie es auf Microsoft.NET.Sdk oder Microsoft.NET.Sdk.Web fest.If it doesn't exist, add the Sdk attribute to the <Project> element and set it to Microsoft.NET.Sdk or Microsoft.NET.Sdk.Web. Dieses Attribut gibt an, dass das Projekt das SDK verwendet, das verwendet werden soll.This attribute specifies that the project uses the SDK to be used. Microsoft.NET.Sdk.Web wird für Webanwendungen verwendet.Microsoft.NET.Sdk.Web is used for web apps.
  • Entfernen Sie die Anweisungen <Import Project="$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Microsoft.Common.props" /> und <Import Project="$(MSBuildToolsPath)\Microsoft.CSharp.targets" /> vom oberen und unteren Rand des Projekts.Remove the <Import Project="$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Microsoft.Common.props" /> and <Import Project="$(MSBuildToolsPath)\Microsoft.CSharp.targets" /> statements from the top and bottom of the project. Diese Importanweisungen werden durch das SDK impliziert, daher müssen Sie nicht im Projekt enthalten sein.These import statements are implied by the SDK, so there is no need for them to be in the project.
  • Wenn Ihr Projekt Microsoft.NETCore.App- oder NETStandard.Library-<PackageReference>-Elemente enthält, sollten Sie diese entfernen.If you have Microsoft.NETCore.App or NETStandard.Library <PackageReference> items in your project, you should remove them. Diese Paketverweise werden durch das SDK impliziert.These package references are implied by the SDK.
  • Entfernen Sie das Microsoft.NET.Sdk-<PackageReference>-Element, sofern vorhanden.Remove the Microsoft.NET.Sdk <PackageReference> element, if it exists. Die SDK-Referenz kommt durch das Sdk-Attribut auf dem <Project>-Element.The SDK reference comes through the Sdk attribute on the <Project> element.
  • Entfernen Sie die Globs, die durch das SDK impliziert werden.Remove the globs that are implied by the SDK. Wenn diese Globs im Projekt bleiben, führt dies zu einem Fehler beim Erstellen, da Compile-Elemente dupliziert werden.Leaving these globs in your project will cause an error on build because compile items will be duplicated.

Nach diesen Schritten sollte das Projekt mit dem RTM .NET Core-csproj-Format vollständig kompatibel sein.After these steps your project should be fully compatible with the RTM .NET Core csproj format.

Beispiele für vor und nach der Migration vom alten csproj-Format zum neuen finden Sie im Artikel Updating Visual Studio 2017 RC – .NET Core Tooling improvements (Aktualisieren von Visual Studio 2017 RC – Verbesserungen der .NET Core-Tools) im .NET-Blog.For examples of before and after the migration from old csproj format to the new one, see the Updating Visual Studio 2017 RC – .NET Core Tooling improvements article on the .NET blog.

Siehe auchSee also

Übertragung, Migration und Upgrade der Visual Studio-ProjektePort, Migrate, and Upgrade Visual Studio Projects