dotnet-migrate(1)

👑 dotnet-migrate(1) — the .NET docs page, but make it cute ✨

okay so bestie, gather round, because we're reading dotnet-migrate(1) from the official .NET Documentation and it's giving legacy. Also heads up: This article applies to: ✔️ .NET Core 2.x SDK. That's the vibe. Let's get into it 💅

---

🎀 NAME 🎀

dotnet-migrate — migrates a Preview 2 .NET Core project to a .NET Core SDK-style project. no cap, that's literally the whole job description 🦋

---

✨ SYNOPSIS ✨

dotnet migrate [<SOLUTION_FILE|PROJECT_DIR>] [--format-report-file-json <REPORT_FILE>]
    [-r|--report-file <REPORT_FILE>] [-s|--skip-project-references [Debug|Release]]
    [--skip-backup] [-t|--template-file <TEMPLATE_FILE>] [-v|--sdk-package-version]
    [-x|--xproj-file]

dotnet migrate -h|--help

look at her. iconic. 🌈

---

💖 DESCRIPTION 💖

okay so first things first, and I need you to hear me on this one: this command is deprecated. 😭 The dotnet migrate command is no longer available starting with .NET Core 3.0 SDK. It can only migrate a Preview 2 .NET Core project to a 1.x .NET Core project, which is out of support. so like... it's a museum piece. beautiful, historic, do not build on it. 💀

By default, the command migrates the root project and any project references that the root project contains. That behavior gets disabled using the --skip-project-references option at run time. ✨

Migration can be performed on the following assets:

• A single project by specifying the project.json file to migrate.
• All of the directories specified in the global.json file by passing in a path to the global.json file.
• A solution.sln file, where it migrates the projects referenced in the solution.
• On all subdirectories of the given directory recursively.

The dotnet migrate command keeps the migrated project.json file inside a backup directory, which it creates if the directory doesn't exist. (so thoughtful of her 🫶) This behavior is overridden using the --skip-backup option.

By default, the migration operation outputs the state of the migration process to standard output (STDOUT). If you use the --report-file <REPORT_FILE> option, the output is saved to the file specify. 🍓

The dotnet migrate command only supports valid Preview 2 project.json-based projects. This means that you cannot use it to migrate DNX or Preview 1 project.json-based projects directly to MSBuild/csproj projects. You first need to manually migrate the project to a Preview 2 project.json-based project and then use the dotnet migrate command to migrate the project. 😮‍💨 (yes it's a whole two-step. she doesn't do glow-ups from scratch.)

---

🦋 ARGUMENTS 🦋

PROJECT_JSON/GLOBAL_JSON/SOLUTION_FILE/PROJECT_DIR

The path to one of the following:

• a project.json file to migrate.
• a global.json file: the folders specified in global.json are migrated.
• a solution.sln file: the projects referenced in the solution are migrated.
• a directory to migrate: recursively searches for project.json files to migrate inside the specified directory.

Defaults to current directory if nothing is specified. 🎀

---

💅 OPTIONS 💅

• --format-report-file-json <REPORT_FILE> — Output migration report file as JSON rather than user messages. 🧚
• -h|--help — Prints out a short help for the command. (our emotional support flag fr fr)
• -r|--report-file <REPORT_FILE> — Output migration report to a file in addition to the console.
• -s|--skip-project-references [Debug|Release] — Skip migrating project references. By default, project references are migrated recursively. 🙈
• --skip-backup — Skip moving project.json, global.json, and *.xproj to a backup directory after successful migration.
• -t|--template-file <TEMPLATE_FILE> — Template csproj file to use for migration. By default, the same template as the one dropped by dotnet new console is used. ✨
• -v|--sdk-package-version <VERSION> — The version of the sdk package that's referenced in the migrated app. The default is the version of the SDK in dotnet new.
• -x|--xproj-file <FILE> — The path to the xproj file to use. Required when there is more than one xproj in a project directory. 👑

---

🌸 EXAMPLES 🌸

Migrate a project in the current directory and all of its project-to-project dependencies:

dotnet migrate

Migrate all projects that global.json file includes:

dotnet migrate path/to/global.json

Migrate only the current project and no project-to-project (P2P) dependencies. Also, use a specific SDK version:

dotnet migrate -s -v 1.0.0-preview4

ate. no crumbs. 🔥

---

and that's the whole page bestie!! she was written for 2024-10-02 and she lives in the dotnet-migrate(1) manual section of the .NET docs — deprecated queen, out-of-support legend, we love her, we do NOT use her in prod. 💜 bye!! 🎀✨