---
title: Upgrade Assistant
slug: cms-11/dev-docs/upgrade-assistant
docTags: 
createdAt: 2026-07-22T19:45:22.987Z
---

The **Upgrade assistant** automates the transition from an ASP.NET Standard project to an ASP.NET Core project. The tool employs the following steps. (You could plug in your conversion steps.)

1. **Creates a backup**
   Upgrade assistant creates a backup because it is going to change important things. You can disable this step if you already have a backup, such as in a source code repository.
2. **Identifies solution conversion order**
   The upgrade assistant determines and recommends the order to migrate projects within a solution. You can accept the recommendation or decide on another order.
3. **Runs try-convert**
   Upgrade assistant runs the try-convert tool to convert the project file from a CS-style project to an SDK-style project. (are there any configuration options?) The try-convert CLI tool is a standard Microsoft package and is found on [GitHub](https://github.com/dotnet/try-convert).
4. **Removes transitive NuGet package dependencies**
   Old NuGet package dependencies that may be present in `packages.config` are removed.
5. **Re-targets project to .NET 6**
6. **Updates NuGet packages**
   Upgrade assistant updates NuGet packages to versions compatible with .NET 6. A config file uses a list with old package names and versions to map to new ones. If a package is not needed, it is removed. NuGet package references should be ASP.NET Core standard compatible.
   Upgrade assistant removes old packages and transitive dependencies and adds packages. The tool then makes an extra restore to rebuild the lock files. After that, it runs a second pass to look for transitive dependencies and removes those in case the NuGet packages add unnecessary transitive dependencies. This lets the tool remove redundant packages that were once needed but are unnecessary after the conversion.
7. **Adds template files**
   Upgrade assistant adds template files that ASP.NET Core needs for startup and hosting code typically used in Optimizely environments. You can tweak the template files later. See Startup code.
8. **Migrates app config files**
   Upgrade assistant migrates non-C# files, like `web.config`, using an interface called `IConfigUpdater` that takes an array of config files and updates them to follow ASP.NET Core standards. You can also implement your `IConfigUpdater` by dropping your libraries into a specific folder; they are picked up at runtime and converted. See  Application configuration files.
9. **Updates source code**
   Upgrade assistant updates the source code by removing unnecessary namespace declarations not supported by ASP.NET Core, and adding namespace references that are supported instead.
   Some cases cannot be handled automatically because there may be too many differences between modules, such as converting HTTP modules to middleware. You must manually convert such cases.

When you have run the tool on your solution, the solution will most probably not build until you have manually completed some migration steps. Analyzers are added to help you identify the changes needed after the tool runs.

## Install the Upgrade assistant

The **Upgrade assistant** automates common tasks related to migrating ASP.NET MVC and WebAPI projects to ASP.NET Core.

:::hint{type="info"}
**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 the changes needed after the tool runs.

The Upgrade assistant is in an open-source [GitHub](https://github.com/dotnet/upgrade-assistant) 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](https://github.com/episerver/upgrade-assistant-extensions), 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](https://visualstudio.microsoft.com/downloads/) to ensure build SDKs (such as for web applications, etc) are available.

To install the Upgrade assistant as a .NET CLI tool:

```shell
dotnet tool install -g upgrade-assistant
```

To upgrade the Upgrade assistant:

```shell
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

```shell
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.

### Troubleshoot installation issues

If installation fails, try 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](https://docs.microsoft.com/nuget/consume-packages/configuring-nuget-behavior) can cause installation problems.

## Run the Upgrade assistant

:::hint{type="info"}
**Tip**
When running the assistant, you access help by typing:

```javascript
dotnet run -- migrate --help
```
:::

Use the following command to run the Upgrade assistant:

```shell
upgrade-assistant <Path to csproj or sln to migrate>
```

:::hint{type="info"}
**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

- `--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> onto the next option in non-interactive mode.
- `--version`
  Show version information.
- `-?`, `-h`, `--help`
  Show help and usage information.

## Analyzers

Analyzer functionality is included in the Upgrade assistant to analyze your solution and determine the components that must be migrated to ASP.NET Core standard. After the analyzers evaluate your code, you can let the Upgrade assistant automatically convert your solution to ASP.NET Core.

Some tasks are not fully automated. For example, the Upgrade assistant does not handle Razor views or CSHTML, but the analyzer functionality does. The analyzer functionality directly flags non-ASP.NET Core standards with green squiggles in the Visual Studio project. You can fix these errors with **code quick fix** functionality in Visual Studio.

The analyzer also works on an already-converted solution, so when you open your updated ASP.NET Core site in Visual Studio and pull in more code that was not converted to ASP.NET Core standard, the analyzer flags any code that does not follow .NET Core standard (for example, occurrences of `System.Web` or `Owin`).

The analyzer tool works for non-framework libraries, such as business logic libraries.

- If you have a library that targets ASP.NET Standard and convert it into ASP.NET Core, it can no longer be consumed by ASP.NET Standard.
- If you have a library with multiple solutions depending on it, other apps targeting this library cannot use it, so in this case, you should have a full framework library and then a library specifically for ASP.NET Core code on the side, to make sure shared libraries can still be used by apps not on ASP.NET Core.

## Startup code

One challenge with going from ASP.NET Standard to ASP.NET Core is that you no longer have a `global.asax` file, which lets you write code that would run in response to higher "system level" events, such as Application\_Start, Application\_End, Session\_Start, Session\_End.

Instead, you have two methods, `Configure` and `ConfigureServices`, and a `Startup` class and those are significantly different. These cannot be migrated automatically because there are too many app-specific things in `global.asax`.

At step 5 in the migration process (adding templates), you need four startup files: `Program.cs`, `Startup.cs`, `appsettings.json`, and `appsettings.Development.json`. If they are missing, Upgrade assistant creates them. It pulls some template files, and changes some namespaces (`System.Web` and `Owin` are no longer used, and are removed) and then add them to the project. Your old `Startup.cs` is saved under the name `Startup.old.cs`.

In `Startup.cs`, you can configure services required by the app and define the app's request handling pipeline as a series of middleware components.

`Program.cs` is often similar from project to project and should not require many changes.

## Application configuration files replacing web.config

In previous versions of ASP.NET, `web.config` stored application configuration settings such as database connection strings, global variables, and so on. In ASP.NET Core, the application configuration settings can come from different configuration sources such as files, user secrets, environment variables, or command-line arguments.

The `appsettings.json` file stores configuration settings previously found in `web.config`. If you do not already have `appsettings.json` in your solution, the Upgrade assistant creates one for you (by adding a template file in step 5) and migrates your `web.config` settings to this file.

If you had a list of namespaces in `web.config` that were automatically imported into Razor views, (such as `System.Web.Mvc.Html`, `System.Web.Routing`, `AlloyTemplates.Models.Pages`, and `AlloyTemplates.Models.Blocks`), you cannot automatically import these namespaces in the views using ASP.NET Core. In ASP.NET Core, you must import them by the `_ViewImports.cshtml` file instead. Upgrade assistant creates `_ViewImports.cshtml` and moves the namespaces from `web.config` to this new file, along with `TagHelpers` because they can be useful in ASP.NET Core projects. Also, Upgrade assistant does not migrate namespaces starting with `System.Web` because ASP.NET Core does not support them; you should replace them with other namespaces.

The `appsettings.{Environment}.json` file is a configuration file where  equals the application's current hosting environments, such as Development, Staging, or Production. This is valuable as you can use different appsettings for different environments.

## ExtensionManifest.json

The Upgrade assistant is divided into two repositories. The first one, \[], contains the general Upgrade assistant that handles general code conversions from ASP.NET standard to ASP.NET Core. The second repository, \[], contains Optimizely specific code.

In this second repository, there is an `ExtensionManifest.json` file, which contains the configuration settings for migrating Optimizely-specific code to ASP.NET Core. From the start, it looks similar to this, with four sections for different configuration options for the migration steps.

```javascript
{
  "ConfigUpdater": {
    "ConfigUpdaterPath": "ConfigUpdaters"
  },
  "PackageUpdater": {
    "PackageMapPath": "PackageMaps"
  },
  "TemplateInserter": {
    "TemplateConfigFiles": [
      "Templates\\EPiServerTemplates\\TemplateConfig.json"
    ]
  }
}
```

- **ConfigUpdater** – For any configuration updaters.
- **PackageUpdater** – Contains the map file that maps old NuGet packages and versions to new packages and versions.
- **SourceUpdater** – For analyzers and code fix providers.
- **TemplateInserter** – Contains template files for the Optimizely-specific code, such as `Program.cs` and *Startup.cs*.

## Related information

If you are starting to look at .NET Core and want to understand more about potential challenges in migrating any particular project .NET Core, start by looking at .NET Framework dependencies the project has, and third-party libraries or NuGet packages it depends on, and understand whether those dependencies are likely to work on .NET Core. Resources that can help with that analysis include:

- [Overview of porting from .NET Framework to .NET](https://docs.microsoft.com/en-us/dotnet/core/porting/)
- [Migrate from ASP.NET to ASP.NET Core](https://docs.microsoft.com/en-us/aspnet/core/migration/proper-to-2x/?view=aspnetcore-6.0)
- [The .NET Portability Analyzer tool](https://github.com/microsoft/dotnet-apiport)
- [Upgrade an ASP.NET MVC App to .NET Core with the .NET Upgrade Assistant](https://docs.microsoft.com/en-us/dotnet/core/porting/upgrade-assistant-aspnetmvc)
- [Upgrade a Windows Forms App to .NET Core with the .NET Upgrade Assistant](https://docs.microsoft.com/en-us/dotnet/core/porting/upgrade-assistant-winforms-framework)
- [Documentation of features not available on .NET Core](https://docs.microsoft.com/dotnet/core/porting/net-framework-tech-unavailable)