Sdílet prostřednictvím

Migrace z ASP.NET Core 2.2 na verzi 3.0

Scott Addie a Rick Anderson

Tento článek vysvětluje, jak aktualizovat existující projekt ASP.NET Core 2.2 na ASP.NET Core 3.0. Může být užitečné vytvořit nový projekt ASP.NET Core 3.0 pro:

  • Porovnejte s kódem ASP.NET Core 2.2.
  • Zkopírujte relevantní změny do projektu ASP.NET Core 3.0.

Požadavky

Aktualizace verze sady .NET Core SDK v global.json

Pokud vaše řešení spoléhá na global.json soubor, který cílí na konkrétní verzi sady .NET Core SDK, aktualizujte jeho version vlastnost na verzi 3.0 nainstalovanou na vašem počítači:

{
  "sdk": {
    "version": "3.0.100"
  }
}

Aktualizace souboru projektu

Aktualizace cílové architektury

ASP.NET Core 3.0 nebo novější běží jenom v .NET Core. Nastavte Target Framework Moniker (TFM) na netcoreapp3.0:

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

  <PropertyGroup>
    <TargetFramework>netcoreapp3.0</TargetFramework>
  </PropertyGroup>

</Project>

Odebrání zastaralých odkazů na balíčky

Pro ASP.NET Core 3.0 se nevygeneruje velký počet balíčků NuGet. Tyto odkazy na balíčky by se měly odebrat ze souboru projektu. Zvažte následující soubor projektu pro webovou aplikaci ASP.NET Core 2.2:

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

  <PropertyGroup>
    <TargetFramework>netcoreapp2.2</TargetFramework>
    <AspNetCoreHostingModel>InProcess</AspNetCoreHostingModel>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.App"/>
    <PackageReference Include="Microsoft.AspNetCore.Razor.Design" Version="2.2.0" PrivateAssets="All" />
  </ItemGroup>

</Project>

Aktualizovaný soubor projektu pro ASP.NET Core 3.0:

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

  <PropertyGroup>
    <TargetFramework>netcoreapp3.0</TargetFramework>
  </PropertyGroup>

</Project>

Aktualizovaný soubor projektu ASP.NET Core 3.0:

  • V <PropertyGroup>:

    • Aktualizuje TFM na netcoreapp3.0
    • Odebere <AspNetCoreHostingModel> prvek. Další informace naleznete v části model hostování v procesu v tomto dokumentu.

  • V <ItemGroup>:

    • Microsoft.AspNetCore.App je odebrán. Další informace naleznete v tématu Framework reference v tomto dokumentu.
    • Microsoft.AspNetCore.Razor.Design je odstraněn ze seznamu následujících balíčků, které se již nevyrábějí.

Pokud chcete zobrazit úplný seznam balíčků, které se už nevytváří, vyberte možnost rozbalit seznam.

Kliknutím rozbalíte seznam balíčků, které se už nevyrábějí.
  • Microsoft.AspNetCore
  • Microsoft.AspNetCore.All
  • Microsoft.AspNetCore.App
  • Microsoft.AspNetCore.Antiforgery
  • Microsoft.AspNetCore.Authentication
  • Microsoft.AspNetCore.Authentication.Abstractions
  • Microsoft.AspNetCore.Authentication.Cookies
  • Microsoft.AspNetCore.Authentication.Core
  • Microsoft.AspNetCore.Authentication.OAuth
  • Microsoft.AspNetCore.Authorization.Policy
  • Microsoft.AspNetCore.CookiePolicy
  • Microsoft.AspNetCore.Cors
  • Microsoft.AspNetCore.Diagnostics
  • Microsoft.AspNetCore.Diagnostics.HealthChecks
  • Microsoft.AspNetCore.HostFiltering
  • Microsoft.AspNetCore.Hosting
  • Microsoft.AspNetCore.Hosting.Abstractions
  • Microsoft.AspNetCore.Hosting.Server.Abstractions
  • Microsoft.AspNetCore.Http
  • Microsoft.AspNetCore.Http.Abstractions
  • Microsoft.AspNetCore.Http.Connections
  • Microsoft.AspNetCore.Http.Extensions
  • Microsoft.AspNetCore.HttpOverrides
  • Microsoft.AspNetCore.HttpsPolicy
  • Microsoft.AspNetCore.Identity
  • Microsoft.AspNetCore.Localization
  • Microsoft.AspNetCore.Localization.Routing
  • Microsoft.AspNetCore.Mvc
  • Microsoft.AspNetCore.Mvc.Abstractions
  • Microsoft.AspNetCore.Mvc.Analyzers
  • Microsoft.AspNetCore.Mvc.ApiExplorer
  • Microsoft.AspNetCore.Mvc.Api.Analyzers
  • Microsoft.AspNetCore.Mvc.Core
  • Microsoft.AspNetCore.Mvc.Cors
  • Microsoft.AspNetCore.Mvc.DataAnnotations
  • Microsoft.AspNetCore.Mvc.Formatters.Json
  • Microsoft.AspNetCore.Mvc.Formatters.Xml
  • Microsoft.AspNetCore.Mvc.Localization
  • Microsoft.AspNetCore.Mvc.Razor
  • Microsoft.AspNetCore.Mvc.Razor. ViewCompilation
  • Microsoft.AspNetCore.Mvc.RazorPages
  • Microsoft.AspNetCore.Mvc.TagHelpers
  • Microsoft.AspNetCore.Mvc.ViewFeatures
  • Microsoft.AspNetCore.Razor
  • Microsoft.AspNetCore.Razor. Runtime
  • Microsoft.AspNetCore.Razor.Návrh
  • Microsoft.AspNetCore.ResponseCaching
  • Microsoft.AspNetCore.ResponseCaching.Abstractions
  • Microsoft.AspNetCore.ResponseCompression
  • Microsoft.AspNetCore.Rewrite
  • Microsoft.AspNetCore.Routing
  • Microsoft.AspNetCore.Routing.Abstractions
  • Microsoft.AspNetCore.Server.HttpSys
  • Microsoft.AspNetCore.Server.IIS
  • Microsoft.AspNetCore.Server.IISIntegration
  • Microsoft.AspNetCore.Server.Kestrel
  • Microsoft.AspNetCore.Server.Kestrel. Jádro
  • Microsoft.AspNetCore.Server.Kestrel. Https
  • Microsoft.AspNetCore.Server.Kestrel. Transport.Abstractions
  • Microsoft.AspNetCore.Server.Kestrel. Transport.Sockets
  • Microsoft.AspNetCore.Session
  • Microsoft.AspNetCore.SignalR
  • Microsoft.AspNetCore.SignalR. Jádro
  • Microsoft.AspNetCore.StaticFiles
  • Microsoft.AspNetCore.WebSockets
  • Microsoft.AspNetCore.WebUtilities
  • Microsoft.Net.Http.Headers

