Note:
This documentation is archived because it was the preview version of the release of CMS 12/Commerce 14/Search & Navigation 14. See Get started developing with CMS.
The Upgrade assistant automates common tasks related to migrating ASP.NET MVC and WebAPI projects to ASP.NET Core.
Note: While Upgrade assistant does many of the migration tasks automatically for an ASP.NET project, you will have manual migration tasks to complete the migration.
After you run Upgrade assistant on a project, the project will not build until you complete the migration (because the project is only partially migrated to .NET Core). Analyzers added to the project will highlight some of the remaining changes needed after the tool runs.
The Upgrade assistant is found in an open-source GitHub repository.
The Upgrade assistant is a general migration tool from ASP.NET standard to ASP.NET Core, but it links to another repository, the Optimizely Migrator, that contains code for migrating Optimizely-specific things.
Prerequisites
- The Upgrade assistant uses MSBuild to work with project files. Make sure that you have a recent version of MSBuild installed. An easy way to do this is to install Visual Studio 2019.
- This tool requires that your project builds. This may include installing install Visual Studio 2019 to ensure build SDKs (such as for web applications, etc) are available.
Installing the Upgrade assistant
To install the Upgrade assistant as a .NET CLI tool:
dotnet tool install -g upgrade-assistant
To upgrade the Upgrade assistant:
dotnet tool update -g upgrade-assistant
To try the latest (and likely less stable) versions of the tool, CI builds are available on the dotnet-tools NuGet feed and can be installed with
dotnet tool install -g upgrade-assistant --add-source https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet-tools/nuget/v3/index.json
or updated using the same --add-source parameter.
Troubleshooting
If installation fails, trying running the install command with the --ignore-failed-sources parameter: dotnet tool install -g upgrade-assistant --ignore-failed-sources. Upgrade-assistant is installed as a NuGet package, so invalid or authenticated sources in NuGet configuration can cause installation problems.
Running the Upgrade assistant
Tip: When running the assistant, you access help by typing:
dotnet run -- migrate --help
Use the following command to run the Upgrade assistant:
upgrade-assistant <Path to csproj or sln to migrate>
Note: You can exit the Upgrade assistant in mid-migration and then resume it later. The progress of the migration process is saved to continue where you left off.
Configuration arguments
| Option |
Description |
| --skip-backup |
By default, the Upgrade assistant backs up your solution automatically before analyzing and converting your projects. To prevent this, pass this argument. However, you should not do this unless your solution is already in version control. |
| -b, --backup-path <backup-path> |
Specifies where the project should be backed up. If you do not specify a backup path, the assistant automatically creates a new directory next to the project directory. |
| --extension <extension> |
Specifies a .NET Upgrade Assistant extension package to include. This could be an ExtensionManifest.json file, a directory containing an ExtensionManifest.json file, or a zip archive containing an extension. This option can be specified multiple times. describes where the updates come from, or a directory containing a manifest file. You can specify this option multiple times, and you can use this path variable to set multiple paths at the same time UpgradeAssistantExtensionPaths={path1};{path2}. |
| -e, --entry-point <entry-point> |
Provides the entry-point project to start the upgrade process. This may include globbing patterns such as '*' for match. |
| -v, --verbose |
Enable verbose diagnostics |
| --non-interactive |
Automatically select each first option in non-interactive mode. |
--non-interactive-wait
<non-interactive-wait> |
Wait the supplied seconds before moving <non-interactive-wait> on to the next option in non-interactive mode. |
| --version |
Show version information |
| -?, -h, --help |
Show help and usage information |
Do you find this information helpful? Please log in to provide feedback.
Last updated: Jul 02, 2021
