Migrar de ASP.NET Core 2.0 a 2.1

Artículo
09/13/2021
Tiempo de lectura: 5 minutos

Consulte Novedades de ASP.NET Core 2.1 para obtener información general sobre las nuevas características de ASP.NET Core 2.1.

En este artículo:

Trata los conceptos básicos de la migración de ASP.NET Core aplicación 2.0 a 2.1.
Proporciona información general sobre los cambios en las plantillas de ASP.NET Core web.

Una manera rápida de obtener información general de los cambios de la versión 2.1 es:

Cree una ASP.NET Core web 2.0 denominada WebApp1.
Confirme WebApp1 en un sistema de control de código fuente.
Elimine WebApp1 y cree una ASP.NET Core web 2.1 denominada WebApp1 en el mismo lugar.
Revise los cambios en la versión 2.1.

En este artículo se proporciona información general sobre la migración ASP.NET Core 2.1. No contiene una lista completa de todos los cambios necesarios para migrar a la versión 2.1. Algunos proyectos pueden requerir más pasos en función de las opciones seleccionadas cuando se creó el proyecto y las modificaciones realizadas en el proyecto.

Actualización del archivo de proyecto para que use las versiones 2.1

Actualice el archivo del proyecto:

Cambie la plataforma de destino a .NET Core 2.1 actualizando el archivo de proyecto a <TargetFramework>netcoreapp2.1</TargetFramework> .
Reemplace la referencia de paquete de Microsoft.AspNetCore.All por una referencia de paquete para Microsoft.AspNetCore.App . Es posible que tenga que agregar dependencias que se quitaron de Microsoft.AspNetCore.All . Para obtener más información, vea Metapaquete Microsoft.AspNetCore.All para ASP.NET Core 2.0 y Metapaquete Microsoft.AspNetCore.App para ASP.NET Core.
Quite el atributo "Version" de la referencia del paquete a Microsoft.AspNetCore.App . Los proyectos que <Project Sdk="Microsoft.NET.Sdk.Web"> usan no necesitan establecer la versión. La versión está implícita en la plataforma de destino y se selecciona para que coincida mejor con ASP.NET Core funciona la versión 2.1. Para obtener más información, vea la sección Reglas para proyectos que tienen como destino el marco compartido.
Para las aplicaciones que tienen como destino .NET Framework, actualice cada referencia de paquete a 2.1.
Quite las referencias < a > los elementos DotNetCliToolReference para los siguientes paquetes. Estas herramientas se incluyen de forma predeterminada en CLI de .NET Core y no es necesario instalarse por separado.
- 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 )
Opcional: puede quitar el < elemento > DotNetCliToolReference para Microsoft.VisualStudio.Web.CodeGeneration.Tools . Puede reemplazar esta herramienta por una versión instalada globalmente mediante la ejecución de dotnet tool install -g dotnet-aspnet-codegenerator .
Para la versión 2.1, una biblioteca Razor de clases es la solución recomendada para distribuir Razor archivos. Si la aplicación usa vistas insertadas o, de lo contrario, se basa en la compilación de archivos en tiempo de Razor ejecución, <CopyRefAssembliesToPublishDirectory>true</CopyRefAssembliesToPublishDirectory> agregue a en el archivo del <PropertyGroup> proyecto.

El marcado siguiente muestra el archivo de proyecto 2.0 generado por la plantilla:

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

El marcado siguiente muestra el archivo de proyecto 2.1 generado por la plantilla:

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

Reglas para proyectos que tienen como destino el marco compartido

Un marco compartido es un conjunto de ensamblados (archivos .dll) que no están en las carpetas de la aplicación. El marco de trabajo compartido debe instalarse en la máquina para ejecutar la aplicación. Para más información, consulte este artículo sobre el marco de trabajo compartido.

ASP.NET Core 2.1 incluye los siguientes marcos compartidos:

La versión especificada por la referencia del paquete es la versión mínima necesaria. Por ejemplo, un proyecto que hace referencia a las versiones 2.1.1 de estos paquetes no se ejecutará en una máquina con solo el runtime 2.1.0 instalado.

