Migrowanie z ASP.NET Core 2.0 do wersji 2.1

  • Artykuł

Autor: Rick Anderson

Zobacz Co nowego w programie ASP.NET Core 2.1 , aby zapoznać się z omówieniem nowych funkcji w programie ASP.NET Core 2.1.

W tym artykule:

  • Omówienie podstaw migracji aplikacji ASP.NET Core 2.0 do wersji 2.1.
  • Zawiera omówienie zmian w szablonach aplikacji internetowych platformy ASP.NET Core.

Szybkim sposobem uzyskania przeglądu zmian w wersji 2.1 jest:

  • Utwórz aplikację internetową platformy ASP.NET Core 2.0 o nazwie WebApp1.
  • Zatwierdź usługę WebApp1 w systemie kontroli źródła.
  • Usuń aplikację internetową WebApp1 i utwórz aplikację internetową platformy ASP.NET Core 2.1 o nazwie WebApp1 w tym samym miejscu.
  • Przejrzyj zmiany w wersji 2.1.

Ten artykuł zawiera omówienie migracji do ASP.NET Core 2.1. Nie zawiera pełnej listy wszystkich zmian wymaganych do migracji do wersji 2.1. Niektóre projekty mogą wymagać większej liczby kroków w zależności od opcji wybranych podczas tworzenia projektu i modyfikacji wprowadzonych w projekcie.

Aktualizowanie pliku projektu w celu używania wersji 2.1

Zaktualizuj plik projektu:

  • Zmień strukturę docelową na .NET Core 2.1, aktualizując plik projektu na <TargetFramework>netcoreapp2.1</TargetFramework>.
  • Zastąp odwołanie do pakietu dla Microsoft.AspNetCore.All elementu odwołaniem do pakietu dla Microsoft.AspNetCore.Appelementu . Może być konieczne dodanie zależności, które zostały usunięte z programu Microsoft.AspNetCore.All. Aby uzyskać więcej informacji, zobacz Microsoft.AspNetCore.All metapackage for ASP.NET Core 2.0 and Microsoft.AspNetCore.App metapackage for ASP.NET Core ( Metapackage for ASP.NET Core).
  • Usuń atrybut "Version" w odwołaniu do pakietu do Microsoft.AspNetCore.App. Projekty, których używasz <Project Sdk="Microsoft.NET.Sdk.Web"> , nie muszą ustawiać wersji. Wersja jest dorozumiana przez platformę docelową i wybrana w celu najlepszego dopasowania do sposobu działania ASP.NET Core 2.1. Aby uzyskać więcej informacji, zobacz sekcję Reguły dla projektów przeznaczonych dla platformy udostępnionej.
  • W przypadku aplikacji przeznaczonych dla programu .NET Framework zaktualizuj każde odwołanie do pakietu 2.1.
  • Usuń odwołania do <elementów DotNetCliToolReference> dla następujących pakietów. Te narzędzia są domyślnie dołączane do interfejsu wiersza polecenia platformy .NET Core i nie muszą być instalowane oddzielnie.
    • Microsoft.DotNet.Watcher.Tools (dotnet watch)
    • Microsoft.EntityFrameworkCore.Tools.DotNet (dotnet ef)
    • Microsoft.Extensions. Buforowanie. SqlConfig.Tools (dotnet sql-cache)
    • Microsoft.Extensions.SecretManager.Tools (dotnet user-secrets)
  • Opcjonalnie: możesz usunąć element DotNetCliToolReference> dla elementu Microsoft.VisualStudio.Web.CodeGeneration.Tools.< To narzędzie można zastąpić globalnie zainstalowaną wersją, uruchamiając polecenie dotnet tool install -g dotnet-aspnet-codegenerator.
  • W przypadku wersji 2.1 Razor biblioteka klas jest zalecanym rozwiązaniem do dystrybucji Razor plików. Jeśli aplikacja korzysta z widoków osadzonych lub w inny sposób korzysta z kompilacji Razor plików w czasie wykonywania, dodaj <CopyRefAssembliesToPublishDirectory>true</CopyRefAssembliesToPublishDirectory> element do <PropertyGroup> pliku projektu.

