Delen via

Migreren van ASP.NET Core 2.2 naar 3.0

Door Scott Addie en Rick Anderson

In dit artikel wordt uitgelegd hoe u een bestaand ASP.NET Core 2.2-project bijwerkt naar ASP.NET Core 3.0. Het kan handig zijn om een nieuw ASP.NET Core 3.0-project te maken voor:

  • Vergelijk met de code ASP.NET Core 2.2.
  • Kopieer de relevante wijzigingen in uw ASP.NET Core 3.0-project.

Benodigdheden

.NET Core SDK-versie bijwerken in global.json

Als uw oplossing afhankelijk is van een global.json-bestand om een specifieke .NET Core SDK-versie te selecteren, werkt u de eigenschap version bij naar versie 3.0 die op uw computer is geïnstalleerd.

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

Het projectbestand bijwerken

Het doelframework bijwerken

ASP.NET Core 3.0 of hoger worden alleen uitgevoerd op .NET Core. Stel de Target Framework Moniker (TFM) in op netcoreapp3.0:

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

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

</Project>

Verouderde pakketverwijzingen verwijderen

Een groot aantal NuGet-pakketten wordt niet geproduceerd voor ASP.NET Core 3.0. Dergelijke pakketverwijzingen moeten worden verwijderd uit uw projectbestand. Bekijk het volgende projectbestand voor een ASP.NET Core 2.2-web-app:

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

Het bijgewerkte projectbestand voor ASP.NET Core 3.0:

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

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

</Project>

Het bijgewerkte ASP.NET Core 3.0-projectbestand:

  • In de <PropertyGroup>:

    • De TFM bijwerken naar netcoreapp3.0
    • Hiermee verwijdert u het <AspNetCoreHostingModel> element. Zie In-process hosting model in dit document voor meer informatie.

  • In de <ItemGroup>:

    • Microsoft.AspNetCore.App wordt verwijderd. Zie Framework-referentiemateriaal in dit document voor meer informatie.
    • Microsoft.AspNetCore.Razor.Design wordt verwijderd en komt voor in de volgende lijst met pakketten die niet meer geproduceerd worden.

Als u de volledige lijst met pakketten wilt zien die niet meer worden geproduceerd, selecteert u de volgende uitvouwlijst:

Klik om de lijst met pakketten uit te vouwen die niet meer worden geproduceerd
  • 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. Ontwerpen
  • 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. Kern
  • Microsoft.AspNetCore.Server.Kestrel. Https
  • Microsoft.AspNetCore.Server.Kestrel.Transport.Abstracties
  • Microsoft.AspNetCore.Server.Kestrel. Transport.Sockets
  • Microsoft.AspNetCore.Session
  • Microsoft.AspNetCore.SignalR
  • Microsoft.AspNetCore.SignalR. Kern
  • Microsoft.AspNetCore.StaticFiles
  • Microsoft.AspNetCore.WebSockets
  • Microsoft.AspNetCore.WebUtilities
  • Microsoft.Net.Http.Headers

Brekende wijzigingen bekijken

Ingrijpende wijzigingen controleren

Framework-naslagwerk

Functies van ASP.NET Core die beschikbaar waren via een van de bovenstaande pakketten, zijn beschikbaar als onderdeel van het Microsoft.AspNetCore.App gedeelde framework. Het gedeelde framework is de set van assemblies (.dll bestanden) die op de computer zijn geïnstalleerd en omvat een runtime-onderdeel en een doelpakket. Zie Het gedeelde frameworkvoor meer informatie.

  • Projecten die gericht zijn op de Microsoft.NET.Sdk.Web SDK verwijzen impliciet naar het Microsoft.AspNetCore.App framework.

    Er zijn geen aanvullende verwijzingen vereist voor deze projecten:

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

  • Projecten die gericht zijn op Microsoft.NET.Sdk of Microsoft.NET.Sdk.Razor SDK, moeten een expliciete FrameworkReference toevoegen aan Microsoft.AspNetCore.App:

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

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

Frameworkafhankelijke builds met Docker

Frameworkafhankelijke builds van console-apps die een pakket gebruiken dat afhankelijk is van het ASP.NET Core gedeelde framework kunnen de volgende runtimefout opleveren:

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 is het gedeelde framework met de ASP.NET Core-runtime en is alleen aanwezig op de docker-installatiekopie van dotnet/core/aspnet. De 3.0 SDK vermindert de grootte van frameworkafhankelijke builds met behulp van ASP.NET Core door geen dubbele kopieën van bibliotheken op te slaan die beschikbaar zijn in het gedeelde framework. Dit is een mogelijke besparing van maximaal 18 MB, maar vereist dat de ASP.NET Core-runtime aanwezig/geïnstalleerd is om de app uit te voeren.

Als u wilt bepalen of de app een afhankelijkheid (direct of indirect) heeft op het gedeelde ASP.NET Core-framework, bekijkt u het runtimeconfig.json-bestand dat is gegenereerd tijdens een build/publicatie van uw app. Het volgende JSON-bestand toont een afhankelijkheid van het gedeelde ASP.NET Core-framework:

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

Als uw app Docker gebruikt, gebruik dan een basisafbeelding met ASP.NET Core 3.0. Bijvoorbeeld: docker pull mcr.microsoft.com/dotnet/core/aspnet:3.0.

Pakketverwijzingen voor verwijderde assembly's toevoegen

