Переход с ASP.NET Core 1.x на 2.0

2025-05-06

В этой статье мы рассмотрим обновление существующего проекта ASP.NET Core 1.x до ASP.NET Core 2.0. Перенос приложения в ASP.NET Core 2.0 позволяет воспользоваться преимуществами многих новых функций и улучшений производительности.

Существующие приложения ASP.NET Core 1.x основаны на шаблонах проектов, относящихся к версии. По мере того как эволюционирует платформа ASP.NET Core, шаблоны проектов и начальный код, содержащиеся в них, также развиваются. Помимо обновления платформы ASP.NET Core, необходимо обновить код приложения.

Предпосылки

См. статью "Начало работы с ASP.NET Core".

Обновление моникера целевой платформы (TFM)

Проекты, предназначенные для .NET Core, должны использовать TFM версии более или равной .NET Core 2.0. Найдите узел <TargetFramework> в файле .csproj и замените его внутренний текст на netcoreapp2.0.

<TargetFramework>netcoreapp2.0</TargetFramework>

Проекты, предназначенные для .NET Framework, следует использовать TFM версии не ниже .NET Framework 4.6.1. Найдите узел <TargetFramework> в файле .csproj и замените его внутренний текст на net461.

<TargetFramework>net461</TargetFramework>

Замечание

.NET Core 2.0 предлагает гораздо большую область поверхности, чем .NET Core 1.x. Если вы выбираете .NET Framework исключительно из-за отсутствия API в .NET Core 1.x, то, вероятно, использование .NET Core 2.0 будет успешным.

Если файл проекта содержится <RuntimeFrameworkVersion>1.{sub-version}</RuntimeFrameworkVersion>, см. эту проблему GitHub.

Обновление версии пакета SDK для .NET Core в global.json

Если решение использует global.json файл для целевой версии пакета SDK для .NET Core, обновите его version свойство, чтобы использовать версию 2.0, установленную на компьютере:

{
  "sdk": {
    "version": "2.0.0"
  }
}

Обновление ссылок на пакеты

Файл .csproj в проекте 1.x перечисляет каждый пакет NuGet, используемый проектом.

В проекте ASP.NET Core 2.0, предназначенном для .NET Core 2.0, одна ссылка на метапакет в .csproj файле заменяет коллекцию пакетов:

<ItemGroup>
  <PackageReference Include="Microsoft.AspNetCore.All" Version="2.0.9" />
</ItemGroup>

Все функции ASP.NET Core 2.0 и Entity Framework Core 2.0 включены в метапакет.

ASP.NET проекты Core 2.0, предназначенные для .NET Framework, должны продолжать ссылаться на отдельные пакеты NuGet. Version Обновите атрибут каждого <PackageReference /> узла до версии 2.0.0.

Например, вот список узлов, используемых <PackageReference /> в типичном проекте ASP.NET Core 2.0 для .NET Framework:

<ItemGroup>
  <PackageReference Include="Microsoft.AspNetCore" Version="2.0.0" />
  <PackageReference Include="Microsoft.AspNetCore.Authentication.Cookies" Version="2.0.0" />
  <PackageReference Include="Microsoft.AspNetCore.Diagnostics.EntityFrameworkCore" Version="2.0.0" />
  <PackageReference Include="Microsoft.AspNetCore.Identity.EntityFrameworkCore" Version="2.0.0" />
  <PackageReference Include="Microsoft.AspNetCore.Mvc" Version="2.0.0" />
  <PackageReference Include="Microsoft.AspNetCore.Mvc.Razor.ViewCompilation" Version="2.0.0" PrivateAssets="All" />
  <PackageReference Include="Microsoft.AspNetCore.StaticFiles" Version="2.0.0" />
  <PackageReference Include="Microsoft.EntityFrameworkCore.Design" Version="2.0.0" PrivateAssets="All" />
  <PackageReference Include="Microsoft.EntityFrameworkCore.SqlServer" Version="2.0.0" />
  <PackageReference Include="Microsoft.EntityFrameworkCore.Tools" Version="2.0.0" PrivateAssets="All" />
  <PackageReference Include="Microsoft.VisualStudio.Web.BrowserLink" Version="2.0.0" />
  <PackageReference Include="Microsoft.VisualStudio.Web.CodeGeneration.Design" Version="2.0.0" PrivateAssets="All" />
</ItemGroup>

Пакет Microsoft.Extensions.CommandLineUtils был снят с учета. Он по-прежнему доступен, но не поддерживается.

Обновление средств .NET CLI

.csproj В файле обновите Version атрибут каждого <DotNetCliToolReference /> узла до версии 2.0.0.

Например, вот список средств CLI, используемых в типичном проекте ASP.NET Core 2.0, предназначенных для .NET Core 2.0:

<ItemGroup>
  <DotNetCliToolReference Include="Microsoft.EntityFrameworkCore.Tools.DotNet" Version="2.0.0" />
  <DotNetCliToolReference Include="Microsoft.Extensions.SecretManager.Tools" Version="2.0.0" />
  <DotNetCliToolReference Include="Microsoft.VisualStudio.Web.CodeGeneration.Tools" Version="2.0.0" />