Poniższy znacznik przedstawia plik projektu wygenerowany przez szablon 2.0:

<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <TargetFramework>netcoreapp2.0</TargetFramework>
    <UserSecretsId>aspnet-{Project Name}-{GUID}</UserSecretsId>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.All" Version="2.0.9" />
    <PackageReference Include="Microsoft.EntityFrameworkCore.Tools" Version="2.0.3" PrivateAssets="All" />
    <PackageReference Include="Microsoft.VisualStudio.Web.CodeGeneration.Design" Version="2.0.4" PrivateAssets="All" />
  </ItemGroup>
  <ItemGroup>
    <DotNetCliToolReference Include="Microsoft.EntityFrameworkCore.Tools.DotNet" Version="2.0.3" />
    <DotNetCliToolReference Include="Microsoft.Extensions.SecretManager.Tools" Version="2.0.2" />
    <DotNetCliToolReference Include="Microsoft.VisualStudio.Web.CodeGeneration.Tools" Version="2.0.4" />
  </ItemGroup>
</Project>

Poniższy znacznik przedstawia wygenerowany przez szablon plik projektu 2.1:

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>netcoreapp2.1</TargetFramework>
    <UserSecretsId>aspnet-{Project Name}-{GUID}</UserSecretsId>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.App" />
    <PackageReference Include="Microsoft.VisualStudio.Web.CodeGeneration.Design" Version="2.1.1" PrivateAssets="All" />
  </ItemGroup>

</Project>

Reguły dotyczące projektów przeznaczonych dla platformy udostępnionej

Platforma udostępnionato zestaw zestawów (plików dll), które nie znajdują się w folderach aplikacji. Aby można było uruchomić aplikację, na maszynie musi być zainstalowana platforma udostępniona. Aby uzyskać więcej informacji, zobacz Struktura udostępniona.

ASP.NET Core 2.1 obejmuje następujące struktury udostępnione:

Wersja określona przez odwołanie do pakietu jest minimalną wymaganą wersją. Na przykład projekt odwołujący się do wersji 2.1.1 tych pakietów nie będzie uruchamiany na maszynie z zainstalowanym tylko środowiskiem uruchomieniowym 2.1.0.

Znane problemy dotyczące projektów przeznaczonych dla platformy udostępnionej:

Aktualizowanie obrazów platformy Docker w wersji 2.1

W programie ASP.NET Core 2.1 obrazy platformy Docker migrowane do repozytorium dotnet/dotnet-docker w usłudze GitHub. W poniższej tabeli przedstawiono zmiany obrazu i tagu platformy Docker:

2.0 2.1
microsoft/aspnetcore:2.0 microsoft/dotnet:2.1-aspnetcore-runtime
microsoft/aspnetcore-build:2.0 microsoft/dotnet:2.1-sdk

Zmień wiersze FROM w pliku Dockerfile , aby używać nowych nazw obrazów i tagów w poprzedniej kolumnie 2.1 tabeli. Aby uzyskać więcej informacji, zobacz Migrowanie z repozytoriów platformy docker aspnetcore do dotnet.

Zmiany w main

Na poniższych obrazach przedstawiono zmiany wprowadzone w wygenerowany plik szablonu Program.cs .

old version differences

Na powyższej ilustracji przedstawiono wersję 2.0 z usunięciami na czerwono.

Na poniższej ilustracji przedstawiono kod 2.1. Kod w kolorze zielonym zastąpił wersję 2.0:

new version differences

Poniższy kod przedstawia wersję 2.1 programu Program.cs:

namespace WebApp1
{
    public class Program
    {
        public static void Main(string[] args)
        {
            CreateWebHostBuilder(args).Build().Run();
        }

        public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
            WebHost.CreateDefaultBuilder(args)
                .UseStartup<Startup>();
    }
}

Nowa Main funkcja zastępuje wywołanie metody BuildWebHostCreateWebHostBuilder. IWebHostBuilder dodano obsługę nowej infrastruktury testów integracji.