Problemas conocidos de los proyectos que tienen como destino un marco compartido:

El SDK de .NET Core 2.1.300 (incluido por primera vez en Visual Studio 15.6) establece la versión implícita de en Microsoft.AspNetCore.App 2.1.0, lo que provocó conflictos con Entity Framework Core 2.1.1. La solución recomendada es actualizar el SDK de .NET Core a 2.1.301 o posterior. Para obtener más información, vea Paquetes que comparten dependencias con Microsoft.AspNetCore.App no pueden hacer referencia a versiones de revisión.
Todos los proyectos que deben usar o deben agregar una referencia de paquete para el paquete en el archivo de proyecto, incluso si contienen una referencia de proyecto Microsoft.AspNetCore.All a otro proyecto mediante o Microsoft.AspNetCore.App Microsoft.AspNetCore.All Microsoft.AspNetCore.App .

Ejemplo:
- MyApp tiene una referencia de paquete a Microsoft.AspNetCore.App .
- MyApp.Tests tiene una referencia de proyecto a MyApp.csproj .
Agregue una referencia de paquete para Microsoft.AspNetCore.App a MyApp.Tests . Para obtener más información, vea Pruebas de integración es difícil de configurar y puede interrumpiren el mantenimiento del marco compartido.

Actualización a las imágenes de Docker 2.1

En ASP.NET Core 2.1, las imágenes de Docker migradas al repositorio dotnet/dotnet-docker GitHub repositorio. En la tabla siguiente se muestran los cambios de imagen y etiqueta de 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

Cambie las líneas del Dockerfile para usar los nuevos nombres de imagen y etiquetas de la columna FROM 2.1 de la tabla anterior. Para obtener más información, consulte Migración de repositorios de Docker de aspnetcore a dotnet.

Cambios para aprovechar las nuevas expresiones basadas en código que se recomiendan en ASP.NET Core 2.1

Cambios en Main

En las imágenes siguientes se muestran los cambios realizados en el archivo Program.cs generado con plantilla.

diferencias de versión anterior

La imagen anterior muestra la versión 2.0 con las eliminaciones en rojo.

En la imagen siguiente se muestra el código 2.1. El código en verde ha reemplazado a la versión 2.0:

nuevas diferencias de versión

El código siguiente muestra la versión 2.1 de 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>();
    }
}

El nuevo Main reemplaza la llamada a por BuildWebHost CreateWebHostBuilder. IWebHostBuilder se agregó para admitir una nueva infraestructura de prueba de integración.

Cambios en el inicio

El código siguiente muestra los cambios en el código generado por la plantilla 2.1. Todos los cambios son código recién agregado, excepto UseBrowserLink que se ha quitado:

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

Los cambios de código anteriores se detallan en:

Compatibilidad con rgpd en ASP.NET Core para y CookiePolicyOptions UseCookiePolicy .
Protocolo de seguridad de transporte estricto (HSTS) HTTP para UseHsts .
Requerir HTTPS para UseHttpsRedirection .
SetCompatibilityVersion para SetCompatibilityVersion(CompatibilityVersion.Version_2_1) .

Cambios en el código de autenticación

ASP.NET Core 2.1 proporciona ASP.NET Core Identity como biblioteca Razor de clases (RCL).

La interfaz de usuario predeterminada 2.1 no proporciona actualmente características Identity nuevas significativas en la versión 2.0. Reemplazar por Identity el paquete de RCL es opcional. Entre las ventajas de reemplazar el código generado por Identity la plantilla por la versión de RCL se incluyen las siguientes:

Muchos archivos se mueven fuera del árbol de origen.
Las correcciones de errores o las nuevas Identity características de se incluyen en Microsoft.AspNetCore.App metapaquete. La actualización se obtiene automáticamente Identity cuando Microsoft.AspNetCore.App se actualiza.

Si ha realizado cambios no triviales en el código generado por la Identity plantilla:

Las ventajas anteriores probablemente no justifican la conversión a la versión de RCL.
Puede mantener el código ASP.NET Core 2.0, Identity es totalmente compatible.

Identity 2.1 expone los puntos de conexión con el Identity área . Por ejemplo, en la tabla siguiente se muestran ejemplos de puntos de conexión Identity que cambian de 2.0 a 2.1:

Dirección URL 2.0	Dirección URL 2.1
/Account/Login	/Identity/Account/Login
/Account/Logout	/Identity/Account/Logout
/Account/Manage	/Identity/Account/Manage

Las aplicaciones que tienen código que usa y reemplazan la interfaz de usuario 2.0 por la biblioteca Identity Identity 2.1 deben tener en cuenta las direcciones URL que tienen el segmento anteponer a los Identity Identity /Identity URI. Una manera de controlar los nuevos puntos Identity de conexión es configurar redireccionamientos, por ejemplo de a /Account/Login /Identity/Account/Login .

Actualización Identity a la versión 2.1

Las siguientes opciones están disponibles para Identity actualizarse a la versión 2.1.

Use el Identity código de la interfaz de usuario 2.0 sin cambios. El uso de código de la interfaz de usuario Identity 2.0 es totalmente compatible. Este es un buen enfoque cuando se han realizado cambios significativos en el código Identity generado.
Elimine el código Identity 2.0 existente y Identity scaffold en el proyecto. El proyecto usará la biblioteca ASP.NET Core Identity Razor de clases. Puede generar código e interfaz de usuario para cualquiera de los códigos de Identity interfaz de usuario que ha modificado. Aplique los cambios de código al código de interfaz de usuario con scaffolding recién.
Elimine el código Identity 2.0 existente y Identity scaffolding en el proyecto con la opción invalidar todos los archivos.

Reemplazar Identity la interfaz de usuario 2.0 por la biblioteca de clases Identity 2.1 Razor

En esta sección se describen los pasos para reemplazar el código generado ASP.NET Core plantilla 2.0 por Identity la biblioteca ASP.NET Core Identity Razor de clases. Los pasos siguientes son para un Razor proyecto de Pages, pero el enfoque de un proyecto MVC es similar.

Comprobación de que el archivo de proyecto está actualizado para usar las versiones 2.1
Elimine las siguientes carpetas y todos los archivos que hay en ellas:
- Controladores
- Pages/Account/
- Extensiones
Compile el proyecto.
Scaffolding Identity en el proyecto:
- Seleccione los proyectos que salen _ del archivo Layout.cshtml.
- Seleccione el + icono del lado derecho de la clase de contexto De datos. Acepte el nombre predeterminado.
- Seleccione Agregar para crear una nueva clase de contexto de datos. Para crear un nuevo contexto de datos, es necesario usar scaffolding. Quite el nuevo contexto de datos en la sección siguiente.

Actualización después de scaffolding Identity

Elimine la Identity clase derivada generada por scaffolder en la carpeta IdentityDbContext Areas/ Identity /Data/.
Delete Identity / Identity Areas/HostingStartup.cs.

Actualice el _ archivo LoginPartial.cshtml:

Mueva _ Pages/LoginPartial.cshtml a Pages/Shared/ _ LoginPartial.cshtml.
Agregue asp-area="Identity" al formulario y los vínculos delimitadores.
Actualice el <form /> elemento a <form asp-area="Identity" asp-page="/Account/Logout" asp-route-returnUrl="@Url.Page("/Index", new { area = "" })" method="post" id="logoutForm" class="navbar-right"> .

El código siguiente muestra el archivo _ LoginPartial.cshtml actualizado:

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

Actualice ConfigureServices con el siguiente código:

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

Cambios en archivos Razor de proyectos de Razor Pages

El archivo de diseño

