Eseguire la migrazione da ASP.NET Core 2.0 alla versione 2.1

Di Rick Anderson

Per una panoramica delle nuove funzionalità di ASP.NET Core 2.1, vedere Novità di ASP.NET Core 2.1 .

Questo articolo:

• Vengono illustrate le nozioni di base sulla migrazione di un'app ASP.NET Core 2.0 alla versione 2.1.
• Fornisce una panoramica delle modifiche apportate ai modelli di applicazione Web ASP.NET Core.

Un modo rapido per ottenere una panoramica delle modifiche nella versione 2.1 consiste nel:

• Creare un'app Web ASP.NET Core 2.0 denominata WebApp1.
• Eseguire il commit di WebApp1 in un sistema di controllo del codice sorgente.
• Eliminare WebApp1 e creare un'app Web ASP.NET Core 2.1 denominata WebApp1 nella stessa posizione.
• Esaminare le modifiche nella versione 2.1.

Questo articolo offre una panoramica sulla migrazione a ASP.NET Core 2.1. Non contiene un elenco completo di tutte le modifiche necessarie per eseguire la migrazione alla versione 2.1. Alcuni progetti potrebbero richiedere più passaggi a seconda delle opzioni selezionate quando il progetto è stato creato e le modifiche apportate al progetto.

Aggiornare il file di progetto per usare le versioni 2.1

Aggiornare il file di progetto:

• Modificare il framework di destinazione in .NET Core 2.1 aggiornando il file di progetto in <TargetFramework>netcoreapp2.1</TargetFramework>.
• Sostituire il riferimento al pacchetto per Microsoft.AspNetCore.All con un riferimento al pacchetto per Microsoft.AspNetCore.App. Potrebbe essere necessario aggiungere dipendenze rimosse da Microsoft.AspNetCore.All. Per altre informazioni, vedere il metapacchetto Microsoft.AspNetCore.All per ASP.NET Core 2.0 e Microsoft.AspNetCore.App metapacchetto per ASP.NET Core.
• Rimuovere l'attributo "Version" nel riferimento al pacchetto a Microsoft.AspNetCore.App. I progetti che usano <Project Sdk="Microsoft.NET.Sdk.Web"> non devono impostare la versione. La versione è implicita dal framework di destinazione e selezionata in modo che corrisponda al modo in cui funziona ASP.NET Core 2.1. Per altre informazioni, vedere la sezione Regole per i progetti destinati al framework condiviso.
• Per le app destinate a .NET Framework, aggiornare ogni riferimento al pacchetto alla versione 2.1.
• Rimuovere i riferimenti agli <elementi DotNetCliToolReference> per i pacchetti seguenti. Questi strumenti sono raggruppati per impostazione predefinita nell'interfaccia della riga di comando di .NET e non devono essere installati separatamente.
  • Microsoft.DotNet.Watcher.Tools (dotnet watch)
  • Microsoft.EntityFrameworkCore.Tools.DotNet (dotnet ef)
  • Microsoft.Extensions.Caching.SqlConfig.Tools (dotnet sql-cache)
  • Microsoft.Extensions.SecretManager.Tools (dotnet user-secrets)
• Facoltativo: è possibile rimuovere l'elemento <DotNetCliToolReference> per Microsoft.VisualStudio.Web.CodeGeneration.Tools. È possibile sostituire questo strumento con una versione installata a livello globale eseguendo dotnet tool install -g dotnet-aspnet-codegenerator.
• Per la versione 2.1, una Razor libreria di classi è la soluzione consigliata per distribuire i Razor file. Se l'app usa visualizzazioni incorporate o in caso contrario si basa sulla compilazione in fase di esecuzione dei file, aggiungere <CopyRefAssembliesToPublishDirectory>true</CopyRefAssembliesToPublishDirectory> a un <PropertyGroup> nel file di Razor progetto.

Il markup seguente mostra il file di progetto 2.0 generato dal modello:

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

Il markup seguente mostra il file di progetto 2.1 generato dal modello:

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