Zmiany w uruchamianiu

Poniższy kod przedstawia zmiany w kodzie wygenerowany przez szablon w wersji 2.1. Wszystkie zmiany są nowo dodane, z tą różnicą, że UseBrowserLink zostały usunięte:

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;

namespace WebApp1
{
    public class Startup
    {
        public Startup(IConfiguration configuration)
        {
            Configuration = configuration;
        }

        public IConfiguration Configuration { get; }

        public void ConfigureServices(IServiceCollection services)
        {
            services.Configure<CookiePolicyOptions>(options =>
            {
                // This lambda determines whether user consent for non-essential cookies is needed for a given request.
                options.CheckConsentNeeded = context => true;
                options.MinimumSameSitePolicy = SameSiteMode.None;
            });


            services.AddMvc()
                .SetCompatibilityVersion(CompatibilityVersion.Version_2_1);
        }

        public void Configure(IApplicationBuilder app, IHostingEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }
            else
            {
                app.UseExceptionHandler("/Error");
                app.UseHsts();
            }

            app.UseHttpsRedirection();
            app.UseStaticFiles();
            app.UseCookiePolicy();
            // If the app uses Session or TempData based on Session:
            // app.UseSession();

            app.UseMvc();
        }
    }
}

Powyższe zmiany kodu zostały szczegółowo opisane w temacie:

Zmiany w kodzie uwierzytelniania

ASP.NET Core 2.1 zapewnia ASP.NET Core Identity jako bibliotekę Razor klas (RCL).

Domyślny interfejs użytkownika 2.1 Identity nie udostępnia obecnie znaczących nowych funkcji w wersji 2.0. Identity Zastąpienie pakietem listy RCL jest opcjonalne. Zalety zamiany wygenerowanego Identity kodu szablonu na wersję listy RCL obejmują:

  • Wiele plików jest przenoszonych z drzewa źródłowego.
  • Wszelkie poprawki błędów lub nowe funkcje, które mają Identity być zawarte w Microsoft.AspNetCore.App metapakiecie. Aktualizacja zostanie automatycznie zaktualizowana Identity po Microsoft.AspNetCore.App zaktualizowaniu.

Jeśli wprowadzono nietrygalne zmiany w wygenerowanym Identity kodzie szablonu:

  • Powyższe zalety prawdopodobnie nie uzasadniają konwersji na wersję listy RCL.
  • Możesz zachować kod ASP.NET Core 2.0 Identity , który jest w pełni obsługiwany.

Identity 2.1 uwidacznia punkty końcowe w Identity obszarze. Na przykład w poniższej tabeli przedstawiono przykłady Identity punktów końcowych, które zmieniają się z 2.0 na 2.1:

Adres URL 2.0 Adres URL 2.1
/Account/Login /Identity/Konto/Logowanie
/Konto/Wylogowywanie /Identity/Konto/Wylogowywanie
/Konto/Zarządzanie /Identity/Konto/Zarządzanie

Aplikacje, które korzystają z kodu i Identity zastępują interfejs użytkownika 2.0 Identity biblioteką w wersji 2.1 Identity , muszą uwzględniać Identity adresy URL, które /Identity są podzielone na segmenty prepended na identyfikatory URI. Jednym ze sposobów obsługi nowych Identity punktów końcowych jest skonfigurowanie przekierowań, na przykład z /Account/Login do /Identity/Account/Login.

Aktualizacja Identity do wersji 2.1

Dostępne są następujące opcje aktualizacji Identity do wersji 2.1.

  • Użyj kodu interfejsu Identity użytkownika 2.0 bez zmian. Korzystanie z Identity kodu interfejsu użytkownika 2.0 jest w pełni obsługiwane. Jest to dobre podejście w przypadku wprowadzania znaczących zmian w wygenerowanym Identity kodzie.
  • Usuń istniejący Identity kod 2.0 i szkielet Identity do projektu. Projekt będzie używać biblioteki klas podstawowychIdentityRazor ASP.NET. Możesz wygenerować kod i interfejs użytkownika dla dowolnego zmodyfikowanego kodu interfejsu Identity użytkownika. Zastosuj zmiany kodu do nowo utworzonego szkieletu kodu interfejsu użytkownika.
  • Usuń istniejący Identity kod 2.0 i szkielet Identity do projektu z opcją Zastąpienia wszystkich plików.