Přezkum významných změn

Kontrola zásadních změn

Referenční rámec

Funkce ASP.NET Core, které byly dostupné prostřednictvím některého z výše uvedených balíčků, jsou k dispozici jako součást Microsoft.AspNetCore.App sdílené architektury. Sdílená architektura je sada sestavení (.dll souborů), která jsou nainstalovaná na počítači a obsahuje komponentu modulu runtime a sadu cílení. Další informace naleznete v části Sdílená architektura.

  • Projekty, které cílí na Microsoft.NET.Sdk.Web sadu SDK, implicitně odkazují na architekturu Microsoft.AspNetCore.App .

    Pro tyto projekty nejsou vyžadovány žádné další odkazy:

    <Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <TargetFramework>netcoreapp3.0</TargetFramework>
  </PropertyGroup>
    ...
</Project>

  • Projekty, které cílí na Microsoft.NET.Sdk nebo Microsoft.NET.Sdk.Razor sadu SDK, by měly explicitně přidat FrameworkReference do Microsoft.AspNetCore.App:

    <Project Sdk="Microsoft.NET.Sdk.Razor">
  <PropertyGroup>
    <TargetFramework>netcoreapp3.0</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
  </ItemGroup>
    ...
</Project>

Sestavení závislá na rozhraní pomocí Dockeru

Sestavení konzolových aplikací závislých na architektuře, které používají balíček, který závisí na sdílené architektuře ASP.NET Core, může obsahovat následující chybu za běhu:

It was not possible to find any compatible framework version
The specified framework 'Microsoft.AspNetCore.App', version '3.0.0' was not found.
  - No frameworks were found.

Microsoft.AspNetCore.App je sdílený framework obsahující modul runtime ASP.NET Core a nachází se pouze v Docker image dotnet/core/aspnet. Sada SDK 3.0 zmenšuje velikost sestavení závislých na rozhraní využívajících ASP.NET Core tím, že nezahrnuje duplicitní kopie knihoven, které jsou dostupné ve sdíleném rozhraní. To je potenciální úspora až 18 MB, ale vyžaduje, aby byl přítomen nebo nainstalován runtime ASP.NET Core pro spuštění aplikace.

Pokud chcete zjistit, jestli má aplikace závislost (přímou nebo nepřímou) na sdílené rozhraní ASP.NET Core, prozkoumejte runtimeconfig.json soubor vygenerovaný během sestavení nebo publikování aplikace. Následující soubor JSON ukazuje závislost na sdílené rozhraní ASP.NET Core:

{
  "runtimeOptions": {
    "tfm": "netcoreapp3.0",
    "framework": {
      "name": "Microsoft.AspNetCore.App",
      "version": "3.0.0"
    },
    "configProperties": {
      "System.GC.Server": true
    }
  }
}

Pokud vaše aplikace používá Docker, použijte základní image, která zahrnuje ASP.NET Core 3.0. Například docker pull mcr.microsoft.com/dotnet/core/aspnet:3.0.

Přidejte odkazy na balíčky pro odebraná sestavení

ASP.NET Core 3.0 odebere některá sestavení, která byla dříve součástí referencí na balíček Microsoft.AspNetCore.App. Pokud chcete vizualizovat, která sestavení byla odebrána, porovnejte dvě složky se sdílenou architekturou. Například porovnání verzí 2.2.7 a 3.0.0:

Porovnání sestavení sdílených architektur

Pokud chcete pokračovat v používání funkcí poskytovaných odebranými sestaveními, odkazujte na verze 3.0 odpovídajících balíčků:

Změny při spuštění

Následující obrázek ukazuje odstraněné a změněné řádky ve webové aplikaci ASP.NET Core 2.2 Razor Pages:

odstraněné a změněné řádky ve webové aplikaci ASP.NET Core 2.2 Razor

Na předchozím obrázku se odstraněný kód zobrazuje červeně. Odstraněný kód nezobrazuje cookie kód možností, který byl odstraněn před porovnáním souborů.

Následující obrázek ukazuje přidané a změněné řádky ve webové aplikaci ASP.NET Core 3.0 Razor Pages:

přidané a změněné řádky ve webové aplikaci ASP.NET Core 3.0 Razor

Na předchozím obrázku se přidaný kód zobrazuje zeleně. Informace o následujících změnách:

Podpora analyzátoru

Projekty, které cílí Microsoft.NET.Sdk.Web, implicitně referencují analyzátory, jež byly dříve dodávány jako součást balíčku Microsoft.AspNetCore.Mvc.Analyzers. K jejich povolení nejsou potřeba žádné další reference.

Pokud vaše aplikace používá dříve dodané analyzátory rozhraní API pomocí balíčku Microsoft.AspNetCore.Mvc.Api.Analyzers, upravte soubor projektu tak, aby odkazoval na analyzátory dodané jako součást webové sady SDK .NET Core:

<Project Sdk="Microsoft.NET.Sdk.Web">
    <PropertyGroup>
        <TargetFramework>netcoreapp3.0</TargetFramework>
        <IncludeOpenAPIAnalyzers>true</IncludeOpenAPIAnalyzers>
    </PropertyGroup>

    ...
</Project>

Razor knihovna tříd

Razor Projekty knihovny tříd, které poskytují součásti uživatelského rozhraní pro MVC, musí nastavit AddRazorSupportForMvc vlastnost v souboru projektu:

<PropertyGroup>
  <AddRazorSupportForMvc>true</AddRazorSupportForMvc>
</PropertyGroup>

Model vnitroprocesového hostování

Projekty ve výchozím nastavení využívají model hostování v procesu ve verzi ASP.NET Core 3.0 nebo novější. Volitelně můžete odebrat vlastnost <AspNetCoreHostingModel> v souboru projektu, pokud je její hodnota InProcess.

Kestrel

Konfigurace

Migrace Kestrel konfigurace do konstruktéru webového hostitele poskytovaného ConfigureWebHostDefaults(Program.cs):

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.ConfigureKestrel(serverOptions =>
            {
                // Set properties and call methods on options
            })
            .UseStartup<Startup>();
        });

Pokud aplikace vytvoří hostitele ručně pomocí ConfigureWebHost místo ConfigureWebHostDefaults, zavolejte UseKestrel na tvůrce webových hostitelů:

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

    host.Run();
}

Middleware připojení nahrazuje adaptéry připojení.

Adaptéry připojení (Microsoft.AspNetCore.Server.Kestrel.Core.Adapter.Internal.IConnectionAdapter) byly odebrány z Kestrelaplikace . Adaptéry připojení nahraďte middlewarem připojení. Middleware připojení je podobné middlewaru HTTP v rámci ASP.NET Core, ale je určeno pro připojení na nižší úrovni. Protokolování HTTPS a připojení:

  • Byly přesunuty z adaptérů připojení do middleware pro připojení.
  • Tyto metody rozšíření fungují stejně jako v předchozích verzích ASP.NET Core.