ASP.NET Core 3.0 verwijdert enkele assembly's die eerder deel uitmaakten van de Microsoft.AspNetCore.App pakketreferentie. Als u wilt visualiseren welke assembly's zijn verwijderd, vergelijkt u de twee gedeelde frameworkmappen. Bijvoorbeeld een vergelijking van versie 2.2.7 en 3.0.0:

Vergelijking van gedeelde frameworkassembly's ,

Raadpleeg de 3.0-versies van de bijbehorende pakketten om functies van de verwijderde assembly's te blijven gebruiken:

Opstartwijzigingen

In de volgende afbeelding ziet u de verwijderde en gewijzigde regels in een ASP.NET Core 2.2 Razor Pages-web-app:

de verwijderde en gewijzigde regels in een ASP.NET Core 2.2 Razor-web-app

In de voorgaande afbeelding wordt verwijderde code rood weergegeven. De optiescode cookie wordt niet weergegeven in de verwijderde code, die verwijderd was voordat de bestanden werden vergeleken.

In de volgende afbeelding ziet u de toegevoegde en gewijzigde lijnen in een web-app ASP.NET Core 3.0 Razor Pages:

de toegevoegde en gewijzigde regels in een ASP.NET Core 3.0 Razor-web-app

In de voorgaande afbeelding wordt toegevoegde code groen weergegeven. Voor informatie over de volgende wijzigingen:

  • services.AddMvc voor services.AddRazorPageszie MVC-serviceregistratie in dit document.
  • CompatibilityVersion, raadpleeg de compatibiliteitsversie voor ASP.NET Core MVC, ,.
  • IHostingEnvironment tot IWebHostEnvironment, zie deze aankondiging van GitHub .
  • app.UseAuthorization is aan de sjablonen toegevoegd om te laten zien dat de middleware voor orderautorisatie moet worden toegevoegd. Als de app geen autorisatie gebruikt, kunt u de aanroep naar app.UseAuthorizationveilig verwijderen.
  • app.UseEndpointsraadpleegt u Razor Pages of Migrate Startup.Configure in dit document.

Ondersteuning voor analyse

Projecten die gericht zijn op Microsoft.NET.Sdk.Web roepen impliciet analyzers aan die eerder zijn geleverd als onderdeel van het Microsoft.AspNetCore.Mvc.Analyzers -pakket. Er zijn geen aanvullende verwijzingen vereist om deze in te schakelen.

Als uw app gebruikmaakt van API-analysen die eerder zijn verzonden met behulp van het Microsoft.AspNetCore.Mvc.Api.Analyzers-pakket, bewerkt u het projectbestand om te verwijzen naar de analysen die zijn verzonden als onderdeel van de .NET Core Web SDK:

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

    ...
</Project>

Razor klassebibliotheek

Razor class library-projecten die UI-onderdelen voor MVC bieden, moeten de eigenschap AddRazorSupportForMvc instellen in het projectbestand:

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

In-process hostingmodel

Projecten zijn standaard ingesteld op het in-process hostingmodel in ASP.NET Core 3.0 of hoger. U kunt desgewenst de eigenschap <AspNetCoreHostingModel> in het projectbestand verwijderen als de waarde InProcessis.

Kestrel

Configuratie

Migreer Kestrel configuratie naar de webhostbouwer geleverd door 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>();
        });

Als de app de host handmatig maakt met ConfigureWebHost in plaats van ConfigureWebHostDefaults, roept u UseKestrel aan op de webhostbouwer:

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 voor verbindingen vervangt verbindingsadapters

Verbindingsadapters (Microsoft.AspNetCore.Server.Kestrel.Core.Adapter.Internal.IConnectionAdapter) zijn verwijderd uit Kestrel. Vervang verbindingsadapters door verbindingsmiddleware. Middleware voor verbindingen is vergelijkbaar met HTTP Middleware in de ASP.NET Core-pijplijn, maar voor verbindingen met een lager niveau. HTTPS en logboekregistratie van verbindingen:

  • Zijn verplaatst van verbindingsadapters naar verbindings-middleware.
  • Deze uitbreidingsmethoden werken net als in eerdere versies van ASP.NET Core.

Zie het voorbeeld tlsFilterConnectionHandler in de sectie ListenOptions.Protocols van het Kestrel artikelvoor meer informatie.

Transportabstracties verplaatst en gepubliceerd

De Kestrel transportlaag is beschikbaar gesteld als een openbare interface in Connections.Abstractions. Als onderdeel van deze updates:

  • Microsoft.AspNetCore.Server.Kestrel.Transport.Abstractions en de bijbehorende typen zijn verwijderd.
  • NoDelay is verplaatst van ListenOptions naar de transportopties.
  • Microsoft.AspNetCore.Server.Kestrel.Transport.Abstractions.Internal.SchedulingMode is verwijderd uit KestrelServerOptions.

Zie de volgende GitHub-resources voor meer informatie:

Kestrel verzoektrailerheaders

Voor apps die gericht zijn op eerdere versies van ASP.NET Core:

  • Kestrel voegt http/1.1 gesegmenteerde trailerheaders toe aan de verzameling aanvraagheaders.
  • Trailers zijn beschikbaar nadat het aanvraaglichaam tot het einde is gelezen.

Dit veroorzaakt enkele zorgen over dubbelzinnigheid tussen kopteksten en trailers, dus de trailers zijn in 3.0 verplaatst naar een nieuwe collectie (RequestTrailerExtensions).

HTTP/2 aanvraagtrailers zijn:

  • Niet beschikbaar in ASP.NET Core 2.2.
  • Beschikbaar in 3.0 als RequestTrailerExtensions.