Mover _ Pages/Layout.cshtml a Pages/Shared/ _ Layout.cshtml
En Areas/ Identity /Pages/ _ ViewStart.cshtml, cambie Layout = "/Pages/_Layout.cshtml" a Layout = "/Pages/Shared/_Layout.cshtml" .
El _ archivo Layout.cshtml tiene los siguientes cambios:
- <partial name="_CookieConsentPartial" /> se agrega. Para más información, vea GDPR support in ASP.NET Core (Compatibilidad con el Reglamento general de protección de datos en ASP.NET Core).
- jQuery cambia de 2.2.0 a 3.3.1.

_ValidationScriptsPartial.cshtml

Pages/ _ ValidationScriptsPartial.cshtml se mueve a Pages/Shared/ _ ValidationScriptsPartial.cshtml.
jquery.validate/1.14.0 cambia a jquery.validate/1.17.0.

Nuevos archivos

Se agregan los siguientes archivos:

Privacy.cshtml
Privacy.cshtml.cs

Consulte Compatibilidad con RGPD en ASP.NET Core para obtener información sobre los archivos anteriores.

Cambios en los archivos de proyectos de Razor MVC

El archivo de diseño

El archivo Layout.cshtml tiene los siguientes cambios:

<partial name="_CookieConsentPartial" /> se agrega.
jQuery cambia de 2.2.0 a 3.3.1

_ValidationScriptsPartial.cshtml

jquery.validate/1.14.0 cambia a jquery.validate/1.17.0

Nuevos archivos y métodos de acción

Se agregan los siguientes elementos:

Views/ Home / Privacy .cshtml
El Privacy método de acción se agrega al Home controlador.

Consulte Compatibilidad con RGPD en ASP.NET Core para obtener información sobre los archivos anteriores.

Cambios en la launchSettings.jsen el archivo

Como ASP.NET Core aplicaciones ahora usan HTTPS de forma predeterminada, las propiedades o launchSettings.jsen el archivo han cambiado.

En el siguiente json se muestran las versiones anteriores de la plantilla 2.0 generadaslaunchSettings.jsarchivo:

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

En el siguiente json se muestra la nueva plantilla 2.1 generada launchSettings.jsarchivo:

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

Para más información, consulte Aplicación de HTTPS en ASP.NET Core.

Últimos cambios

Encabezado FileResult Range

FileResult ya no procesa el encabezado Accept-Ranges de forma predeterminada. Para habilitar el Accept-Ranges encabezado, establezca EnableRangeProcessing en true .

Encabezado ControllerBase.File y PhysicalFile Range

Los ControllerBase métodos siguientes ya no procesa el encabezado Accept-Ranges de forma predeterminada:

Sobrecargas de ControllerBase.File
ControllerBase.PhysicalFile

Para habilitar el Accept-Ranges encabezado, establezca el EnableRangeProcessing parámetro en true .

Cambios adicionales

Si hospeda la aplicación en Windows con IIS, instale el paquete de hospedaje de .NET Core más reciente.
SetCompatibilityVersion
Configuración de transporte de Libuv

Migrar de ASP.NET Core 2.0 a 2.1

Valore su experiencia

Actualización del archivo de proyecto para que use las versiones 2.1

Reglas para proyectos que tienen como destino el marco compartido

Actualización a las imágenes de Docker 2.1

Cambios para aprovechar las nuevas expresiones basadas en código que se recomiendan en ASP.NET Core 2.1

Cambios en Main

Cambios en el inicio

Cambios en el código de autenticación

Actualización Identity a la versión 2.1

Reemplazar Identity la interfaz de usuario 2.0 por la biblioteca de clases Identity 2.1 Razor

Actualización después de scaffolding Identity

Cambios en archivos Razor de proyectos de Razor Pages

El archivo de diseño

_ValidationScriptsPartial.cshtml

Nuevos archivos

Cambios en los archivos de proyectos de Razor MVC

El archivo de diseño

_ValidationScriptsPartial.cshtml

Nuevos archivos y métodos de acción

Cambios en la launchSettings.jsen el archivo

Últimos cambios

Encabezado FileResult Range

Encabezado ControllerBase.File y PhysicalFile Range

Cambios adicionales