Další informace najdete v příkladu TlsFilterConnectionHandler v části ListenOptions.Protocols článkuKestrel.

Dopravní abstrakce přesunuté a zpřístupněné veřejnosti

Transportní Kestrel vrstva byla zpřístupněna jako veřejné rozhraní v Connections.Abstractions. V rámci těchto aktualizací:

  • Microsoft.AspNetCore.Server.Kestrel.Transport.Abstractions a přidružené typy byly odebrány.
  • NoDelay byla přesunuta z ListenOptions do možností dopravy.
  • Microsoft.AspNetCore.Server.Kestrel.Transport.Abstractions.Internal.SchedulingMode byla odebrána z KestrelServerOptions.

Další informace najdete v následujících zdrojích informací na GitHubu:

Kestrel Hlavičky žádosti o přívěs

Pro aplikace, které cílí na starší verze ASP.NET Core:

  • Kestrel přidá příznakové hlavičky HTTP/1.1 typu chunked do kolekce hlaviček požadavků.
  • Trailery jsou k dispozici po dokončení čtení těla požadavku.

To způsobuje určité obavy ohledně nejednoznačnosti mezi hlavičkami a přívěsy, takže přívěsy byly přesunuty do nové kolekce (RequestTrailerExtensions) ve verzi 3.0.

Požadavky HTTP/2 jsou:

  • V ASP.NET Core 2.2 není k dispozici.
  • K dispozici ve verzi 3.0 jako RequestTrailerExtensions.

Pro přístup k těmto přívěsům jsou k dispozici nové metody rozšíření požadavků. Stejně jako u HTTP/1.1, trailer hlavičky jsou dostupné po úplném přečtení těla požadavku.

Pro verzi 3.0 jsou k dispozici následující RequestTrailerExtensions metody:

  • GetDeclaredTrailers: Získá hlavičku požadavku Trailer , která uvádí, které přívěsy mají očekávat po těle.
  • SupportsTrailers: Určuje, zda žádost podporuje příjem hlaviček přívěsu.
  • CheckTrailersAvailable: Zkontroluje, jestli žádost podporuje přívěsy a zda jsou k dispozici ke čtení. Tato kontrola nepředpokládá, že existují přívěsy ke čtení. Tato metoda nemusí číst žádné přívěsy, i když true je vrácena touto metodou.
  • GetTrailer: Získá požadovanou koncovou hlavičku z odpovědi. Nejprve zkontrolujte SupportsTrailers, než zavoláte GetTrailer, jinak může dojít k NotSupportedException, pokud požadavek nepodporuje koncové hlavičky.

Další informace naleznete v tématu Put request trailers in a separate collection (dotnet/AspNetCore #10410).

AllowSynchronousIO zakázáno

AllowSynchronousIO povolí nebo zakáže synchronní rozhraní API vstupně-výstupních operací, například HttpRequest.Body.Read, HttpResponse.Body.Writea Stream.Flush. Tato rozhraní API jsou zdrojem hladovění vláken, což vede k chybovému ukončení aplikace. Ve verzi 3.0 AllowSynchronousIO je ve výchozím nastavení zakázaná. Další informace najdete v části Synchronní vstupně-výstupní operace v Kestrel článku.

Pokud je potřeba synchronní vstupně-výstupní operace, můžete ji povolit konfigurací volby AllowSynchronousIO na používaném serveru (například při volání ConfigureKestrel, pokud používáte Kestrel). Všimněte si, že všechny servery (KestrelHttpSys, TestServer atd.) mají vlastní AllowSynchronousIO možnost, která nebude mít vliv na ostatní servery. Synchronní vstupně-výstupní operace je možné povolit pro všechny servery na základě požadavku pomocí této IHttpBodyControlFeature.AllowSynchronousIO možnosti:

var syncIOFeature = HttpContext.Features.Get<IHttpBodyControlFeature>();

if (syncIOFeature != null)
{
    syncIOFeature.AllowSynchronousIO = true;
}

Pokud máte potíže s TextWriter implementacemi nebo jinými datovými proudy, které volají synchronní rozhraní API v Dispose, zavolejte místo toho nové DisposeAsync rozhraní API.

Další informace naleznete v tématu [Oznámení] AllowSynchronousIO zakázáno na všech serverech (dotnet/AspNetCore #7644).

Ukládání výstupního formátovače do vyrovnávací paměti

Newtonsoft.JsonXmlSerializer a DataContractSerializer formátovací moduly založené na výstupech podporují pouze synchronní serializaci. Aby tyto formátovací moduly fungovaly s omezeními AllowSynchronousIO serveru, MVC před zápisem na disk zasadí výstup těchto formátování do vyrovnávací paměti. V důsledku ukládání do vyrovnávací paměti bude MVC obsahovat hlavičku Content-Length při odpovídání pomocí těchto formátovacích metod.

System.Text.Json podporuje asynchronní serializaci a v důsledku toho System.Text.Json formátovač neuchovává data ve vyrovnávací paměti. Zvažte použití tohoto formátovače pro lepší výkon.

Pokud chcete zakázat ukládání do vyrovnávací paměti, můžou aplikace nakonfigurovat SuppressOutputFormatterBuffering při spuštění:

services.AddControllers(options => options.SuppressOutputFormatterBuffering = true)

Upozorňujeme, že to může způsobit, že aplikace vyvolá výjimku za běhu, pokud AllowSynchronousIO není také nakonfigurovaná.

Microsoft.AspNetCore.Server.Kestrel. Sestavení HTTPS bylo odstraněno

V ASP.NET Core 2.1 obsah Microsoft.AspNetCore.Server.Kestrel. Https.dll byly přesunuty na Microsoft.AspNetCore.Server.Kestrel. Core.dll. Jednalo se o nepřerušující aktualizaci pomocí atributů TypeForwardedTo. Pro verzi 3.0 bylo odebráno prázdné sestavení Microsoft.AspNetCore.Server.Kestrel.Https.dll a balíček NuGet.

Knihovny odkazující na Microsoft.AspNetCore.Server.HttpsKestrel by měly aktualizovat závislosti ASP.NET Core na verzi 2.1 nebo novější.

Aplikace a knihovny cílené na ASP.NET Core 2.1 nebo novější by měly odebrat všechny přímé odkazy na Microsoft.AspNetCore.Server.Kestrel. Balíček HTTPS .

Podpora Newtonsoft.Json (Json.NET)

V rámci práce na vylepšení sdílené architektury ASP.NET Core byl Newtonsoft.Json (Json.NET) odstraněn z této architektury.

Výchozí serializátor JSON pro ASP.NET Core je teď System.Text.Jsonnový v .NET Core 3.0. Zvažte použití System.Text.Json , pokud je to možné. Je vysoce výkonný a nevyžaduje závislost na další knihovně. Vzhledem k tomu, že System.Text.Json je nová, může v současné době chybět funkce, které vaše aplikace potřebuje. Další informace najdete v tématu Jak migrovat z Newtonsoft.Json na System.Text.Json.

Použití Newtonsoft.Json v projektu ASP.NET Core 3.0 SignalR

  • Nainstalujte balíček NuGet Microsoft.AspNetCore.Protocols.NewtonsoftJson.

  • V klientovi zřetězte AddNewtonsoftJsonProtocol volání metody do HubConnectionBuilder instance:

    new HubConnectionBuilder()
    .WithUrl("/chathub")
    .AddNewtonsoftJsonProtocol(...)
    .Build();

  • Na serveru spojte volání metody AddNewtonsoftJsonProtocol s voláním metody AddSignalR v Startup.ConfigureServices:

    services.AddSignalR()
    .AddNewtonsoftJsonProtocol(...);

Použití Newtonsoft.Json v projektu ASP.NET Core 3.0 MVC

  • Nainstalujte balíček Microsoft.AspNetCore.Mvc.NewtonsoftJson.

  • Aktualizujte Startup.ConfigureServices na zavolání AddNewtonsoftJson.

    services.AddMvc()
    .AddNewtonsoftJson();

    AddNewtonsoftJson je kompatibilní s novými metodami registrace služby MVC:

    • AddRazorPages
    • AddControllersWithViews
    • AddControllers
    services.AddControllers()
    .AddNewtonsoftJson();

    Newtonsoft.Json nastavení lze nastavit při volání na AddNewtonsoftJson:

    services.AddMvc()
    .AddNewtonsoftJson(options =>
           options.SerializerSettings.ContractResolver =
              new CamelCasePropertyNamesContractResolver());

    Poznámka: Pokud tato metoda AddNewtonsoftJson není dostupná, ujistěte se, že jste nainstalovali balíček Microsoft.AspNetCore.Mvc.NewtonsoftJson. Běžnou chybou je instalace balíčku Newtonsoft.Json místo Microsoft.AspNetCore.Mvc.NewtonsoftJson balíčku.

Další informace najdete v tématu Přidání podpory formátu JSON založeného na Newtonsoft.Json.

Registrace služby MVC

ASP.NET Core 3.0 přidává nové možnosti registrace scénářů MVC uvnitř Startup.ConfigureServices.

K dispozici jsou tři nové metody rozšíření nejvyšší úrovně související se scénáři IServiceCollection MVC. Šablony používají tyto nové metody místo AddMvc. AddMvc I nadále se ale chová stejně jako v předchozích verzích.

Následující příklad přidá podporu pro kontrolery a funkce související s rozhraním API, ale ne zobrazení nebo stránky. Šablona rozhraní API používá tento kód:

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers();
}

Následující příklad přidá podporu pro kontrolery, funkce související s rozhraním API a zobrazení, ale ne stránky. Šablona webové aplikace (MVC) používá tento kód:

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllersWithViews();
}