Er zijn nieuwe uitbreidingsmethoden voor verzoeken beschikbaar voor toegang tot deze trailers. Net als bij HTTP/1.1 zijn trailers beschikbaar nadat de aanvraagbody tot het einde is gelezen.

Voor de release 3.0 zijn de volgende RequestTrailerExtensions methoden beschikbaar:

  • GetDeclaredTrailers: haalt de verzoekheader Trailer op die de trailers vermeldt die na de body moeten worden verwacht.
  • SupportsTrailers: Geeft aan of de aanvraag ondersteuning biedt voor het ontvangen van trailer-kopteksten.
  • CheckTrailersAvailable: controleert of de aanvraag aanhangwagens ondersteunt en of deze beschikbaar zijn om te worden gelezen. Bij deze controle wordt niet uitgegaan dat er trailers te lezen zijn. Er zouden er misschien geen aanvullende gegevens te lezen zijn, zelfs als true door deze methode wordt geretourneerd.
  • GetTrailer: haalt de aangevraagde volgheader op uit het antwoord. Controleer SupportsTrailers voordat u GetTraileraanroept of een NotSupportedException kan optreden als de aanvraag geen ondersteuning biedt voor volgheaders.

Voor meer informatie, zie Aanvraagtrailers plaatsen in een aparte verzameling (dotnet/AspNetCore #10410).

AllowSynchronousIO uitgeschakeld

AllowSynchronousIO synchrone I/O-API's inschakelt of uitschakelt, zoals HttpRequest.Body.Read, HttpResponse.Body.Writeen Stream.Flush. Deze API's zijn een bron van thread-uitputting die leiden tot appcrashes. In 3.0 is AllowSynchronousIO standaard uitgeschakeld. Zie de sectie Synchrone I/O in het Kestrel artikelvoor meer informatie.

Als synchrone I/O nodig is, kan deze worden ingeschakeld door de AllowSynchronousIO optie te configureren op de server die wordt gebruikt (bij het aanroepen van ConfigureKestrel, bijvoorbeeld als u Kestrelgebruikt). Houd er rekening mee dat servers (Kestrel, HttpSys, TestServer, enzovoort) allemaal hun eigen AllowSynchronousIO optie hebben die geen invloed heeft op andere servers. Synchrone I/O kan per aanvraag worden ingeschakeld voor alle servers met behulp van de optie IHttpBodyControlFeature.AllowSynchronousIO:

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

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

Als u problemen ondervindt met TextWriter-implementaties of andere streams die synchrone API's aanroepen in Dispose, roep dan in plaats daarvan de nieuwe DisposeAsync-API aan.

Zie [Aankondiging] AllowSynchronousIO uitgeschakeld op alle servers (dotnet/AspNetCore #7644)voor meer informatie.

Buffering van uitvoerformatter

Newtonsoft.Json, XmlSerializeren DataContractSerializer gebaseerde uitvoerindelingen ondersteunen alleen synchrone serialisatie. Als u wilt dat deze formatters met de AllowSynchronousIO beperkingen van de server werken, buffert MVC de uitvoer van deze formatters voordat ze naar de schijf schrijven. Als gevolg van buffering zal MVC de header Content-Length opnemen wanneer erop gereageerd wordt met behulp van deze formatters.

System.Text.Json ondersteunt asynchrone serialisatie en daardoor buffert de op System.Text.Json gebaseerde formatter niet. Overweeg deze formatter te gebruiken voor betere prestaties.

Als u buffering wilt uitschakelen, kunnen toepassingen SuppressOutputFormatterBuffering configureren bij het opstarten:

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

Dit kan ertoe leiden dat de toepassing een runtime-uitzondering genereert als AllowSynchronousIO niet ook is geconfigureerd.

Microsoft.AspNetCore.Server.Kestrel.Https-assembly verwijderd

In ASP.NET Core 2.1 is de inhoud van Microsoft.AspNetCore.Server.Kestrel.Https.dll zijn verplaatst naar Microsoft.AspNetCore.Server.Kestrel.Core.dll. Dit was een niet-belangrijke update met behulp van TypeForwardedTo kenmerken. Voor 3.0 zijn de lege Microsoft.AspNetCore.Server.Kestrel.Https.dll assembly en het NuGet-pakket verwijderd.

Bibliotheken die verwijzen naar Microsoft.AspNetCore.Server.Kestrel. Https moet ASP.NET Kernafhankelijkheden bijwerken naar 2.1 of hoger.

Apps en bibliotheken die zijn gericht op ASP.NET Core 2.1 of hoger, moeten alle directe verwijzingen naar de Microsoft.AspNetCore.Server verwijderen.Kestrel. Https-pakket.

Ondersteuning voor Newtonsoft.Json (Json.NET)

Als onderdeel van het werk om het ASP.NET Core gedeelde framework teverbeteren, is Newtonsoft.Json Json.NET- verwijderd uit het gedeelde ASP.NET Core-framework.

De standaard-JSON-serializer voor ASP.NET Core is nu System.Text.Json, wat nieuw is in .NET Core 3.0. Overweeg het gebruik van System.Text.Json indien mogelijk. Het is high-performance en vereist geen extra bibliotheekafhankelijkheid. Omdat System.Text.Json echter nieuw is, ontbreken er mogelijk functies die uw app nodig heeft. Zie Migreren van Newtonsoft.Json naar System.Text.Jsonvoor meer informatie.

Newtonsoft.Json gebruiken in een ASP.NET Core 3.0 SignalR-project

  • Installeer de Microsoft.AspNetCore.SignalR. Protocols.NewtonsoftJson NuGet-pakket.

  • Koppel op de client een AddNewtonsoftJsonProtocol methodeaanroep aan het HubConnectionBuilder-exemplaar:

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

  • Koppel op de server een AddNewtonsoftJsonProtocol methodeaanroep aan de AddSignalR methodeaanroep in Startup.ConfigureServices:

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

Newtonsoft.Json gebruiken in een ASP.NET Core 3.0 MVC-project

  • Installeer het Microsoft.AspNetCore.Mvc.NewtonsoftJson-pakket.

  • Werk Startup.ConfigureServices bij om AddNewtonsoftJsonaan te roepen.

    services.AddMvc()
    .AddNewtonsoftJson();

    AddNewtonsoftJson compatibel is met de nieuwe MVC-serviceregistratiemethoden:

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

    Newtonsoft.Json-instellingen kunnen worden geconfigureerd bij de oproep van AddNewtonsoftJson.

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

    Opmerking: Als de methode AddNewtonsoftJson niet beschikbaar is, controleert u of u het Microsoft.AspNetCore.Mvc.NewtonsoftJson-pakket hebt geïnstalleerd. Een veelvoorkomende fout is het installeren van het Newtonsoft.Json--pakket in plaats van het Microsoft.AspNetCore.Mvc.NewtonsoftJson-pakket.

Voor meer informatie, zie Nieuw Json-formaat ondersteuning, gebaseerd op Newtonsoft.Json.

Registratie van MVC-service

ASP.NET Core 3.0 voegt nieuwe opties toe voor het registreren van MVC-scenario's binnen Startup.ConfigureServices.

Er zijn drie nieuwe uitbreidingsmethoden op het hoogste niveau die betrekking hebben op MVC-scenario's op IServiceCollection beschikbaar zijn. Sjablonen gebruiken deze nieuwe methoden in plaats van AddMvc. AddMvc blijft zich echter gedragen zoals in eerdere versies.

In het volgende voorbeeld wordt ondersteuning toegevoegd voor controllers en API-gerelateerde functies, maar niet voor weergaven of pagina's. De API-sjabloon maakt gebruik van deze code:

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

In het volgende voorbeeld wordt ondersteuning toegevoegd voor controllers, API-gerelateerde functies en weergaven, maar niet voor pagina's. De MVC-sjabloon (Web Application) maakt gebruik van deze code:

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

In het volgende voorbeeld wordt ondersteuning toegevoegd voor Razor Pages en minimale controllerondersteuning. De webtoepassingssjabloon maakt gebruik van deze code:

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

De nieuwe methoden kunnen ook worden gecombineerd. Het volgende voorbeeld is gelijk aan het aanroepen van AddMvc in ASP.NET Core 2.2:

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

Opstartcode routeren

Als een app UseMvc of UseSignalRaanroept, migreert u de app naar Eindpuntroutering indien mogelijk. Om de compatibiliteit van eindpuntroutering met eerdere versies van MVC te verbeteren, hebben we enkele wijzigingen in het genereren van url's die zijn geïntroduceerd in ASP.NET Core 2.2, teruggedraaid. Als u problemen ondervindt met het gebruik van Eindpuntroutering in 2.2, verwacht u verbeteringen in ASP.NET Core 3.0 met de volgende uitzonderingen:

  • Als de app IRouter implementeert of overdrat van Route, gebruikt u DynamicRouteValuesTransformer als vervanging.
  • Als de app rechtstreeks toegang heeft tot RouteData.Routers in MVC om URL's te parseren, kunt u deze vervangen door het gebruik van LinkParser.ParsePathByEndpointName.
    • Definieer de route met een routenaam.
    • Gebruik LinkParser.ParsePathByEndpointName en geef de gewenste routenaam door.

Endpoint Routing ondersteunt dezelfde syntaxis van routepatronen en ontwerpfuncties voor routepatronen als IRouter. Endpoint Routing ondersteunt IRouteConstraint. Eindpuntroutering ondersteunt [Route], [HttpGet]en de andere MVC-routeringskenmerken.

Voor de meeste toepassingen zijn alleen Startup wijzigingen vereist.

Startup.Configure migreren

Algemeen advies:

  • Voeg UseRoutingtoe.

  • Als de app UseStaticFilesaanroept, plaatst u UseStaticFilesvóórUseRouting.

  • Als de app gebruikmaakt van verificatie-/autorisatiefuncties zoals AuthorizePage of [Authorize], plaatst u de aanroep naar UseAuthentication en UseAuthorization: na, UseRouting en UseCors, maar vóór UseEndpoints:

    public void Configure(IApplicationBuilder app)
{
  ...

  app.UseStaticFiles();

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

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

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

  • Vervang UseMvc of UseSignalR door UseEndpoints.

  • Als de app gebruikmaakt van CORS--scenario's, zoals [EnableCors], plaatst u de aanroep naar UseCors vóór andere middleware die CORS gebruikt (bijvoorbeeld plaats UseCors vóór UseAuthentication, UseAuthorizationen UseEndpoints).

  • Vervang IHostingEnvironment door IWebHostEnvironment en voeg een using-instructie toe voor de Microsoft.AspNetCore.Hosting-naamruimte.

  • Vervang IApplicationLifetime door IHostApplicationLifetime (Microsoft.Extensions.Hosting naamruimte).

  • Vervang EnvironmentName door Environments (Microsoft.Extensions.Hosting naamruimte).

De volgende code is een voorbeeld van Startup.Configure in een typische ASP.NET Core 2.2-app:

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?}");
    });
}