Regole per i progetti destinati al framework condiviso

Un framework condiviso è un set di assembly (file DLL) che non sono presenti nelle cartelle dell'app. Il framework condiviso deve essere installato nel computer per eseguire l'app. Per altre informazioni, vedere The shared framework (Il framework condiviso).

ASP.NET Core 2.1 include i framework condivisi seguenti:

• Microsoft.AspNetCore.App
• Microsoft.AspNetCore.All

La versione specificata dal riferimento al pacchetto è la versione minima richiesta . Ad esempio, un progetto che fa riferimento alle versioni 2.1.1 di questi pacchetti non verrà eseguito in un computer con solo il runtime 2.1.0 installato.

Problemi noti per i progetti destinati a un framework condiviso:

• .NET Core 2.1.300 SDK (incluso in Visual Studio 15.6) imposta la versione implicita di Microsoft.AspNetCore.App su 2.1.0 che ha causato conflitti con Entity Framework Core 2.1.1. La soluzione consigliata consiste nell'aggiornare .NET Core SDK alla versione 2.1.301 o successiva. Per altre informazioni, vedere Pacchetti che condividono dipendenze con Microsoft.AspNetCore.App non possono fare riferimento a versioni patch.

• Tutti i progetti che devono usare Microsoft.AspNetCore.All o Microsoft.AspNetCore.App devono aggiungere un riferimento al pacchetto per il pacchetto nel file di progetto, anche se contengono un riferimento al progetto a un altro progetto usando Microsoft.AspNetCore.All o Microsoft.AspNetCore.App.

  Esempio:

  • MyApp ha un riferimento al pacchetto a Microsoft.AspNetCore.App.
  • MyApp.Tests ha un riferimento al progetto a MyApp.csproj.

  Aggiungere un riferimento al pacchetto per Microsoft.AspNetCore.App a MyApp.Tests. Per altre informazioni, vedere Integration testing is hard to set up and may break on shared framework servicing .For more information, see Integration testing is hard to set up and may break on shared framework servicing.

Eseguire l'aggiornamento alle immagini Docker 2.1

In ASP.NET Core 2.1, le immagini Docker sono migrate nel repository GitHub dotnet/dotnet-docker. La tabella seguente illustra le modifiche apportate all'immagine e al tag 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

Modificare le FROM righe nel Dockerfile in modo da usare i nuovi nomi di immagine e tag nella colonna 2.1 della tabella precedente. Per altre informazioni, vedere Migrazione da aspnetcore docker repos a dotnet.

Modifiche per sfruttare i nuovi idiomi basati su codice consigliati in ASP.NET Core 2.1

Modifiche apportate a Main

Le immagini seguenti mostrano le modifiche apportate al file generato dal Program.cs modello.

L'immagine precedente mostra la versione 2.0 con le eliminazioni in rosso.

L'immagine seguente mostra il codice 2.1. Il codice in verde ha sostituito la versione 2.0:

Il codice seguente illustra la versione 2.1 di 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>();
    }
}

Il nuovo Main sostituisce la chiamata a BuildWebHost con CreateWebHostBuilder. IWebHostBuilder è stato aggiunto per supportare una nuova infrastruttura di test di integrazione.

Modifiche all'avvio

Il codice seguente mostra le modifiche apportate al codice generato dal modello 2.1. Tutte le modifiche vengono appena aggiunte, ad eccezione del fatto che UseBrowserLink sono state rimosse:

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();
        }
    }
}

Le modifiche al codice precedenti sono descritte in dettaglio:

• Supporto gdpr in ASP.NET Core per CookiePolicyOptions e UseCookiePolicy.
• HTTP Strict Transport Security Protocol (HSTS) per UseHsts.
• Richiedi HTTPS per UseHttpsRedirection.
• SetCompatibilityVersion per SetCompatibilityVersion(CompatibilityVersion.Version_2_1).

Modifiche al codice di autenticazione

ASP.NET Core 2.1 fornisce ASP.NET Core Identitycome libreria di Razor classi (RCL).