Následující příklad přidá podporu pro Razor Pages a minimální podporu kontroleru. Šablona webové aplikace používá tento kód:

public void ConfigureServices(IServiceCollection services)
{
    services.AddRazorPages();
}

Nové metody lze také kombinovat. Následující příklad je ekvivalentní volání AddMvc v ASP.NET Core 2.2:

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllersWithViews();
    services.AddRazorPages();
}

Směrování spouštěcího kódu

Pokud aplikace volá UseMvc nebo UseSignalR, migrujte aplikaci, pokud je to možné, na Endpoint Routing. Abychom vylepšili kompatibilitu směrování koncových bodů s předchozími verzemi MVC, vrátili jsme některé změny v generování adres URL zavedených v ASP.NET Core 2.2. Pokud došlo k problémům se směrováním koncových bodů ve verzi 2.2, počítejte s vylepšeními v ASP.NET Core 3.0 s následujícími výjimkami:

  • Pokud aplikace implementuje IRouter nebo dědí z Route, použijte dynamicRouteValuesTransformer jako náhradu.
  • Pokud aplikace k analýze adres URL přistupuje přímo v rámci RouteData.Routers MVC, můžete ji nahradit použitím LinkParser.ParsePathByEndpointName.
    • Definujte trasu s názvem trasy.
    • Použijte LinkParser.ParsePathByEndpointName a předejte název požadované trasy.

Směrování koncových bodů podporuje stejnou syntaxi vzoru tras a funkce vytváření vzorů tras jako IRouter. Směrování koncových bodů podporuje IRouteConstraint. Směrování koncového bodu podporuje [Route][HttpGet]a další atributy směrování MVC.

U většiny aplikací vyžaduje jenom Startup změny.

Přesměrovat Startup.Configure

Obecné rady:

  • Přidat UseRouting.

  • Pokud aplikace volá UseStaticFiles, umístěte jej před UseStaticFilesUseRouting.

  • Pokud aplikace používá funkce ověřování/autorizace, jako je AuthorizePage nebo [Authorize], umístěte volání na UseAuthentication a UseAuthorization: za, UseRouting a UseCors, ale před UseEndpoints

    public void Configure(IApplicationBuilder app)
{
  ...

  app.UseStaticFiles();

  app.UseRouting();
  app.UseCors();

  app.UseAuthentication();
  app.UseAuthorization();

  app.UseEndpoints(endpoints => {
     endpoints.MapControllers();
  });

  • Nahradit UseMvc nebo UseSignalR za UseEndpoints.

  • V případě, že aplikace používá scénáře CORS, například [EnableCors], umístěte volání UseCors před jakýkoli jiný middleware, který používá CORS (například umístěte UseCors před UseAuthentication, UseAuthorization, a UseEndpoints).

  • Nahraďte IHostingEnvironment za IWebHostEnvironment a přidejte příkaz using pro obor názvů Microsoft.AspNetCore.Hosting.

  • Nahradit IApplicationLifetime s IHostApplicationLifetime (obor názvů Microsoft.Extensions.Hosting).

  • Nahradit EnvironmentName s Environments (obor názvů Microsoft.Extensions.Hosting).

Následující kód je příkladem Startup.Configure typické aplikace ASP.NET Core 2.2:

public void Configure(IApplicationBuilder app)
{
    ...

    app.UseStaticFiles();

    app.UseAuthentication();

    app.UseSignalR(hubs =>
    {
        hubs.MapHub<ChatHub>("/chat");
    });

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

Po aktualizaci předchozího Startup.Configure kódu:

public void Configure(IApplicationBuilder app)
{
    ...

    app.UseStaticFiles();

    app.UseRouting();

    app.UseCors();

    app.UseAuthentication();
    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapHub<ChatHub>("/chat");
        endpoints.MapControllerRoute("default", "{controller=Home}/{action=Index}/{id?}");
    });
}