Zastąp Identity interfejs użytkownika 2.0 biblioteką Identity klas 2.1 Razor

W tej sekcji opisano kroki zastępowania szablonu ASP.NET Core 2.0 wygenerowanego Identity kodu za pomocą biblioteki klas podstawowychIdentityRazor ASP.NET. Poniższe kroki dotyczą Razor projektu Pages, ale podejście do projektu MVC jest podobne.

  • Sprawdź, czy plik projektu został zaktualizowany do korzystania z wersji 2.1
  • Usuń następujące foldery i wszystkie pliki w nich:
    • Kontrolery
    • Strony/konto/
    • Rozszerzenia
  • Skompiluj projekt.
  • Tworzenie szkieletu Identity w projekcie:
    • Wybierz projekt zamykający plik _Layout.cshtml .
    • Wybierz ikonę + po prawej stronie klasy Kontekstu danych. Zaakceptuj nazwę domyślną.
    • Wybierz pozycję Dodaj , aby utworzyć nową klasę kontekstu danych. Utworzenie nowego kontekstu danych jest wymagane do tworzenia szkieletu. W następnej sekcji usuniesz nowy kontekst danych.

Aktualizuj po rusztowaniu Identity

  • Usuń klasę pochodną wygenerowaną IdentityDbContext przez szkielet w folderze Obszary/Identity/Dane/.Identity

  • Usuń folder Areas/Identity/IdentityHostingStartup.cs.

  • Zaktualizuj plik _LoginPartial.cshtml:

    • Przenieś plik Pages/_LoginPartial.cshtml do pliku Pages/Shared/_LoginPartial.cshtml.
    • Dodaj asp-area="Identity" do formularza i linków kotwicy.
    • <form /> Zaktualizuj element na <form asp-area="Identity" asp-page="/Account/Logout" asp-route-returnUrl="@Url.Page("/Index", new { area = "" })" method="post" id="logoutForm" class="navbar-right">.

    Poniższy kod przedstawia zaktualizowany plik _LoginPartial.cshtml :

    @using Microsoft.AspNetCore.Identity

@inject SignInManager<ApplicationUser> SignInManager
@inject UserManager<ApplicationUser> UserManager

@if (SignInManager.IsSignedIn(User))
{
    <form asp-area="Identity" asp-page="/Account/Logout" asp-route-returnUrl="@Url.Page("/Index", new { area = "" })" method="post" id="logoutForm" class="navbar-right">
        <ul class="nav navbar-nav navbar-right">
            <li>
                <a asp-area="Identity" asp-page="/Account/Manage/Index" title="Manage">Hello @UserManager.GetUserName(User)!</a>
            </li>
            <li>
                <button type="submit" class="btn btn-link navbar-btn navbar-link">Log out</button>
            </li>
        </ul>
    </form>
}
else
{
    <ul class="nav navbar-nav navbar-right">
        <li><a asp-area="Identity" asp-page="/Account/Register">Register</a></li>
        <li><a asp-area="Identity" asp-page="/Account/Login">Log in</a></li>
    </ul>
}

Zaktualizuj ConfigureServices za pomocą następującego kodu:

public void ConfigureServices(IServiceCollection services)
{
    services.AddDbContext<ApplicationDbContext>(options =>
        options.UseSqlServer(Configuration.GetConnectionString("DefaultConnection")));

    services.AddDefaultIdentity<ApplicationUser>()
        .AddEntityFrameworkStores<ApplicationDbContext>()
        .AddDefaultTokenProviders();

    services.AddMvc();

    // Register no-op EmailSender used by account confirmation and password reset 
    // during development
    services.AddSingleton<IEmailSender, EmailSender>();
}

Razor Zmiany w plikach projektów Razor Pages