L'interfaccia utente predefinita 2.1 Identity attualmente non fornisce nuove funzionalità significative rispetto alla versione 2.0. La sostituzione Identity con il pacchetto RCL è facoltativa. I vantaggi della sostituzione del codice generato Identity dal modello con la versione RCL includono:

• Molti file vengono spostati dall'albero di origine.
• Eventuali correzioni di bug o nuove funzionalità da Identity includere nel metapacchetto Microsoft.AspNetCore.App. Si ottiene automaticamente l'aggiornamento Identity quando Microsoft.AspNetCore.App viene aggiornato.

Se sono state apportate modifiche non semplici al codice generato Identity dal modello:

• I vantaggi precedenti probabilmente non giustificano la conversione nella versione RCL.
• È possibile mantenere il codice ASP.NET Core 2.0 Identity , che è completamente supportato.

Identity 2.1 espone gli endpoint con l'area Identity . Ad esempio, la tabella seguente mostra esempi di Identity endpoint che cambiano da 2.0 a 2.1:

2.0 URL	2.1 URL
/Account/Account di accesso	/Identity/Account/Login
/Account/Disconnessione	/Identity/Account/Disconnessione
/Account/Gestisci	/Identity/Account/Manage

Le applicazioni con codice che usano Identity e sostituiscono l'interfaccia utente 2.0 Identity con la libreria 2.1 Identity devono tenere conto Identity che gli URL hanno /Identity anteporre un segmento agli URI. Un modo per gestire i nuovi Identity endpoint consiste nel configurare i reindirizzamenti, ad esempio da /Account/Login a /Identity/Account/Login.

Aggiornamento Identity alla versione 2.1

Per l'aggiornamento Identity alla versione 2.1 sono disponibili le opzioni seguenti.

• Usare il codice dell'interfaccia Identity utente 2.0 senza modifiche. L'uso del Identity codice dell'interfaccia utente 2.0 è completamente supportato. Si tratta di un approccio efficace quando sono state apportate modifiche significative al codice generato Identity .
• Eliminare il codice 2.0 esistente Identity e lo scaffolding Identity nel progetto. Il progetto userà la libreria di classi ASP.NET Core Identity Razor. È possibile generare codice e interfaccia utente per qualsiasi codice dell'interfaccia Identity utente modificato. Applicare le modifiche al codice dell'interfaccia utente appena sottoposto a scaffolding.
• Eliminare il codice 2.0 esistente Identity e eseguire lo Scaffolding Identity nel progetto con l'opzione Override di tutti i file.

Sostituire Identity l'interfaccia utente 2.0 con la Identity libreria di classi 2.1 Razor

Questa sezione illustra i passaggi per sostituire il codice generato Identity dal modello ASP.NET Core 2.0 con la libreria di classi ASP.NET CoreRazor Identity . I passaggi seguenti sono relativi a un Razor progetto Pages, ma l'approccio per un progetto MVC è simile.

• Verificare che il file di progetto sia aggiornato per usare le versioni 2.1
• Eliminare le cartelle seguenti e tutti i file in essi contenuti:
  • Controller
  • Pagine/Account/
  • Estensioni
• Compilare il progetto.
• Eseguire lo scaffolding Identity nel progetto:
  • Selezionare i progetti che escono dal file _Layout.cshtml .
  • Selezionare l'icona + a destra della classe Contesto dati. Accettare il nome predefinito.
  • Selezionare Aggiungi per creare una nuova classe contesto dati. Per eseguire lo scaffolding è necessario creare un nuovo contesto dati. Rimuovere il nuovo contesto dati nella sezione successiva.

Aggiornare dopo lo scaffolding Identity

• Eliminare la Identity classe derivata generata IdentityDbContext dallo scaffolder nella cartella Areas/Identity/Data/ .

• Eliminare Areas/Identity/IdentityHostingStartup.cs.