Varování

U většiny aplikací musí být volání na UseAuthentication, UseAuthorization a UseCors mezi voláními UseRouting a UseEndpoints, aby byla efektivní.

Kontroly stavu

Kontroly stavu používají směrování koncových bodů s generickým hostitelem. V Startup.Configure zavolejte MapHealthChecks na konstruktor koncových bodů s URL adresou koncového bodu nebo relativní cestou:

app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health");
});

Koncové body kontroly stavu mohou:

  • Zadejte jednoho nebo více povolených hostitelů nebo portů.
  • Vyžadovat autorizaci.
  • Vyžadovat CORS.

Další informace najdete v tématu Kontroly stavu v ASP.NET Core.

Pokyny k middlewaru zabezpečení

Podpora autorizace a CORS je sjednocená kolem přístupu middlewaru. To umožňuje použití stejného middlewaru a funkcí v těchto scénářích. V této verzi je k dispozici aktualizovaný middleware autorizace a CORS middleware je vylepšený tak, aby porozuměl atributům používaným kontrolery MVC.

CORS (Sdílení zdrojů mezi různými doménami)

Dříve mohlo být obtížné nakonfigurovat CORS. Middleware byl k dispozici pro použití v některých případech, ale filtry MVC byly určeny k použití bez middlewaru v jiných případech použití. S ASP.NET Core 3.0 doporučujeme, aby všechny aplikace, které vyžadují CORS, používaly middleware CORS společně se směrováním koncových bodů. UseCors lze zadat s výchozí zásadou, a atributy [EnableCors] a [DisableCors] lze použít k přepsání výchozí zásady tam, kde je to potřeba.

V následujícím příkladu:

  • CORS je povoleno pro všechny koncové body se zásadou pojmenovanou default.
  • Třída MyController zakáže CORS s atributem [DisableCors] .
public void Configure(IApplicationBuilder app)
{
    ...

    app.UseRouting();

    app.UseCors("default");

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapDefaultControllerRoute();
    });
}

[DisableCors]
public class MyController : ControllerBase
{
    ...
}

Autorizace

V dřívějších verzích ASP.NET Core byla prostřednictvím atributu [Authorize] poskytována podpora autorizace. Middleware pro autorizaci nebyl k dispozici. V ASP.NET Core 3.0 se vyžaduje middleware autorizace. Doporučujeme umístit middleware ASP.NET Core Authorization (UseAuthorization) ihned po UseAuthentication. Middleware pro autorizaci je také možné nakonfigurovat s výchozí zásadou, kterou je možné přepsat.

V ASP.NET Core 3.0 nebo novější se UseAuthorization volá v Startup.Configure, a následující HomeController vyžaduje přihlášeného uživatele:

public void Configure(IApplicationBuilder app)
{
    ...

    app.UseRouting();

    app.UseAuthentication();
    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapDefaultControllerRoute();
    });
}

public class HomeController : Controller
{
    [Authorize]
    public IActionResult BuyWidgets()
    {
        ...
    }
}

Při použití směrování koncového bodu nedoporučujeme konfiguraci AuthorizeFilter, ale místo toho se spoléhat na autorizační middleware. Pokud aplikace používá AuthorizeFilter jako globální filtr v MVC, doporučujeme refaktorovat kód a poskytnout zásadu při volání AddAuthorization.

DefaultPolicy je zatím nakonfigurovaná tak, aby vyžadovala ověřování, takže není nutná žádná další konfigurace. V následujícím příkladu jsou koncové body MVC označené jako RequireAuthorization, takže všechny požadavky musí být autorizovány na základě DefaultPolicy. Přístup HomeController však umožňuje bez přihlášení uživatele k aplikaci z důvodu [AllowAnonymous]:

public void Configure(IApplicationBuilder app)
{
    ...

    app.UseRouting();

    app.UseAuthentication();
    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapDefaultControllerRoute().RequireAuthorization();
    });
}

[AllowAnonymous]
public class HomeController : Controller
{
    ...
}

Autorizace pro konkrétní koncové body

Autorizaci je také možné nakonfigurovat pro konkrétní třídy koncových bodů. Následující kód je příkladem převodu aplikace MVC, která nakonfigurovala globální AuthorizeFilter aplikaci na aplikaci s konkrétní zásadou vyžadující autorizaci:

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

    static readonly string _RequireAuthenticatedUserPolicy = 
                            "RequireAuthenticatedUserPolicy";
    public IConfiguration Configuration { get; }

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddDbContext<ApplicationDbContext>(options =>
            options.UseSqlServer(
                Configuration.GetConnectionString("DefaultConnection")));
        services.AddDefaultIdentity<IdentityUser>(
                 options => options.SignIn.RequireConfirmedAccount = true)
            .AddEntityFrameworkStores<ApplicationDbContext>();

        // Pre 3.0:
        // services.AddMvc(options => options.Filters.Add(new AuthorizeFilter(...));

        services.AddControllersWithViews();
        services.AddRazorPages();
        services.AddAuthorization(o => o.AddPolicy(_RequireAuthenticatedUserPolicy,
                        builder => builder.RequireAuthenticatedUser()));

    }

    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
            app.UseDatabaseErrorPage();
        }
        else
        {
            app.UseExceptionHandler("/Home/Error");
            app.UseHsts();
        }
        app.UseHttpsRedirection();
        app.UseStaticFiles();

        app.UseRouting();

        app.UseAuthentication();
        app.UseAuthorization();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapDefaultControllerRoute()
                .RequireAuthorization(_RequireAuthenticatedUserPolicy);
            endpoints.MapRazorPages();
        });
    }
}

Zásady je také možné přizpůsobit. Je DefaultPolicy nakonfigurovaná tak, aby vyžadovala ověřování:

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

    public IConfiguration Configuration { get; }

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddDbContext<ApplicationDbContext>(options =>
            options.UseSqlServer(
                Configuration.GetConnectionString("DefaultConnection")));
        services.AddDefaultIdentity<IdentityUser>(
                 options => options.SignIn.RequireConfirmedAccount = true)
            .AddEntityFrameworkStores<ApplicationDbContext>();

        services.AddControllersWithViews();
        services.AddRazorPages();
        services.AddAuthorization(options =>
        {
            options.DefaultPolicy = new AuthorizationPolicyBuilder()
              .RequireAuthenticatedUser()
              .Build();
        });

    }

    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
            app.UseDatabaseErrorPage();
        }
        else
        {
            app.UseExceptionHandler("/Home/Error");
            app.UseHsts();
        }
        app.UseHttpsRedirection();
        app.UseStaticFiles();

        app.UseRouting();

        app.UseAuthentication();
        app.UseAuthorization();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapDefaultControllerRoute().RequireAuthorization();
            endpoints.MapRazorPages();
        });
    }
}