Na het bijwerken van de vorige Startup.Configure code:

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?}");
    });
}

Waarschuwing

Voor de meeste apps moeten aanroepen naar UseAuthentication, UseAuthorizationen UseCors tussen de aanroepen naar UseRouting en UseEndpoints worden weergegeven om effectief te zijn.

Gezondheidscontroles

Statuscontroles gebruiken eindpuntroutering met de algemene host. Roep in Startup.ConfigureMapHealthChecks aan op de eindpuntbouwer met de eindpunt-URL of het relatieve pad:

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

Eindpunten voor gezondheidscontroles kunnen:

  • Geef een of meer toegestane hosts/poorten op.
  • Vereist autorisatie.
  • CORS vereisen.

Zie Health-controles in ASP.NET Corevoor meer informatie.

Richtlijnen voor middleware voor beveiliging

Ondersteuning voor autorisatie en CORS wordt geïntegreerd rond de middleware benadering. Dit maakt het gebruik van dezelfde middleware en functionaliteit in deze scenario's mogelijk. In deze release wordt een bijgewerkte autorisatie-middleware geleverd en CORS Middleware is verbeterd, zodat deze inzicht krijgt in de kenmerken die worden gebruikt door MVC-controllers.

CORS (Cross-Origin Resource Sharing)