</ItemGroup>

Переименовать свойство резервного целевого пакета

Файл .csproj проекта 1.x использовал PackageTargetFallback узел и переменную:

<PackageTargetFallback>$(PackageTargetFallback);portable-net45+win8+wp8+wpa81;</PackageTargetFallback>

Переименуйте и узел, и переменную на AssetTargetFallback.

<AssetTargetFallback>$(AssetTargetFallback);portable-net45+win8+wp8+wpa81;</AssetTargetFallback>

Обновление метода Main в Program.cs

В проектах Main 1.x метод Program.cs выглядел следующим образом:

using System.IO;
using Microsoft.AspNetCore.Hosting;

namespace AspNetCoreDotNetCore1App
{
    public class Program
    {
        public static void Main(string[] args)
        {
            var host = new WebHostBuilder()
                .UseKestrel()
                .UseContentRoot(Directory.GetCurrentDirectory())
                .UseIISIntegration()
                .UseStartup<Startup>()
                .UseApplicationInsights()
                .Build();

            host.Run();
        }
    }
}

В проектах 2.0 метод MainProgram.cs был упрощен:

using Microsoft.AspNetCore;
using Microsoft.AspNetCore.Hosting;

namespace AspNetCoreDotNetCore2App
{
    public class Program
    {
        public static void Main(string[] args)
        {
            BuildWebHost(args).Run();
        }

        public static IWebHost BuildWebHost(string[] args) =>
            WebHost.CreateDefaultBuilder(args)
                .UseStartup<Startup>()
                .Build();
    }
}

Внедрение этого нового шаблона 2.0 настоятельно рекомендуется и требуется для работы функций продукта, таких как Entity Framework (EF) Core Migrations . Например, при запуске Update-Database из окна консоли диспетчера пакетов или dotnet ef database update из командной строки (в проектах, преобразованных в ASP.NET Core 2.0), возникает следующая ошибка:

Unable to create an object of type '<Context>'. Add an implementation of 'IDesignTimeDbContextFactory<Context>' to the project, or see https://go.microsoft.com/fwlink/?linkid=851728 for additional patterns supported at design time.

Все поставщики конфигурации

В проектах 1.x добавление поставщиков конфигурации в приложение было выполнено с помощью конструктора Startup . Действия, связанные с созданием экземпляра, загрузкой применимых ConfigurationBuilderпоставщиков (переменными среды, параметрами приложения и т. д.) и инициализацией члена IConfigurationRoot.

public Startup(IHostingEnvironment env)
{
    var builder = new ConfigurationBuilder()
        .SetBasePath(env.ContentRootPath)
        .AddJsonFile("appsettings.json", optional: false, reloadOnChange: true)
        .AddJsonFile($"appsettings.{env.EnvironmentName}.json", optional: true);

    if (env.IsDevelopment())
    {
        builder.AddUserSecrets<Startup>();
    }

    builder.AddEnvironmentVariables();
    Configuration = builder.Build();
}

public IConfigurationRoot Configuration { get; }

Элемент Configuration загружается параметрами конфигурации из appsettings.json, а также из любого appsettings.{Environment}.json файла, соответствующего свойству IHostingEnvironment.EnvironmentName. Расположение этих файлов совпадает с Startup.cs.

В проектах 2.0 стандартный код конфигурации, присущий проектам 1.x, выполняется за кулисами. Например, переменные среды и параметры приложения загружаются при запуске. Эквивалентный Startup.cs код сводится к IConfiguration инициализации с внедренным экземпляром:

public Startup(IConfiguration configuration)
{
    Configuration = configuration;
}

public IConfiguration Configuration { get; }

Чтобы удалить добавленных поставщиков по умолчанию WebHostBuilder.CreateDefaultBuilder, вызовите метод Clear в свойстве IConfigurationBuilder.Sources внутри ConfigureAppConfiguration. Чтобы добавить поставщиков обратно, используйте метод ConfigureAppConfiguration в Program.cs.

public static void Main(string[] args)
{
    BuildWebHost(args).Run();
}