[AllowAnonymous]
public class HomeController : Controller
{

Alternativně lze všechny koncové body nakonfigurovat tak, aby vyžadovaly autorizaci, a to bez použití [Authorize] nebo RequireAuthorization, pomocí konfigurace FallbackPolicy. FallbackPolicy se liší od DefaultPolicy. Spouští se DefaultPolicy pomocí [Authorize] nebo RequireAuthorization, zatímco FallbackPolicy je spuštěn, když není nastavena žádná jiná politika. FallbackPolicy je původně nakonfigurovaný tak, aby povoloval požadavky bez autorizace.

Následující příklad je stejný jako předchozí DefaultPolicy příklad, ale používá FallbackPolicy k tomu, aby vždy vyžadoval ověřování ve všech koncových bodech, s výjimkou případů, kdy [AllowAnonymous] je zadán:

public void ConfigureServices(IServiceCollection services)
{
    ...

    services.AddAuthorization(options =>
    {
        options.FallbackPolicy = new AuthorizationPolicyBuilder()
          .RequireAuthenticatedUser()
          .Build();
    });
}

public void Configure(IApplicationBuilder app)
{
    ...

    app.UseRouting();

    app.UseAuthentication();
    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapDefaultControllerRoute();
    });
}

[AllowAnonymous]
public class HomeController : Controller
{
    ...
}

Autorizace pomocí middlewaru funguje bez architektury, která má konkrétní znalosti autorizace. Například kontroly zdraví nemají žádné konkrétní znalosti o autorizaci, ale na kontroly zdraví může být pomocí middlewaru aplikována konfigurovatelná zásada autorizace.

Každý koncový bod navíc může přizpůsobit své požadavky na autorizaci. V následujícím příkladu UseAuthorization zpracovává autorizaci pomocí DefaultPolicy, ale /healthz kontrolní bod stavu vyžaduje uživatele admin.

public void Configure(IApplicationBuilder app)
{
    ...

    app.UseRouting();

    app.UseAuthentication();
    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        endpoints
            .MapHealthChecks("/healthz")
            .RequireAuthorization(new AuthorizeAttribute(){ Roles = "admin", });
    });
}

Ochrana se implementuje v některých scénářích. Middleware koncových bodů vyvolá výjimku, pokud se kvůli chybějícímu middlewaru přeskočí zásady autorizace nebo CORS. Podpora analyzátoru, která poskytuje další zpětnou vazbu o chybné konfiguraci, probíhá.

Vlastní obslužné rutiny autorizace

Pokud aplikace používá vlastní autorizační obslužné rutiny, směrování koncového bodu předá obslužným rutinám jiný typ prostředku než MVC. Obslužné rutiny, které očekávají, že kontextový prostředek obslužné rutiny autorizace bude typu AuthorizationFilterContext (typ prostředku poskytovaný filtry MVC), bude potřeba aktualizovat tak, aby zpracovávaly prostředky typu RouteEndpoint (typ prostředku udělený obslužným rutinám autorizace směrováním koncového bodu).

MVC stále používá AuthorizationFilterContext prostředky, takže pokud aplikace používá autorizační filtry MVC spolu s autorizací směrování koncových bodů, může být nutné zpracovat oba typy prostředků.

SignalR

Mapování SignalR rozbočovačů teď probíhá uvnitř UseEndpoints.

Namapujte každé centrum pomocí MapHub. Stejně jako v předchozích verzích je každé centrum explicitně uvedené.

V následujícím příkladu se přidá podpora pro hub ChatHubSignalR:

public void Configure(IApplicationBuilder app)
{
    ...

    app.UseRouting();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapHub<ChatHub>();
    });
}

Existuje nová možnost pro řízení limitů velikosti zpráv od klientů. Například v Startup.ConfigureServices:

services.AddSignalR(hubOptions =>
{
    hubOptions.MaximumReceiveMessageSize = 32768;
});

Ve verzi ASP.NET Core 2.2 jste mohli nastavit TransportMaxBufferSize, což by efektivně kontrolovalo maximální velikost zprávy. V ASP.NET Core 3.0 tato možnost nyní řídí maximální velikost, než se objeví zpětný tlak.

SignalR sestavení ve sdíleném frameworku

ASP.NET sestavení na straně serveru se SignalR teď instalují se sadou .NET Core SDK. Další informace naleznete v tématu Odebrání zastaralých odkazů na balíčky v tomto dokumentu.

Kontrolery MVC

Mapování kontrolerů probíhá uvnitř UseEndpoints.

Přidejte MapControllers , pokud aplikace používá směrování atributů. Vzhledem k tomu, že směrování zahrnuje podporu mnoha frameworků v ASP.NET Core 3.0 nebo novější, je přidání kontrolerů směrovaných pomocí atributů volitelná možnost.

Nahraďte následující položky:

  • MapRoute s MapControllerRoute
  • MapAreaRoute s MapAreaControllerRoute

Vzhledem k tomu, že směrování teď zahrnuje podporu více než jen MVC, terminologie se změnila, aby tyto metody jasně uvedly, co dělají. Běžné trasy, jako MapControllerRoute/MapAreaControllerRoute/MapDefaultControllerRoute jsou použité v pořadí, v jakém jsou přidány. Nejprve umístěte konkrétnější trasy (například trasy pro oblast).

V následujícím příkladu:

  • MapControllers přidává podporu pro kontrolery směrované pomocí atributů.
  • MapAreaControllerRoute přidá konvenční trasu pro kontrolery v oblasti.
  • MapControllerRoute přidá konvenční trasu pro kontrolery.
public void Configure(IApplicationBuilder app)
{
    ...

    app.UseRouting();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
        endpoints.MapAreaControllerRoute(
            "admin",
            "admin",
            "Admin/{controller=Home}/{action=Index}/{id?}");
        endpoints.MapControllerRoute(
            "default", "{controller=Home}/{action=Index}/{id?}");
    });
}

Odebrání asynchronní přípony z názvů akcí kontroleru

V ASP.NET Core 3.0 ASP.NET Core MVC odebere příponu Async z názvů akcí kontroleru. Toto nové výchozí nastavení má vliv na generování směrování i propojení. Příklad:

public class ProductsController : Controller
{
    public async Task<IActionResult> ListAsync()
    {
        var model = await _dbContext.Products.ToListAsync();
        return View(model);
    }
}

Před ASP.NET Core 3.0:

  • K předchozí akci lze přistupovat na trase Products/ListAsync.

  • Generování propojení vyžaduje zadání přípony Async . Příklad:

    <a asp-controller="Products" asp-action="ListAsync">List</a>

V ASP.NET Core 3.0:

  • K předchozí akci je možné přistoupit na trase Products/List.

  • Generování propojení nevyžaduje zadání přípony Async . Příklad:

    <a asp-controller="Products" asp-action="List">List</a>

