This article highlights the most significant changes in ASP.NET Core 3.0 with links to relevant documentation.
Blazor is a new framework in ASP.NET Core for building interactive client-side web UI with .NET:
- Share server-side and client-side app logic written in .NET.
- Render the UI as HTML and CSS for wide browser support, including mobile browsers.
Blazor framework supported scenarios:
- Reusable UI components (Razor components)
- Client-side routing
- Component layouts
- Support for dependency injection
- Forms and validation
- Build component libraries with Razor class libraries
For more information, see Introduction to ASP.NET Core Blazor.
Blazor decouples component rendering logic from how UI updates are applied. Blazor Server provides support for hosting Razor components on the server in an ASP.NET Core app. UI updates are handled over a SignalR connection. Blazor Server is supported in ASP.NET Core 3.0.
Blazor WebAssembly (Preview)
Blazor apps can also be run directly in the browser using a WebAssembly-based .NET runtime. Blazor WebAssembly is in preview and not supported in ASP.NET Core 3.0. Blazor WebAssembly will be supported in a future release of ASP.NET Core.
Components in Blazor are typically authored using Razor syntax, a natural blend of HTML and C#. Razor components are similar to Razor Pages and MVC views in that they both use Razor. Unlike pages and views, which are based on a request-response model, components are used specifically for handling UI composition.
Is a popular, high-performance RPC (remote procedure call) framework.
Offers an opinionated contract-first approach to API development.
Uses modern technologies such as:
- HTTP/2 for transport.
- Protocol Buffers as the interface description language.
- Binary serialization format.
Provides features such as:
- Bidirectional streaming and flow control.
- Cancellation and timeouts.
gRPC functionality in ASP.NET Core 3.0 includes:
- Grpc.AspNetCore – An ASP.NET Core framework for hosting gRPC services. gRPC on ASP.NET Core integrates with standard ASP.NET Core features like logging, dependency injection (DI), authentication and authorization.
- Grpc.Net.Client – A gRPC client for .NET Core that builds upon the familiar
- Grpc.Net.ClientFactory – gRPC client integration with
For more information, see Introduction to gRPC on .NET Core.
See Update SignalR code for migration instructions. SignalR now uses
System.Text.Json to serialize/deserialize JSON messages. See Switch to Newtonsoft.Json for instructions to restore the
const connection = new signalR.HubConnectionBuilder() .withUrl("/chatHub") .withAutomaticReconnect() .build();
The reconnection intervals can be specified by passing an array of millisecond-based durations:
.withAutomaticReconnect([0, 3000, 5000, 10000, 15000, 30000]) //.withAutomaticReconnect([0, 2000, 10000, 30000]) The default intervals.
A custom implementation can be passed in for full control of the reconnection intervals.
If the reconnection fails after the last reconnect interval:
- The client considers the connection is offline.
- The client stops trying to reconnect.
During reconnection attempts, update the app UI to notify the user that the reconnection is being attempted.
To provide UI feedback when the connection is interrupted, the SignalR client API has been expanded to include the following event handlers:
onreconnecting: Gives developers an opportunity to disable UI or to let users know the app is offline.
onreconnected: Gives developers an opportunity to update the UI once the connection is reestablished.
The following code uses
onreconnecting to update the UI while trying to connect:
connection.onreconnecting((error) => const status = `Connection lost due to error "$error". Reconnecting.`; document.getElementById("messageInput").disabled = true; document.getElementById("sendButton").disabled = true; document.getElementById("connectionStatus").innerText = status; );
The following code uses
onreconnected to update the UI on connection:
connection.onreconnected((connectionId) => const status = `Connection reestablished. Connected.`; document.getElementById("messageInput").disabled = false; document.getElementById("sendButton").disabled = false; document.getElementById("connectionStatus").innerText = status; );
SignalR 3.0 and later provides a custom resource to authorization handlers when a hub method requires authorization. The resource is an instance of
HubInvocationContext includes the:
- Name of the hub method being invoked.
- Arguments to the hub method.
Consider the following example of a chat room app allowing multiple organization sign-in via Azure Active Directory. Anyone with a Microsoft account can sign in to chat, but only members of the owning organization can ban users or view users’ chat histories. The app could restrict certain functionality from specific users.
public class DomainRestrictedRequirement : AuthorizationHandler<DomainRestrictedRequirement, HubInvocationContext>, IAuthorizationRequirement protected override Task HandleRequirementAsync(AuthorizationHandlerContext context, DomainRestrictedRequirement requirement, HubInvocationContext resource) if (context.User?.Identity?.Name == null) return Task.CompletedTask; if (IsUserAllowedToDoThis(resource.HubMethodName, context.User.Identity.Name)) context.Succeed(requirement); return Task.CompletedTask; private bool IsUserAllowedToDoThis(string hubMethodName, string currentUsername) if (hubMethodName.Equals("banUser", StringComparison.OrdinalIgnoreCase)) return currentUsername.Equals("firstname.lastname@example.org", StringComparison.OrdinalIgnoreCase); return currentUsername.EndsWith("@jabbr.net", StringComparison.OrdinalIgnoreCase));
In the preceding code,
DomainRestrictedRequirement serves as a custom
IAuthorizationRequirement. Because the
HubInvocationContext resource parameter is being passed in, the internal logic can:
- Inspect the context in which the Hub is being called.
- Make decisions on allowing the user to execute individual Hub methods.
Individual Hub methods can be decorated with the name of the policy the code checks at run-time. As clients attempt to call individual Hub methods, the
DomainRestrictedRequirement handler runs and controls access to the methods. Based on the way the
DomainRestrictedRequirement controls access:
- All logged-in users can call the
- Only users who have logged in with a
@jabbr.netemail address can view users’ histories.
email@example.com ban users from the chat room.
[Authorize] public class ChatHub : Hub public void SendMessage(string message) [Authorize("DomainRestricted")] public void BanUser(string username) [Authorize("DomainRestricted")] public void ViewUserHistory(string username)
DomainRestricted policy might involve:
- In Startup.cs, adding the new policy.
- Provide the custom
DomainRestrictedRequirementrequirement as a parameter.
DomainRestrictedwith the authorization middleware.
services .AddAuthorization(options => options.AddPolicy("DomainRestricted", policy => policy.Requirements.Add(new DomainRestrictedRequirement()); ); );
SignalR hubs use Endpoint Routing. SignalR hub connection was previously done explicitly:
app.UseSignalR(routes => routes.MapHub<ChatHub>("hubs/chat"); );
In the previous version, developers needed to wire up controllers, Razor pages, and hubs in a variety of different places. Explicit connection results in a series of nearly-identical routing segments:
app.UseSignalR(routes => routes.MapHub<ChatHub>("hubs/chat"); ); app.UseRouting(routes => routes.MapRazorPages(); );
SignalR 3.0 hubs can be routed via endpoint routing. With endpoint routing, typically all routing can be configured in
app.UseRouting(routes => routes.MapRazorPages(); routes.MapHub<ChatHub>("hubs/chat"); );
ASP.NET Core 3.0 SignalR added:
Client-to-server streaming. With client-to-server streaming, server-side methods can take instances of either an
ChannelReader<T>. In the following C# sample, the
UploadStream method on the Hub will receive a stream of strings from the client:
public async Task UploadStream(IAsyncEnumerable<string> stream) await foreach (var item in stream) // process content
.NET client apps can pass either an
ChannelReader<T> instance as the
stream argument of the
UploadStream Hub method above.
for loop has completed and the local function exits, the stream completion is sent:
async IAsyncEnumerable<string> clientStreamData() for (var i = 0; i < 5; i++) var data = await FetchSomeData(); yield return data; await connection.SendAsync("UploadStream", clientStreamData());
Subject (or an RxJS Subject) for the
stream argument of the
UploadStream Hub method above.
let subject = new signalR.Subject(); await connection.send("StartStream", "MyAsciiArtStream", subject);
subject.next method to handle strings as they are captured and ready to be sent to the server.
Using code like the two preceding snippets, real-time streaming experiences can be created.
New JSON serialization
ASP.NET Core 3.0 now uses System.Text.Json by default for JSON serialization:
- Reads and writes JSON asynchronously.
- Is optimized for UTF-8 text.
- Typically higher performance than
To add Json.NET to ASP.NET Core 3.0, see Add Newtonsoft.Json-based JSON format support.
New Razor directives
The following list contains new Razor directives:
- @attribute – The
@attributedirective applies the given attribute to the class of the generated page or view. For example,
- @implements – The
@implementsdirective implements an interface for the generated class. For example,
IdentityServer4 supports authentication and authorization for web APIs and SPAs
IdentityServer4 is an OpenID Connect and OAuth 2.0 framework for ASP.NET Core 3.0. IdentityServer4 enables the following security features:
- Authentication as a Service (AaaS)
- Single sign-on/off (SSO) over multiple application types
- Access control for APIs
- Federation Gateway
For more information, see Welcome to IdentityServer4.
Certificate and Kerberos authentication
Certificate authentication requires:
- Configuring the server to accept certificates.
- Adding the authentication middleware in
- Adding the certificate authentication service in
public void ConfigureServices(IServiceCollection services) services.AddAuthentication( CertificateAuthenticationDefaults.AuthenticationScheme) .AddCertificate(); // Other service configuration removed. public void Configure(IApplicationBuilder app, IHostingEnvironment env) app.UseAuthentication(); // Other app configuration removed.
Options for certificate authentication include the ability to:
- Accept self-signed certificates.
- Check for certificate revocation.
- Check that the proffered certificate has the right usage flags in it.
A default user principal is constructed from the certificate properties. The user principal contains an event that enables supplementing or replacing the principal. For more information, see Configure certificate authentication in ASP.NET Core.
Windows Authentication has been extended onto Linux and macOS. In previous versions, Windows Authentication was limited to IIS and HttpSys. In ASP.NET Core 3.0, Kestrel has the ability to use Negotiate, Kerberos, and NTLM on Windows, Linux, and macOS for Windows domain-joined hosts. Kestrel support of these authentication schemes is provided by the Microsoft.AspNetCore.Authentication.Negotiate NuGet package. As with the other authentication services, configure authentication app wide, then configure the service:
public void ConfigureServices(IServiceCollection services) services.AddAuthentication(NegotiateDefaults.AuthenticationScheme) .AddNegotiate(); // Other service configuration removed. public void Configure(IApplicationBuilder app, IHostingEnvironment env) app.UseAuthentication(); // Other app configuration removed.
- Windows hosts must have Service Principal Names (SPNs) added to the user account hosting the app.
- Linux and macOS machines must be joined to the domain.
- SPNs must be created for the web process.
- Keytab files must be generated and configured on the host machine.
For more information, see Configure Windows Authentication in ASP.NET Core.
The web UI templates (Razor Pages, MVC with controller and views) have the following removed:
The Angular template updated to use Angular 8.
The Razor class library (RCL) template defaults to Razor component development by default. A new template option in Visual Studio provides template support for pages and views. When creating an RCL from the template in a command shell, pass the
--support-pages-and-views option (
dotnet new razorclasslib --support-pages-and-views).
The ASP.NET Core 3.0 templates use .NET Generic Host. Previous versions used WebHostBuilder. Using the .NET Core Generic Host (HostBuilder) provides better integration of ASP.NET Core apps with other server scenarios that are not web specific. For more information, see HostBuilder replaces WebHostBuilder.
Prior to the release of ASP.NET Core 3.0, environment variables prefixed with
ASPNETCORE_ were loaded for host configuration of the Web Host. In 3.0,
AddEnvironmentVariables is used to load environment variables prefixed with
DOTNET_ for host configuration with
Changes to Startup contructor injection
The Generic Host only supports the following types for
Startup constructor injection:
All services can still be injected directly as arguments to the
Startup.Configure method. For more information, see Generic Host restricts Startup constructor injection (aspnet/Announcements #353).
- Kestrel configuration has been updated for the migration to the Generic Host. In 3.0, Kestrel is configured on the web host builder provided by
- Connection Adapters have been removed from Kestrel and replaced with Connection Middleware, which is similar to HTTP Middleware in the ASP.NET Core pipeline but for lower-level connections.
- The Kestrel transport layer has been exposed as a public interface in
- Ambiguity between headers and trailers has been resolved by moving trailing headers to a new collection.
- Synchronous IO APIs, such as
HttpRequest.Body.Read, are a common source of thread starvation leading to app crashes. In 3.0,
AllowSynchronousIOis disabled by default.
For more information, see Migrate from ASP.NET Core 2.2 to 3.0.
HTTP/2 enabled by default
HTTP/2 is enabled by default in Kestrel for HTTPS endpoints. HTTP/2 support for IIS or HTTP.sys is enabled when supported by the operating system.
EventCounters on request
The Hosting EventSource,
Microsoft.AspNetCore.Hosting, emits the following new EventCounter types related to incoming requests:
Endpoint Routing, which allows frameworks (for example, MVC) to work well with middleware, is enhanced:
- The order of middleware and endpoints is configurable in the request processing pipeline of
- Endpoints and middleware compose well with other ASP.NET Core-based technologies, such as Health Checks.
- Endpoints can implement a policy, such as CORS or authorization, in both middleware and MVC.
- Filters and attributes can be placed on methods in controllers.
For more information, see Routing in ASP.NET Core.
Health Checks use endpoint routing with the Generic Host. In
MapHealthChecks on the endpoint builder with the endpoint URL or relative path:
app.UseEndpoints(endpoints => endpoints.MapHealthChecks("/health"); );
Health Checks endpoints can:
- Specify one or more permitted hosts/ports.
- Require authorization.
- Require CORS.
For more information, see the following articles:
Pipes on HttpContext
It’s now possible to read the request body and write the response body using the System.IO.Pipelines API. The
HttpRequest.BodyReader property provides a PipeReader that can be used to read the request body. The
HttpResponse.BodyWriter property provides a PipeWriter that can be used to write the response body.
HttpRequest.BodyReader is an analogue of the
HttpResponse.BodyWriter is an analogue of the
Improved error reporting in IIS
Startup errors when hosting ASP.NET Core apps in IIS now produce richer diagnostic data. These errors are reported to the Windows Event Log with stack traces wherever applicable. In addition, all warnings, errors, and unhandled exceptions are logged to the Windows Event Log.
Worker Service and Worker SDK
.NET Core 3.0 introduces the new Worker Service app template. This template provides a starting point for writing long running services in .NET Core.
For more information, see:
Forwarded Headers Middleware improvements
In previous versions of ASP.NET Core, calling UseHsts and UseHttpsRedirection were problematic when deployed to an Azure Linux or behind any reverse proxy other than IIS. The fix for previous versions is documented in Forward the scheme for Linux and non-IIS reverse proxies.
This scenario is fixed in ASP.NET Core 3.0. The host enables the Forwarded Headers Middleware when the
ASPNETCORE_FORWARDEDHEADERS_ENABLED environment variable is set to
ASPNETCORE_FORWARDEDHEADERS_ENABLED is set to
true in our container images.
ASP.NET Core 3.0 includes many improvements that reduce memory usage and improve throughput:
- Reduction in memory usage when using the built-in dependency injection container for scoped services.
- Reduction in allocations across the framework, including middleware scenarios and routing.
- Reduction in memory usage for WebSocket connections.
- Memory reduction and throughput improvements for HTTPS connections.
- New optimized and fully asynchronous JSON serializer.
- Reduction in memory usage and throughput improvements in form parsing.
ASP.NET Core 3.0 only runs on .NET Core 3.0
As of ASP.NET Core 3.0, .NET Framework is no longer a supported target framework. Projects targeting .NET Framework can continue in a fully supported fashion using the .NET Core 2.1 LTS release. Most ASP.NET Core 2.1.x related packages will be supported indefinitely, beyond the 3 year LTS period for .NET Core 2.1.
For migration information, see Port your code from .NET Framework to .NET Core.
Use the ASP.NET Core shared framework
The ASP.NET Core 3.0 shared framework, contained in the Microsoft.AspNetCore.App metapackage, no longer requires an explicit
<PackageReference /> element in the project file. The shared framework is automatically referenced when using the
Microsoft.NET.Sdk.Web SDK in the project file:
Assemblies removed from the ASP.NET Core shared framework
The most notable assemblies removed from the ASP.NET Core 3.0 shared framework are:
For a complete list of assemblies removed from the shared framework, see Assemblies being removed from Microsoft.AspNetCore.App 3.0. For more information on the motivation for this change, see Breaking changes to Microsoft.AspNetCore.App in 3.0 and A first look at changes coming in ASP.NET Core 3.0.