Migrasi dari ASP.NET Core 2.1 ke 2.2

Oleh Scott Addie

Artikel ini menjelaskan cara memperbarui proyek ASP.NET Core 2.1 yang ada ke ASP.NET Core 2.2.

Prasyarat

Visual Studio

• Visual Studio 2019 dengan beban kerja pengembangan ASP.NET dan web
• .NET Core SDK 2.2 atau yang lebih baru

Peringatan

Jika Anda menggunakan Visual Studio 2017, lihat masalah dotnet/sdk #3124 untuk informasi tentang versi .NET Core SDK yang tidak berfungsi dengan Visual Studio.

Visual Studio Code

• Visual Studio Code
• C# for Visual Studio Code (versi terbaru)
• .NET Core SDK 2.2 atau yang lebih baru

Petunjuk Visual Studio Code menggunakan .NET Core CLI untuk fungsi pengembangan ASP.NET Core seperti pembuatan proyek. Anda dapat mengikuti petunjuk ini di platform apa pun (macOS, Linux, atau Windows) dan dengan editor kode apa pun. Mungkin diperlukan perubahan kecil jika Anda menggunakan editor selain Visual Studio Code.

Visual Studio untuk Mac

• Visual Studio untuk Mac versi 8.0 atau yang lebih baru
• .NET Core SDK 2.2 atau yang lebih baru

Memperbarui Target Framework Moniker (TFM)

Proyek yang menargetkan .NET Core harus menggunakan TFM versi yang lebih besar dari atau sama dengan .NET Core 2.2. Dalam file proyek, perbarui <TargetFramework> teks dalam simpul dengan netcoreapp2.2:

<TargetFramework>netcoreapp2.2</TargetFramework>

Proyek yang menargetkan .NET Framework dapat terus menggunakan TFM versi yang lebih besar dari atau sama dengan .NET Framework 4.6.1:

<TargetFramework>net461</TargetFramework>

Mengadopsi model hosting dalam proses IIS

Untuk mengadopsi model hosting dalam proses untuk IIS, tambahkan <AspNetCoreHostingModel> properti dengan nilai InProcess ke <PropertyGroup> dalam file proyek:

<AspNetCoreHostingModel>InProcess</AspNetCoreHostingModel>

Model hosting dalam proses tidak didukung untuk aplikasi ASP.NET Core yang menargetkan .NET Framework.

Untuk informasi lebih lanjut, lihat ASP.NET Core Module (ANCM) untuk IIS.

Memperbarui file web.config kustom

Untuk proyek yang menggunakan file web.config kustom di akar proyek untuk menghasilkan file web.config yang diterbitkan:

• <handlers> Dalam entri yang menambahkan ASP.NET Core Module (name="aspNetCore"), ubah modules nilai atribut dari AspNetCoreModule ke AspNetCoreModuleV2.
• <aspNetCore> Dalam elemen , tambahkan atribut model hosting (hostingModel="InProcess").

Untuk informasi selengkapnya dan contoh file web.config , lihat ASP.NET Core Module (ANCM) untuk IIS.

Memperbarui referensi paket

Jika menargetkan .NET Core, hapus atribut referensi Version metapackage dalam file proyek. Penyertaan atribut menghasilkan Version peringatan berikut:

A PackageReference to 'Microsoft.AspNetCore.App' specified a Version of `2.2.0`. Specifying the version of this package is not recommended. For more information, see https://aka.ms/sdkimplicitrefs

Untuk informasi selengkapnya, lihat Microsoft.AspNetCore.App metapackage untuk ASP.NET Core.

Referensi metapackage harus menyerupai node berikut <PackageReference /> :

<ItemGroup>
  <PackageReference Include="Microsoft.AspNetCore.App" />
</ItemGroup>

Jika menargetkan .NET Framework, perbarui atribut setiap referensi Version paket ke 2.2.0 atau yang lebih baru. Berikut adalah referensi paket dalam proyek ASP.NET Core 2.2 umum yang menargetkan .NET Framework:

<ItemGroup>
  <PackageReference Include="Microsoft.AspNetCore" Version="2.2.0" />
  <PackageReference Include="Microsoft.AspNetCore.CookiePolicy" Version="2.2.0" />
  <PackageReference Include="Microsoft.AspNetCore.HttpsPolicy" Version="2.2.0" />
  <PackageReference Include="Microsoft.AspNetCore.Mvc" Version="2.2.0" />
  <PackageReference Include="Microsoft.AspNetCore.StaticFiles" Version="2.2.0" />
</ItemGroup>

Jika mereferensikan Microsoft.AspNetCore.Razor. Paket desain , perbarui atributnya Version ke 2.2.0 atau yang lebih baru. Kegagalan untuk melakukannya menghasilkan kesalahan berikut:

Detected package downgrade: Microsoft.AspNetCore.Razor.Design from 2.2.0 to 2.1.2. Reference the package directly from the project to select a different version.

Memperbarui versi .NET Core SDK di global.json

Jika solusi Anda bergantung pada global.json file untuk menargetkan versi .NET Core SDK tertentu, perbarui propertinya version ke versi 2.2 yang diinstal pada komputer Anda:

{
  "sdk": {
    "version": "2.2.100"
  }
}

Memperbarui pengaturan peluncuran

Jika menggunakan Visual Studio Code, perbarui file pengaturan peluncuran proyek (.vscode/launch.json). Jalur program harus mereferensikan TFM baru:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": ".NET Core Launch (web)",
            "type": "coreclr",
            "request": "launch",
            "preLaunchTask": "build",
            "program": "${workspaceFolder}/bin/Debug/netcoreapp2.2/test-app.dll",
            "args": [],
            "cwd": "${workspaceFolder}",
            "stopAtEntry": false,
            "internalConsoleOptions": "openOnSessionStart",
            "launchBrowser": {
                "enabled": true,
                "args": "${auto-detect-url}",
                "windows": {
                    "command": "cmd.exe",
                    "args": "/C start ${auto-detect-url}"
                },
                "osx": {
                    "command": "open"
                },
                "linux": {
                    "command": "xdg-open"
                }
            },
            "env": {
                "ASPNETCORE_ENVIRONMENT": "Development"
            },
            "sourceFileMap": {
                "/Views": "${workspaceFolder}/Views"
            }
        },
        {
            "name": ".NET Core Attach",
            "type": "coreclr",
            "request": "attach",
            "processId": "${command:pickProcess}"
        }
    ]
}

Memperbarui Kestrel konfigurasi

Jika aplikasi memanggil UseKestrel dengan memanggil CreateDefaultBuilder dalam metode CreateWebHostBuilder kelas Program , panggil ConfigureKestrel untuk mengonfigurasi Kestrel server alih-alih UseKestrel untuk menghindari konflik dengan model hosting dalam proses IIS:

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureKestrel((context, options) =>
        {
            // Set properties and call methods on options
        });

Jika aplikasi tidak memanggil CreateDefaultBuilder dan membangun host secara manual di Program kelas, hubungi UseKestrelsebelum memanggil ConfigureKestrel:

public static void Main(string[] args)
{
    var host = new WebHostBuilder()
        .UseContentRoot(Directory.GetCurrentDirectory())
        .UseKestrel()
        .UseIISIntegration()
        .UseStartup<Startup>()
        .ConfigureKestrel((context, options) =>
        {
            // Set properties and call methods on options
        })
        .Build();

    host.Run();
}

Untuk informasi selengkapnya, lihat Kestrel server web di ASP.NET Core.

Memperbarui versi kompatibilitas

Perbarui versi kompatibilitas ke Startup.ConfigureServicesVersion_2_2:

services.AddMvc()
        .SetCompatibilityVersion(CompatibilityVersion.Version_2_2);

Memperbarui kebijakan CORS

Dalam ASP.NET Core 2.2, middleware CORS merespons dengan asal kartubebas (*) jika kebijakan mengizinkan asal dan mengizinkan kredensial. Kredensial tidak didukung saat asal kartubebas (*) ditentukan, dan browser akan melarang permintaan CORS. Untuk informasi selengkapnya, termasuk opsi untuk memperbaiki masalah pada klien, lihat dokumen web MDN.

Untuk memperbaiki masalah ini pada server, lakukan salah satu tindakan berikut:

• Ubah kebijakan CORS untuk tidak lagi mengizinkan kredensial. Artinya, hapus panggilan ke AllowCredentials saat mengonfigurasi kebijakan.
• Jika kredensial diperlukan agar permintaan CORS berhasil, ubah kebijakan untuk menentukan host yang diizinkan. Misalnya, gunakan builder.WithOrigins("https://api.example1.com", "https://example2.com") alih-alih menggunakan AllowAnyOrigin.

Memperbarui gambar Docker

Tabel berikut ini memperlihatkan perubahan tag gambar Docker:

2.1	2.2
microsoft/dotnet:2.1-aspnetcore-runtime	mcr.microsoft.com/dotnet/core/aspnet:2.2
microsoft/dotnet:2.1-sdk	mcr.microsoft.com/dotnet/core/sdk:2.2

FROM Ubah baris di Dockerfile Anda untuk menggunakan tag gambar baru di kolom 2.2 tabel sebelumnya.

Membangun secara manual di Visual Studio saat menggunakan hosting dalam proses IIS

Pengalaman permintaan Visual Studio's Auto build on browser tidak berfungsi dengan model hosting dalam proses IIS. Anda harus membangun kembali proyek secara manual saat menggunakan hosting dalam proses. Peningkatan pengalaman ini direncanakan untuk rilis Visual Studio di masa mendatang.

Memperbarui kode pengelogan

Kode konfigurasi pengelogan yang direkomendasikan tidak berubah dari 2.1 menjadi 2.2, tetapi beberapa pola pengodean 1.x yang masih berfungsi di 2.1 tidak lagi berfungsi di 2.2.

Jika aplikasi Anda melakukan inisialisasi, pemfilteran, dan pemuatan konfigurasi penyedia pengelogan di kelas, pindahkan kode tersebut Startup ke Program.Main:

• Inisialisasi penyedia:

  Contoh 1.x:

  public void Configure(IApplicationBuilder app, ILoggerFactory loggerFactory)
  {
      loggerFactory.AddConsole();
  }
  

  Contoh 2.2:

  
  public static void Main(string[] args)
  {
      var webHost = new WebHostBuilder()
          // ...
          .ConfigureLogging((hostingContext, logging) =>
          {
              logging.AddConsole();
          })
          // ...
  }
  

• Penyaringan:

  Contoh 1.x:

  public void Configure(IApplicationBuilder app, ILoggerFactory loggerFactory)
  {
      loggerFactory.AddConsole(LogLevel.Information);
      // or
      loggerFactory.AddConsole((category, level) => 
          category == "A" || level == LogLevel.Critical);
  }
  

  Contoh 2.2:

  public static void Main(string[] args)
  {
      var webHost = new WebHostBuilder()
          // ...
          .ConfigureLogging((hostingContext, logging) =>
          {
              logging.AddConsole()
                     .AddFilter<ConsoleLoggerProvider>
                         (category: null, level: LogLevel.Information)
                     // or
                     .AddFilter<ConsoleLoggerProvider>
                         ((category, level) => category == "A" ||
                             level == LogLevel.Critical)
              );
          })
          // ...
  }
  

• Pemuatan konfigurasi:

  Contoh 1.x:

  public void Configure(IApplicationBuilder app, ILoggerFactory loggerFactory)
  {
      loggerFactory.AddConsole(Configuration);
  }
  

  Contoh 2.2:

  public static void Main(string[] args)
  {
      var webHost = new WebHostBuilder()
          // ...
          .ConfigureLogging((hostingContext, logging) =>
          {
              logging.AddConfiguration(hostingContext.Configuration.GetSection("Logging"));
              logging.AddConsole();
          })
          // ...
  }
  

Untuk informasi selengkapnya, lihat Pengelogan di .NET Core dan ASP.NET Core

Modul Inti ASP.NET (ANCM)

Jika ASP.NET Core Module (ANCM) bukan komponen yang dipilih saat Visual Studio diinstal atau jika versi ANCM sebelumnya diinstal pada sistem, unduh Penginstal Bundel Hosting .NET Core terbaru (unduh langsung) dan jalankan alat penginstal. Untuk informasi selengkapnya, lihat Bundel Hosting.

Sumber Daya Tambahan:

• Versi kompatibilitas untuk ASP.NET Core MVC
• Microsoft.AspNetCore.App metapackage untuk ASP.NET Core
• Referensi paket implisit