• Aggiornare il file _LoginPartial.cshtml :

  • Spostare Pages/_LoginPartial.cshtml in Pages/Shared/_LoginPartial.cshtml.
  • Aggiungere asp-area="Identity" al modulo e ai collegamenti di ancoraggio.
  • Aggiornare l'elemento <form /> a <form asp-area="Identity" asp-page="/Account/Logout" asp-route-returnUrl="@Url.Page("/Index", new { area = "" })" method="post" id="logoutForm" class="navbar-right">.

  Il codice seguente mostra il file _LoginPartial.cshtml aggiornato:

  @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>
  }
  

Aggiornare ConfigureServices con il codice seguente:

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>();
}

Modifiche ai Razor file di progetti Razor Pages

File di layout

• Spostare Pages/_Layout.cshtml in Pages/Shared/_Layout.cshtml

• In Areas//IdentityPages/_ViewStart.cshtml passare Layout = "/Pages/_Layout.cshtml" a Layout = "/Pages/Shared/_Layout.cshtml".

• Il file _Layout.cshtml presenta le modifiche seguenti:

  • <partial name="_CookieConsentPartial" /> viene aggiunto. Per altre informazioni, vedere Supporto per il Regolamento generale sulla protezione dei dati in ASP.NET Core.
  • jQuery cambia da 2.2.0 a 3.3.1.

_ValidationScriptsPartial.cshtml

• Pages/_ValidationScriptsPartial.cshtml passa a Pages/Shared/_ValidationScriptsPartial.cshtml.
• jquery.validate/1.14.0 cambia in jquery.validate/1.17.0.

Nuovi file

Vengono aggiunti i file seguenti:

• Privacy.cshtml
• Privacy.cshtml.cs

Per informazioni sui file precedenti, vedere Il supporto gdpr in ASP.NET Core .

Modifiche ai file di progetti Razor MVC

File di layout

Il Layout.cshtml file presenta le modifiche seguenti:

• <partial name="_CookieConsentPartial" /> viene aggiunto.
• jQuery cambia da 2.2.0 a 3.3.1

_ValidationScriptsPartial.cshtml

jquery.validate/1.14.0 modifiche a jquery.validate/1.17.0

Nuovi file e metodi di azione

Vengono aggiunti gli elementi seguenti:

• Views/Home/Privacy.cshtml
• Il Privacy metodo di azione viene aggiunto al Home controller.

Per informazioni sui file precedenti, vedere Il supporto gdpr in ASP.NET Core .

Modifiche al file di launchSettings.json

Come ASP.NET app Core ora usano HTTPS per impostazione predefinita, il Properties/launchSettings.json file è stato modificato.

Il codice JSON seguente mostra il file generato dal launchSettings.json modello 2.0 precedente:

{
  "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/"
    }
  }
}

Il codice JSON seguente mostra il nuovo file generato dal launchSettings.json modello 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"
      }
    }
  }
}

Per altre informazioni, vedere Applicare HTTPS in ASP.NET Core.

Modifiche di rilievo

Intestazione Intervallo FileResult

FileResult non elabora più l'intestazione Accept-Ranges per impostazione predefinita. Per abilitare l'intestazione Accept-Ranges , impostare su EnableRangeProcessing true.

Intestazione ControllerBase.File e PhysicalFile Range

Per impostazione predefinita, i metodi seguenti ControllerBase non elaborano più l'intestazione Accept-Ranges :

• Overload di ControllerBase.File
• ControllerBase.PhysicalFile

Per abilitare l'intestazione Accept-Ranges , impostare il EnableRangeProcessing parametro su true.

modulo ASP.NET core (ANCM)

Se la ASP.NET Core Module (ANCM) non è un componente selezionato quando Visual Studio è stato installato o se è stata installata una versione precedente di ANCM nel sistema, scaricare l'ultimo programma di installazione del bundle di hosting .NET Core (download diretto) ed eseguire il programma di installazione. Per altre informazioni, vedere Bundle di hosting.

Ulteriori modifiche

• SetCompatibilityVersion
• Configurazione del trasporto Libuv