Plik układu

  • Przenieś plik Pages/_Layout.cshtml do pliku Pages/Shared/_Layout.cshtml

  • W obszarze Areas//IdentityPages/_ViewStart.cshtml zmień wartość Layout = "/Pages/_Layout.cshtml" na Layout = "/Pages/Shared/_Layout.cshtml".

  • Plik _Layout.cshtml zawiera następujące zmiany:

_ValidationScriptsPartial.cshtml

  • Plik Pages/_ValidationScriptsPartial.cshtml przechodzi do pliku Pages/Shared/_ValidationScriptsPartial.cshtml.
  • jquery.validate/1.14.0 zmienia się na jquery.validate/1.17.0.

Nowe pliki

Dodawane są następujące pliki:

  • Privacy.cshtml
  • Privacy.cshtml.cs

Aby uzyskać informacje na temat powyższych plików, zobacz Obsługa RODO w programie ASP.NET Core .

Zmiany w plikach projektów Razor MVC

Plik układu

Plik Layout.cshtml zawiera następujące zmiany:

  • <partial name="_CookieConsentPartial" /> jest dodawany.
  • Tryb jQuery zmienia się z 2.2.0 na 3.3.1

_ValidationScriptsPartial.cshtml

jquery.validate/1.14.0 zmienia się na jquery.validate/1.17.0

Nowe pliki i metody akcji

Dodano następujące elementy:

  • Views/Home/Privacy.cshtml
  • Metoda Privacy akcji jest dodawana do Home kontrolera.

Aby uzyskać informacje na temat powyższych plików, zobacz Obsługa RODO w programie ASP.NET Core .

Zmiany w pliku launch Ustawienia.json

Ponieważ aplikacje ASP.NET Core domyślnie używają protokołu HTTPS, Properties/launchSettings.json plik został zmieniony.

JSPoniżej przedstawiono wcześniejszy plik wygenerowany przez launchSettings.json szablon w wersji 2.0:

{
  "iisSettings": {
    "windowsAuthentication": false,
    "anonymousAuthentication": true,
    "iisExpress": {
      "applicationUrl": "http://localhost:1799/",
      "sslPort": 0
    }
  },
  "profiles": {
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "WebApp1": {
      "commandName": "Project",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      },
      "applicationUrl": "http://localhost:1798/"
    }
  }
}

JSPoniższy plik ON przedstawia nowy plik wygenerowany przez launchSettings.json szablon 2.1:

{
  "iisSettings": {
    "windowsAuthentication": false, 
    "anonymousAuthentication": true, 
    "iisExpress": {
      "applicationUrl": "http://localhost:39191",
      "sslPort": 44390
    }
  },
  "profiles": {
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "WebApp1": {
      "commandName": "Project",
      "launchBrowser": true,
      "applicationUrl": "https://localhost:5001;http://localhost:5000",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

Aby uzyskać więcej informacji, zobacz Wymuszanie protokołu HTTPS w ASP.NET Core.

Zmiany powodujące niezgodność

Nagłówek Zakres właściwości FileResult

FileResult nie przetwarza już nagłówka Accept-Ranges domyślnie. Aby włączyć Accept-Ranges nagłówek, ustaw wartość trueEnableRangeProcessing .

Nagłówek ControllerBase.File i PhysicalFile Range

ControllerBase Następujące metody domyślnie nie przetwarzają nagłówka Accept-Ranges:

Aby włączyć Accept-Ranges nagłówek, ustaw EnableRangeProcessing parametr na true.

ASP.NET Core Module (ANCM)

Jeśli moduł ASP.NET Core Module (ANCM) nie był wybranym składnikiem, gdy program Visual Studio został zainstalowany lub czy wcześniejsza wersja narzędzia ANCM została zainstalowana w systemie, pobierz najnowszy Instalator pakietu hostingowego platformy .NET Core (pobieranie bezpośrednie) i uruchom instalatora. Aby uzyskać więcej informacji, zobacz Hosting Bundle (Pakiet hostingu).

Dodatkowe zmiany