Tato změna nemá vliv na názvy zadané pomocí atributu [ActionName] . Výchozí chování může být zakázáno s následujícím kódem v Startup.ConfigureServices:

services.AddMvc(options =>
    options.SuppressAsyncSuffixInActionNames = false);

V generování propojení (například pomocí Url.Link a podobných rozhraní API) existují určité rozdíly. Tady jsou některé z nich:

  • Ve výchozím nastavení se při použití směrování koncového bodu nemusí ve vygenerovaných identifikátorech URI zachovat velikost písmen parametrů trasy. Toto chování lze ovládat pomocí IOutboundParameterTransformer rozhraní.
  • Při generování identifikátoru URI pro neplatnou trasu (kontroler/akci nebo stránku, která neexistuje) vznikne prázdný řetězec v rámci směrování koncového bodu místo vytvoření neplatného identifikátoru URI.
  • Okolní hodnoty (parametry trasy z aktuálního kontextu) se při generování propojení se směrováním koncového bodu nepoužívají automaticky. Dříve se při generování odkazu na jinou akci (nebo stránku) odvozovaly nezadané hodnoty trasy z aktuálních tras okolních hodnot. Při použití směrování koncového bodu musí být během generování propojení explicitně zadány všechny parametry trasy.

Razor Stránky

Probíhá mapování Razor stránek uvnitř UseEndpoints.

Přidejte MapRazorPages, pokud aplikace používá Razor Stránky. Vzhledem k tomu, že směrování koncových bodů zahrnuje podporu pro mnoho rámců, přidávání Razor Stránek je nyní volitelné.

V následující Startup.Configure metodě MapRazorPages přidá podporu pro Razor Stránky:

public void Configure(IApplicationBuilder app)
{
    ...

    app.UseRouting();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapRazorPages();
    });
}

Použití MVC bez směrování koncového bodu

Použití MVC prostřednictvím UseMvc nebo UseMvcWithDefaultRoute v ASP.NET Core 3.0 vyžaduje explicitní souhlas uvnitř Startup.ConfigureServices. To je povinné, protože MVC musí vědět, jestli se může během inicializace spoléhat na autorizaci a middleware CORS. K dispozici je analyzátor, který varuje, pokud se aplikace pokusí použít nepodporovanou konfiguraci.

Pokud aplikace vyžaduje starší IRouter verzi podpory, zakažte EnableEndpointRouting použití některého z následujících přístupů v Startup.ConfigureServices:

services.AddMvc(options => options.EnableEndpointRouting = false);

services.AddControllers(options => options.EnableEndpointRouting = false);

services.AddControllersWithViews(options => options.EnableEndpointRouting = false);

services.AddRazorPages().AddMvcOptions(options => options.EnableEndpointRouting = false);

Kontroly stavu

Kontroly stavu se dají použít jako router-ware se směrováním koncových bodů.

Ke kontrole stavu pomocí směrování koncových bodů přidejte MapHealthChecks. Metoda MapHealthChecks přijímá argumenty podobné UseHealthChecks. Výhodou použití MapHealthChecksUseHealthChecks oproti tomu je možnost použít autorizaci a mít větší podrobnou kontrolu nad odpovídajícími zásadami.

V následujícím příkladu se volá koncový bod kontroly zdraví MapHealthChecks na adrese /healthz:

public void Configure(IApplicationBuilder app)
{
    ...

    app.UseRouting();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapHealthChecks("/healthz", new HealthCheckOptions() { });
    });
}

HostBuilder nahrazuje WebHostBuilder.

Šablony ASP.NET Core 3.0 používají obecného hostitele. Předchozí verze používaly webového hostitele. Následující kód ukazuje vygenerovanou Program třídu šablony ASP.NET Core 3.0:

// requires using Microsoft.AspNetCore.Hosting;
// requires using Microsoft.Extensions.Hosting;

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

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

Následující kód ukazuje třídu vygenerovanou Program šablonou ASP.NET Core 2.2:

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

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

IWebHostBuilder zůstává ve verzi 3.0 a je typem webBuilder předchozího vzorku kódu. WebHostBuilderbude vyřazena v budoucí verzi a nahrazena .HostBuilder

Nejvýznamnější změnou z WebHostBuilder na HostBuilder je injekce závislostí (DI). Při použití HostBuilder můžete do konstruktoru Startup vložit pouze následující:

Omezení HostBuilder DI:

  • Povolte sestavení kontejneru DI pouze jednou.
  • Vyhne se problémům s životností výsledného objektu, jako je řešení více instancí singletonů.

Další informace najdete v tématu Zabránění injektáži služby po spuštění v ASP.NET Core 3.

AddAuthorization přesunuto do jiného sestavení

Metody ASP.NET Core 2.2 a starší verze AddAuthorization v Microsoft.AspNetCore.Authorization.dll:

  • Byly přejmenovány AddAuthorizationCore.
  • Byly přesunuty do Microsoft.AspNetCore.Authorization.Policy.dll.

Aplikace, které používají Microsoft.AspNetCore.Authorization.dll i Microsoft.AspNetCore.Authorization.Policy.dll , nemají vliv.

Aplikace, které nepoužívají Microsoft.AspNetCore.Authorization.Policy.dll by měly provádět jednu z následujících věcí:

  • Přidejte odkaz na Microsoft.AspNetCore.Authorization.Policy.dll. Tento přístup funguje pro většinu aplikací a je to vše, co je potřeba.
  • Přepnutí na používání AddAuthorizationCore

Další informace naleznete v tématu Zásadní změna v AddAuthorization(o =>) přetížení žije v jiném sestavení č. 386.

Identity Uživatelské rozhraní

Identity Aktualizace uživatelského rozhraní pro ASP.NET Core 3.0:

  • Přidejte odkaz na balíček Identity.
  • Aplikace, které nepoužívají Razor stránky, musí volat MapRazorPages. Viz Razor Stránky v tomto dokumentu.
  • Bootstrap 4 je výchozí architektura uživatelského rozhraní. IdentityUIFrameworkVersion Nastavte vlastnost projektu tak, aby se výchozí nastavení změnilo. Další informace najdete v tomto oznámení GitHubu.

SignalR

Klient JavaScriptu SignalR se změnil z @aspnet/signalr na @microsoft/signalr. Pokud chcete na tuto změnu reagovat, změňte odkazy v package.json souborech, require příkazech a příkazech ECMAScript import .

System.Text.Json je výchozí protokol.

System.Text.Json je teď výchozí protokol centra používaný klientem i serverem.

V Startup.ConfigureServices volejte AddJsonProtocol pro nastavení možností serializátoru.

Server:

services.AddSignalR(...)
        .AddJsonProtocol(options =>
        {
            options.PayloadSerializerOptions.WriteIndented = false;
        })

Klient:

new HubConnectionBuilder()
    .WithUrl("/chathub")
    .AddJsonProtocol(options =>
    {
        options.PayloadSerializerOptions.WriteIndented = false;
    })
    .Build();

Přepnutí na Newtonsoft.Json

Pokud používáte funkce Newtonsoft.Json, které nejsou v souboru System.Text.Json podporované, můžete přepnout zpět na Newtonsoft.Json. Viz SignalR ASP.NET Core 3.0 výše v tomto článku.

Distribuované mezipaměti Redis

Balíček Microsoft.Extensions.Caching.Redis není k dispozici pro aplikace ASP.NET Core 3.0 nebo novější. Nahraďte odkaz na balíček microsoft.Extensions.Caching.StackExchangeRedis. Další informace naleznete v tématu Distribuované ukládání do mezipaměti v ASP.NET Core.

Přihlášení k kompilaci modulu runtime

Před ASP.NET Core 3.0 byla implicitní funkcí architektury kompilace zobrazení za běhu. Kompilace modulu runtime doplňuje kompilaci zobrazení v čase sestavení. Umožňuje rozhraní kompilovat Razor zobrazení a stránky (.cshtml soubory) při úpravě souborů, aniž by bylo nutné znovu sestavit celou aplikaci. Tato funkce podporuje scénář rychlé úpravy v integrovaném vývojovém prostředí (IDE) a aktualizaci prohlížeče pro zobrazení změn.

V ASP.NET Core 3.0 je kompilace modulu runtime scénářem výslovného souhlasu. Kompilace v době sestavení je jediným mechanismem pro zobrazení kompilace, která je ve výchozím nastavení povolená. Modul runtime spoléhá na Visual Studio nebo dotnet-watch v editoru Visual Studio Code k opětovnému sestavení projektu při zjišťování změn souborů .cshtml . Ve Visual Studiu změny v souborech .cs, .cshtml nebo .razor v běžícím projektu (Ctrl+F5), ale ne při ladění (F5), spustí rekompilaci projektu.

Povolení kompilace modulu runtime v projektu ASP.NET Core 3.0:

  1. Nainstalujte balíček NuGet Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation.

  2. Aktualizovat Startup.ConfigureServices k provedení volání AddRazorRuntimeCompilation.

    Pro ASP.NET Core MVC použijte následující kód:

    services.AddControllersWithViews()
    .AddRazorRuntimeCompilation(...);

    Pro ASP.NET základní Razor stránky použijte následující kód:

    services.AddRazorPages()
    .AddRazorRuntimeCompilation(...);

Ukázka na obrázku https://github.com/aspnet/samples/tree/main/samples/aspnetcore/mvc/runtimecompilation ukazuje příklad podmíněného povolení kompilace modulu runtime ve vývojových prostředích.

Další informace o Razor kompilaci souborů naleznete Razor v souboru kompilace v ASP.NET Core.

Migrace knihoven pomocí vícenásobného cílení

Knihovny často potřebují podporovat více verzí ASP.NET Core. Většina knihoven zkompilovaných oproti předchozím verzím ASP.NET Core by měla bez problémů pokračovat v práci. Následující podmínky vyžadují, aby byla aplikace křížově zkompilována:

  • Knihovna spoléhá na funkci, která má binární zásadní změnu.
  • Knihovna chce využívat nové funkce v ASP.NET Core 3.0.

Příklad:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFrameworks>netcoreapp3.0;netstandard2.0</TargetFrameworks>
  </PropertyGroup>

  <ItemGroup Condition="'$(TargetFramework)' == 'netcoreapp3.0'">
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
  </ItemGroup>

  <ItemGroup Condition="'$(TargetFramework)' == 'netstandard2.0'">
    <PackageReference Include="Microsoft.AspNetCore" Version="2.1.0" />
  </ItemGroup>
</Project>

Použijte #ifdefs k povolení API specifických pro ASP.NET Core 3.0:

var webRootFileProvider =
#if NETCOREAPP3_0
    GetRequiredService<IWebHostEnvironment>().WebRootFileProvider;
#elif NETSTANDARD2_0
    GetRequiredService<IHostingEnvironment>().WebRootFileProvider;
#else
#error unknown target framework
#endif

Další informace o používání rozhraní ASP.NET Core API v knihovně tříd najdete v tématu Použití rozhraní API ASP.NET Core v knihovně tříd.

Různé změny

Ověřovací systém v .NET Core 3.0 nebo novější považuje parametry bez hodnoty null nebo vázané vlastnosti, jako by měly [Required] atribut. Další informace naleznete v tématu [Povinný] atribut.

Publikovat

Odstraňte složky bin a obj v adresáři projektu.

Testovací server

Pro aplikace, které používají TestServer přímo s Generic Host, vytvořte TestServer v rámci IWebHostBuilder v ConfigureWebHost:

[Fact]
public async Task GenericCreateAndStartHost_GetTestServer()
{
    using var host = await new HostBuilder()
        .ConfigureWebHost(webBuilder =>
        {
            webBuilder
                .UseTestServer()
                .Configure(app => { });
        })
    .StartAsync();

    var response = await host.GetTestServer().CreateClient().GetAsync("/");

    Assert.Equal(HttpStatusCode.NotFound, response.StatusCode);
}

Zásadní změny rozhraní API

Kontrola zásadních změn:

Směrování koncového bodu s catch-all parametrem

Varování

Parametr catch-all může nesprávně odpovídat trasám kvůli chybě při směrování. Aplikace ovlivněné touto chybou mají následující charakteristiky:

  • Například univerzální trasa {**slug}"
  • Trasa catch-all neodpovídá požadavkům, které by se měly shodovat.
  • Odebráním jiných tras začne fungovat zachytávání všech tras.

Podívejte se na chyby na GitHubu 18677 a 16579 pro příklady případů, které narazily na tuto chybu.

Oprava, kterou je třeba vyžádat, aby se tato chyba odstranila, je obsažena v sadě SDK .NET Core 3.1.301 nebo novější. Následující kód nastaví interní přepínač, který tuto chybu opraví:

public static void Main(string[] args)
{
   AppContext.SetSwitch("Microsoft.AspNetCore.Routing.UseCorrectCatchAllBehavior", 
                         true);
   CreateHostBuilder(args).Build().Run();
}
// Remaining code removed for brevity.

.NET Core 3.0 ve službě Aplikace Azure

Zavedení rozhraní .NET Core do služby Aplikace Azure je dokončené. .NET Core 3.0 je k dispozici ve všech datacentrech Aplikace Azure Service.

modul ASP.NET Core (ANCM)

Pokud ASP.NET Core Module (ANCM) nebyla vybraná komponenta při instalaci sady Visual Studio nebo pokud byla v systému nainstalována předchozí verze ANCM, stáhněte si nejnovější instalační program balíčku hostingu .NET Core (přímý stažení) a spusťte instalační program. Další informace naleznete v tématu Hosting Bundle.