public static IWebHost BuildWebHost(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureAppConfiguration((hostContext, config) =>
        {
            // delete all default configuration providers
            config.Sources.Clear();
            config.AddJsonFile("myconfig.json", optional: true);
        })
        .Build();

Здесь CreateDefaultBuilder конфигурацию, используемую методом в приведенном выше фрагменте кода.

Дополнительные сведения см. в разделе Конфигурация в ASP.NET Core.

Перемещение кода инициализации базы данных

В проектах версии 1.x, при использовании EF Core 1.x, команда, такая как dotnet ef migrations add, выполняет следующее:

Создает экземпляр Startup
Метод ConfigureServices вызывается для регистрации всех сервисов с использованием внедрения зависимостей (включая типы DbContext)
Выполняет необходимые задачи

В проектах 2.0, использующих EF Core 2.0, Program.BuildWebHost вызывается для получения служб приложений. В отличие от 1.x, это имеет дополнительный побочный эффект вызова Startup.Configure. Если приложение 1.x вызвало код инициализации базы данных в методе Configure , могут возникнуть непредвиденные проблемы. Например, если база данных еще не существует, начальный код запускается до EF Core выполнения команды Migrations. Эта проблема приводит к сбою dotnet ef migrations list команды, если база данных еще не существует.

Рассмотрим следующий код начальной инициализации 1.x в методе ConfigureStartup.cs:

app.UseMvc(routes =>
{
    routes.MapRoute(
        name: "default",
        template: "{controller=Home}/{action=Index}/{id?}");
});

SeedData.Initialize(app.ApplicationServices);

В проектах 2.0 переместите вызов SeedData.Initialize на метод Main из Program.cs:

var host = BuildWebHost(args);

using (var scope = host.Services.CreateScope())
{
    var services = scope.ServiceProvider;

    try
    {
        // Requires using RazorPagesMovie.Models;
        SeedData.Initialize(services);
    }
    catch (Exception ex)
    {
        var logger = services.GetRequiredService<ILogger<Program>>();
        logger.LogError(ex, "An error occurred seeding the DB.");
    }
}

host.Run();

Начиная с версии 2.0, это плохая практика делать что-либо в BuildWebHost, кроме сборки и настройки веб-узла. Все, что относится к запуску приложения, должно обрабатываться за пределами BuildWebHost , как правило, в методе MainProgram.cs.

Просмотр Razor параметра компиляции представления

Быстрое время запуска приложения и более мелкие опубликованные пакеты являются крайне важными для вас. По этим причинам Razor компиляция представлений включена по умолчанию в ASP.NET Core 2.0.

Устанавливать свойство MvcRazorCompileOnPublish в значение true больше не требуется. Если вы не отключаете компиляцию представлений, то свойство может быть удалено из файла .csproj.

При использовании .NET Framework необходимо явно ссылаться на пакет NuGet Microsoft.AspNetCore.Mvc.Razor.ViewCompilation в вашем файле .csproj.

<PackageReference Include="Microsoft.AspNetCore.Mvc.Razor.ViewCompilation" Version="2.0.0" PrivateAssets="All" />

Полагайтесь на функции Application Insights "light-up"

Важна простая настройка инструментов для оценки производительности приложений. Теперь вы можете воспользоваться новыми функциями "активации" Application Insights, доступными в инструментах Visual Studio 2017.

ASP.NET проекты Core 1.1, созданные в Visual Studio 2017, по умолчанию добавили Application Insights. Если вы не используете пакет SDK Application Insights напрямую, за пределами Program.cs и Startup.csвыполните следующие действия.

Если вы ориентируетесь на .NET Core, удалите следующий узел <PackageReference /> из файла .csproj.
```
<PackageReference Include="Microsoft.ApplicationInsights.AspNetCore" Version="2.0.0" />
```

Если вы нацелены на .NET Core, удалите вызов метода расширения UseApplicationInsights из Program.cs.

public static void Main(string[] args)
{
    var host = new WebHostBuilder()
        .UseKestrel()
        .UseContentRoot(Directory.GetCurrentDirectory())
        .UseIISIntegration()
        .UseStartup<Startup>()
        .UseApplicationInsights()
        .Build();

    host.Run();
}

Удалите вызов API на стороне клиента Application Insights из _Layout.cshtml. Он состоит из следующих двух строк кода:
```
@inject Microsoft.ApplicationInsights.AspNetCore.JavaScriptSnippet JavaScriptSnippet
@Html.Raw(JavaScriptSnippet.FullScript)
```

Если вы используете пакет SDK Application Insights напрямую, продолжайте это делать. Метапакет версии 2.0 включает последнюю версию Application Insights, поэтому ошибка возникает, если ссылаетесь на более старую версию пакета.

Внедрение проверки подлинности иIdentity улучшений

ASP.NET Core 2.0 имеет новую модель проверки подлинности и ряд существенных изменений в ASP.NET Core Identity. Если вы создали проект с включенными отдельными учетными записями пользователей или вручную добавили проверку подлинности или Identity, см. статью «Миграция проверки подлинности и Identity на ASP.NET Core 2.0».

Дополнительные ресурсы

Критические изменения в ASP.NET Core 2.0

Поделиться через

Переход с ASP.NET Core 1.x на 2.0

Предпосылки

Обновление моникера целевой платформы (TFM)

Обновление версии пакета SDK для .NET Core в global.json

Обновление ссылок на пакеты

Обновление средств .NET CLI

Переименовать свойство резервного целевого пакета

Обновление метода Main в Program.cs

Все поставщики конфигурации

Перемещение кода инициализации базы данных

Просмотр Razor параметра компиляции представления

Полагайтесь на функции Application Insights "light-up"

Внедрение проверки подлинности иIdentity улучшений

Дополнительные ресурсы

Обратная связь

Дополнительные ресурсы