Voorheen kon CORS moeilijk te configureren zijn. Middleware is gebruikt in sommige gebruiksscenario's, maar MVC-filters zijn bedoeld om te worden gebruikt zonder de middleware in andere gebruiksvoorbeelden. Met ASP.NET Core 3.0 raden we aan dat alle apps waarvoor CORS is vereist, de CORS Middleware gebruiken in combinatie met Endpoint Routing. UseCors kan worden geleverd met een standaardbeleid en [EnableCors] en [DisableCors] kenmerken kunnen worden gebruikt om het standaardbeleid waar nodig te overschrijven.

In het volgende voorbeeld:

  • CORS is ingeschakeld voor alle eindpunten met het default genoemde beleid.
  • De MyController-klasse schakelt CORS uit met het kenmerk [DisableCors].
public void Configure(IApplicationBuilder app)
{
    ...

    app.UseRouting();

    app.UseCors("default");

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

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

Machtiging

In eerdere versies van ASP.NET Core is autorisatieondersteuning geboden via het kenmerk [Authorize]. Autorisatie-middleware is niet beschikbaar. In ASP.NET Core 3.0 is autorisatie-middleware vereist. U wordt aangeraden de ASP.NET Core Authorization Middleware (UseAuthorization) direct na UseAuthenticationte plaatsen. De autorisatie-middleware kan ook worden geconfigureerd met een standaardbeleid dat kan worden overschreven.

In ASP.NET Core 3.0 of hoger wordt UseAuthorization in Startup.Configureaangeroepen. Voor de volgende HomeController is een aangemelde gebruiker vereist:

public void Configure(IApplicationBuilder app)
{
    ...

    app.UseRouting();

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

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

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

Wanneer u eindpuntroutering gebruikt, raden we aan om AuthorizeFilter niet te configureren en in plaats daarvan te vertrouwen op de Authorization-middleware. Als de app gebruikmaakt van een AuthorizeFilter als een globaal filter in MVC, raden we u aan om de code te herstructureren om een beleid in de aanroep naar AddAuthorizationop te geven.

De DefaultPolicy is in eerste instantie geconfigureerd om verificatie te vereisen, dus er is geen aanvullende configuratie vereist. In het volgende voorbeeld worden MVC-eindpunten gemarkeerd als RequireAuthorization, zodat alle aanvragen moeten worden geautoriseerd op basis van de DefaultPolicy. Het HomeController staat echter toegang toe, zonder dat de gebruiker zich aanmeldt bij de app vanwege [AllowAnonymous].

public void Configure(IApplicationBuilder app)
{
    ...

    app.UseRouting();

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

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

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

Autorisatie voor specifieke eindpunten

Autorisatie kan ook worden geconfigureerd voor specifieke klassen eindpunten. De volgende code is een voorbeeld van het converteren van een MVC-app die een globale AuthorizeFilter heeft geconfigureerd naar een app met een specifiek beleid waarvoor autorisatie is vereist:

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

Beleidsregels kunnen ook worden aangepast. De DefaultPolicy is geconfigureerd om authenticatie te vereisen.

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
{

U kunt ook alle eindpunten configureren om autorisatie te vereisen zonder [Authorize] of RequireAuthorization door een FallbackPolicyte configureren. De FallbackPolicy verschilt van de DefaultPolicy. De DefaultPolicy wordt geactiveerd door [Authorize] of RequireAuthorization, terwijl de FallbackPolicy wordt geactiveerd wanneer er geen ander beleid is ingesteld. FallbackPolicy is in eerste instantie geconfigureerd om aanvragen zonder autorisatie toe te staan.

Het volgende voorbeeld is hetzelfde als het voorgaande DefaultPolicy voorbeeld, maar gebruikt de FallbackPolicy om altijd verificatie op alle eindpunten te vereisen, behalve wanneer [AllowAnonymous] is opgegeven:

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

Autorisatie door middleware werkt zonder dat het framework specifieke kennis van autorisatie heeft. statuscontroles bijvoorbeeld geen specifieke kennis van autorisatie hebben, maar statuscontroles kunnen een configureerbaar autorisatiebeleid hebben dat door de middleware wordt toegepast.

Daarnaast kan elk eindpunt de autorisatievereisten aanpassen. In het volgende voorbeeld verwerkt UseAuthorization autorisatie met de DefaultPolicy, maar voor het eindpunt van de /healthz statuscontrole is een admin gebruiker vereist:

public void Configure(IApplicationBuilder app)
{
    ...

    app.UseRouting();

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

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

Beveiliging wordt geïmplementeerd voor sommige scenario's. Endpoints Middleware genereert een uitzondering als een autorisatie- of CORS-beleid wordt overgeslagen vanwege ontbrekende middleware. Analyseondersteuning om aanvullende feedback te geven over onjuiste configuratie wordt uitgevoerd.

Aangepaste autorisatiehandlers

Als de app gebruikmaakt van aangepaste autorisatiehandlers, geeft eindpuntroutering een ander resourcetype door aan handlers dan MVC. Handlers die verwachten dat de contextresource van de autorisatie-handler van het type AuthorizationFilterContext is (het resourcetype geleverd door MVC-filters) moet worden bijgewerkt om resources van het type RouteEndpoint te verwerken (het resourcetype dat wordt gegeven aan autorisatiehandlers door eindpuntroutering).

MVC maakt nog steeds gebruik van AuthorizationFilterContext resources, dus als de app MVC-autorisatiefilters gebruikt, samen met autorisatie voor eindpuntroutering, kan het nodig zijn om beide typen resources te verwerken.

SignalR

Kartering van SignalR hubs vindt nu plaats in UseEndpoints.

Wijs elke hub toe met MapHub. Net als in eerdere versies wordt elke hub expliciet vermeld.

In het volgende voorbeeld wordt ondersteuning voor de ChatHubSignalR hub toegevoegd:

public void Configure(IApplicationBuilder app)
{
    ...

    app.UseRouting();

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

Er is een nieuwe optie voor het beheren van berichtgroottelimieten van clients. Bijvoorbeeld in Startup.ConfigureServices:

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

In ASP.NET Core 2.2 kunt u TransportMaxBufferSize instellen, wat de maximale berichtgrootte effectief zou beheersen. In ASP.NET Core 3.0 bepaalt die optie nu alleen de maximale grootte voordat de backpressure wordt waargenomen.

SignalR assemblies in gedeeld raamwerk

ASP.NET Core SignalR assembly's aan de serverzijde zijn nu geïnstalleerd met de .NET Core SDK. Voor meer informatie, zie Verouderde pakketverwijzingen verwijderen in dit document.

MVC-controllers

Toewijzing van controllers vindt nu plaats in UseEndpoints.

Voeg MapControllers toe als de app kenmerkroutering gebruikt. Omdat routering ondersteuning biedt voor veel frameworks in ASP.NET Core 3.0 of hoger, is het toevoegen van controllers met attribuut-gebaseerde routering een optionele keuze.

Vervang het volgende:

  • MapRoute met MapControllerRoute
  • MapAreaRoute met MapAreaControllerRoute

Aangezien routering nu ondersteuning biedt voor meer dan alleen MVC, is de terminologie gewijzigd om deze methoden duidelijk te maken wat ze doen. Conventionele routes zoals MapControllerRoute/MapAreaControllerRoute/MapDefaultControllerRoute worden toegepast in de volgorde waarin ze worden toegevoegd. Plaats eerst specifiekere routes (zoals routes voor een gebied).

In het volgende voorbeeld:

  • MapControllers voegt ondersteuning toe voor door kenmerken gerouteerde controllers.
  • MapAreaControllerRoute voegt een conventionele route toe voor controllers in een gebied.
  • MapControllerRoute voegt een conventionele route voor controllers toe.
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?}");
    });
}

Asynchroon achtervoegsel verwijderen uit controlleractienamen

In ASP.NET Core 3.0 verwijdert ASP.NET Core MVC het achtervoegsel van de controlleractienamen Async. Zowel routering als het genereren van koppelingen wordt beïnvloed door deze nieuwe standaardinstelling. Voorbeeld:

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

Vóór ASP.NET Core 3.0:

  • De voorgaande actie kan worden geopend op de route Products/ListAsync.

  • Voor het genereren van koppelingen is het Async achtervoegsel vereist. Voorbeeld:

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

In ASP.NET Core 3.0:

  • De eerdere actie kan geopend worden op de route Products/List.

  • Voor het genereren van koppelingen hoeft u het Async achtervoegsel niet op te geven. Voorbeeld:

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

Deze wijziging heeft geen invloed op namen die zijn opgegeven met behulp van het kenmerk [ActionName]. Het standaardgedrag kan worden uitgeschakeld met de volgende code in Startup.ConfigureServices:

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

Er zijn enkele verschillen in het genereren van koppelingen (bijvoorbeeld met behulp van Url.Link en vergelijkbare API's). Deze omvatten:

  • Bij het gebruik van eindpuntroutering blijft het gebruik van routeparameters in gegenereerde URI's standaard niet noodzakelijkerwijs behouden. Dit gedrag kan worden beheerd met de IOutboundParameterTransformer-interface.
  • Het genereren van een URI voor een ongeldige route (een controller/actie of pagina die niet bestaat) produceert een lege tekenreeks onder eindpuntroutering in plaats van een ongeldige URI te produceren.
  • Omgevingswaarden (routeparameters uit de huidige context) worden niet automatisch gebruikt bij het genereren van koppelingen met eindpuntroutering. Voorheen worden bij het genereren van een koppeling naar een andere actie (of pagina) niet-opgegeven routewaarden afgeleid van de huidige omgevingswaarden. Wanneer u eindpuntroutering gebruikt, moeten alle routeparameters expliciet worden opgegeven tijdens het genereren van koppelingen.

Razor pagina's

Het mappen van Razor-pagina's vindt nu plaats in UseEndpoints.

Voeg MapRazorPages toe als de app Razor Pages gebruikt. Omdat Endpoint Routing ondersteuning biedt voor veel frameworks, is het toevoegen van Razor Pages nu een opt-in optie.

In de volgende Startup.Configure methode voegt MapRazorPages ondersteuning toe voor Razor Pages:

public void Configure(IApplicationBuilder app)
{
    ...

    app.UseRouting();

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

MVC gebruiken zonder eindpuntroutering

Voor het gebruik van MVC via UseMvc of UseMvcWithDefaultRoute in ASP.NET Core 3.0 is een expliciete aanmelding in Startup.ConfigureServicesvereist. Dit is vereist omdat MVC moet weten of deze kan vertrouwen op de autorisatie en CORS Middleware tijdens de initialisatie. Er wordt een analyse uitgevoerd die waarschuwt als de app probeert een niet-ondersteunde configuratie te gebruiken.

Als de app verouderde ondersteuning voor IRouter vereist, schakelt u EnableEndpointRouting uit met behulp van een van de volgende methoden in 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);

Gezondheidscontroles

Statuscontroles kunnen worden gebruikt als een router-ware met Eindpuntroutering.

Voeg MapHealthChecks toe om statuscontroles te gebruiken met Eindpuntroutering. De methode MapHealthChecks accepteert argumenten die vergelijkbaar zijn met UseHealthChecks. Het voordeel van het gebruik van MapHealthChecks boven UseHealthChecks is de mogelijkheid om autorisatie toe te passen en een nauwkeurigere controle te hebben over het overeenkomende beleid.

In het volgende voorbeeld wordt MapHealthChecks aangeroepen voor een statuscontrole-eindpunt op /healthz:

public void Configure(IApplicationBuilder app)
{
    ...

    app.UseRouting();

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

HostBuilder vervangt WebHostBuilder

De ASP.NET Core 3.0-sjablonen maken gebruik van Generic Host. Vorige versies gebruikten Webhost. De volgende code toont de door de ASP.NET Core 3.0-sjabloon gegenereerde klasse Program:

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

De volgende code toont de ASP.NET Core 2.2-sjabloon gegenereerde Program klasse:

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 blijft in 3.0 en is het type van de webBuilder, zoals te zien is in het voorgaande codevoorbeeld. WebHostBuilder wordt afgeschaft in een toekomstige release en vervangen door HostBuilder.

De belangrijkste wijziging van WebHostBuilder naar HostBuilder ligt bij de afhankelijkheidsinjectie (DI) van . Wanneer u HostBuildergebruikt, kunt u het volgende alleen in de constructor van Startupinjecteren:

De HostBuilder DI-beperkingen:

  • Zorg ervoor dat de DI-container slechts één keer wordt gebouwd.
  • Vermijdt de resulterende problemen met de levensduur van objecten, zoals het oplossen van meerdere exemplaren van singletons.

Zie Vermijden van opstartserviceinjectie in ASP.NET Core 3voor meer informatie.

AddAuthorization is verplaatst naar een andere assembly

De ASP.NET Core 2.2 en lagere AddAuthorization-methoden in Microsoft.AspNetCore.Authorization.dll:

  • Zijn hernoemd naar AddAuthorizationCore.
  • Zijn verplaatst naar Microsoft.AspNetCore.Authorization.Policy.dll.

Apps die zowel Microsoft.AspNetCore.Authorization.dll als Microsoft.AspNetCore.Authorization.Policy.dll gebruiken, worden niet beïnvloed.

Apps die geen Microsoft.AspNetCore.Authorization.Policy.dll gebruiken, moeten een van de volgende handelingen uitvoeren:

  • Voeg een verwijzing toe naar Microsoft.AspNetCore.Authorization.Policy.dll. Deze aanpak werkt voor de meeste apps en is alles wat vereist is.
  • Overschakelen naar het gebruik van AddAuthorizationCore

Voor meer informatie, zie Belangrijke wijziging in AddAuthorization(o =>overload leeft in een andere assembly #386.

Identity gebruikersinterface

Identity UI-updates voor ASP.NET Core 3.0:

  • Voeg een pakketreferentie toe aan Microsoft.AspNetCore.Identity.UI.
  • Apps die geen Razor Pagina gebruiken, moeten MapRazorPagesaanroepen. Zie Razor Pages in dit document.
  • Bootstrap 4 is het standaard UI-framework. Stel een IdentityUIFrameworkVersion projecteigenschap in om de standaardinstelling te wijzigen. Zie deze GitHub-aankondigingvoor meer informatie.

SignalR

De SignalR JavaScript-client is gewijzigd van @aspnet/signalr in @microsoft/signalr. Als u op deze wijziging wilt reageren, wijzigt u de verwijzingen in package.json bestanden, require-instructies en ECMAScript-import-instructies.

System.Text.Json is het standaardprotocol

System.Text.Json is nu het standaard Hub-protocol dat wordt gebruikt door zowel de client als de server.

Roep in Startup.ConfigureServicesAddJsonProtocol aan om serialisatieopties in te stellen.

Server:

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

Klant:

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

Overschakelen naar Newtonsoft.Json

Als u functies van Newtonsoft.Json gebruikt die niet worden ondersteund in System.Text.Json, kunt u teruggaan naar Newtonsoft.Json. Zie Newtonsoft.Json gebruiken in een ASP.NET Core 3.0 SignalR project eerder in dit artikel.

Gedistribueerde Redis-caches

Het Microsoft.Extensions.Caching.Redis-pakket is niet beschikbaar voor ASP.NET Core 3.0- of hoger-apps. Vervang de pakketverwijzing door Microsoft.Extensions.Caching.StackExchangeRedis. Voor meer informatie, zie gedistribueerde caching in ASP.NET Core.

Inschrijven voor runtimecompilatie

Vóór ASP.NET Core 3.0 was runtimecompilatie van weergaven een impliciete functie van het framework. Runtime-compilatie vult de build-time-compilatie van views aan. Hiermee kan het framework Razor weergaven en pagina's (.cshtml bestanden) compileren wanneer de bestanden worden gewijzigd, zonder dat de hele app opnieuw hoeft te worden opgebouwd. Deze functie ondersteunt het scenario van het maken van een snelle bewerking in de IDE en het vernieuwen van de browser om de wijzigingen weer te geven.

In ASP.NET Core 3.0 is runtimecompilatie een opt-in-scenario. Compilatie van buildtijd is het enige mechanisme voor het weergeven van compilaties die standaard is ingeschakeld. De runtime is afhankelijk van Visual Studio of dotnet-watch in Visual Studio Code om het project opnieuw te bouwen wanneer wijzigingen in .cshtml bestanden worden gedetecteerd. In Visual Studio worden wijzigingen in .cs, .cshtmlof .razor bestanden in het project uitgevoerd (Ctrl+F5), maar worden er geen fouten opgespoord (F5), waardoor het project opnieuw wordt gecompileerd.

Runtimecompilatie inschakelen in uw ASP.NET Core 3.0-project:

  1. Installeer de Microsoft.AspNetCore.Mvc.Razor. RuntimeCompilation NuGet-pakket.

  2. Werk Startup.ConfigureServices bij om AddRazorRuntimeCompilationaan te roepen:

    Gebruik de volgende code voor ASP.NET Core MVC:

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

    Gebruik de volgende code voor ASP.NET Core Razor Pages:

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

In het voorbeeld op https://github.com/aspnet/samples/tree/main/samples/aspnetcore/mvc/runtimecompilation ziet u een voorbeeld van het inschakelen van runtimecompilatie voorwaardelijk in ontwikkelomgevingen.

Zie Razorvoor meer informatie over Razor bestandscompilatie.

Bibliotheken migreren via meerdere targeting

Bibliotheken moeten vaak meerdere versies van ASP.NET Core ondersteunen. De meeste bibliotheken die zijn gecompileerd op basis van eerdere versies van ASP.NET Core, moeten zonder problemen blijven werken. Voor de volgende voorwaarden moet de app kruislings worden gecompileerd:

  • De bibliotheek is afhankelijk van een functie met een binaire brekende verandering.
  • De bibliotheek wil profiteren van nieuwe functies in ASP.NET Core 3.0.

Voorbeeld:

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

Gebruik #ifdefs om ASP.NET Core 3.0-specifieke API's in te schakelen:

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

Zie ASP.NET Core-API's gebruiken in een klassebibliotheekvoor meer informatie over het gebruik van ASP.NET Core-API's.

Diverse wijzigingen

Het validatiesysteem in .NET Core 3.0 of hoger behandelt niet-nullable parameters of afhankelijke eigenschappen alsof ze een [Required] kenmerk hadden. Zie kenmerk [Vereist]voor meer informatie.

Publiceren

Verwijder de bin en obj mappen in de projectmap.

testserver

Voor apps die rechtstreeks gebruikmaken van TestServer met de Generic Host-, maakt u de TestServer op een IWebHostBuilder in 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);
}

Ingrijpende API-wijzigingen

Belangrijke wijzigingen bekijken:

Eindpuntroutering met catch-all-parameter

Waarschuwing

Een catch-all--parameter kan verkeerde routes matchen door een fout in de routering. Apps die door deze fout worden beïnvloed, hebben de volgende kenmerken:

  • Een catch-all-route, bijvoorbeeld {**slug}"
  • De catch-all-route kan niet overeenkomen met aanvragen die moeten overeenkomen.
  • Als u andere routes verwijdert, begint de catch-all route te werken.

Zie GitHub-bugs 18677 en 16579 voor voorbeeldgevallen die deze bug ervaren.

Een opt-in-oplossing voor deze fout is opgenomen in .NET Core 3.1.301 of hoger SDK. Met de volgende code wordt een interne switch ingesteld waarmee deze fout wordt opgelost:

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 in Azure App Service

De implementatie van .NET Core naar Azure App Service is voltooid. .NET Core 3.0 is beschikbaar in alle Azure App Service-datacenters.

ASP.NET Core Module (ANCM)

Als de ASP.NET Core Module (ANCM) geen geselecteerd onderdeel was toen Visual Studio werd geïnstalleerd of als er een eerdere versie van de ANCM op het systeem was geïnstalleerd, downloadt u de meest recente .NET Core Hosting Bundle Installer (direct downloaden) en voert u het installatieprogramma uit. Zie Hosting Bundlevoor meer informatie.