aspnetcore/release-notes/aspnetcore-3.0.md
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:
Blazor framework supported scenarios:
For more information, see xref:blazor/index.
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 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.
Blazor apps are built from components. Components are self-contained chunks of user interface (UI), such as a page, dialog, or form. Components are normal .NET classes that define UI rendering logic and client-side event handlers. You can create rich interactive web apps without JavaScript.
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.
gRPC:
Is a popular, high-performance RPC (remote procedure call) framework.
Offers an opinionated contract-first approach to API development.
Uses modern technologies such as:
Provides features such as:
gRPC functionality in ASP.NET Core 3.0 includes:
HttpClient.HttpClientFactory.For more information, see xref:grpc/index.
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 Newtonsoft.Json-based serializer.
In the JavaScript and .NET Clients for SignalR, support was added for automatic reconnection. By default, the client tries to reconnect immediately and retry after 2, 10, and 30 seconds if necessary. If the client successfully reconnects, it receives a new connection ID. Automatic reconnect is opt-in:
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:
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 or later provides a custom resource to authorization handlers when a hub method requires authorization. The resource is an instance of HubInvocationContext. The HubInvocationContext includes the:
HubCallerContextConsider 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("[email protected]", 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:
Individual Hub methods can be marked 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:
SendMessage method.@jabbr.net email address can view users' histories.[email protected] can 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)
{
}
}
Creating the DomainRestricted policy might involve:
Startup.cs, adding the new policy.DomainRestrictedRequirement requirement as a parameter.DomainRestricted with 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 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 UseRouting:
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 IAsyncEnumerable<T> or 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 IAsyncEnumerable<T> or ChannelReader<T> instance as the stream argument of the UploadStream Hub method above.
After the 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());
JavaScript client apps use the SignalR 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);
The JavaScript code could use the subject.next method to handle strings as they are captured and ready to be sent to the server.
subject.next("example");
subject.complete();
Using code like the two preceding snippets, real-time streaming experiences can be created.
ASP.NET Core 3.0 now uses xref:System.Text.Json by default for JSON serialization:
Newtonsoft.Json.To add Json.NET to ASP.NET Core 3.0, see Add Newtonsoft.Json-based JSON format support.
The following list contains new Razor directives:
@attribute: The @attribute directive applies the given attribute to the class of the generated page or view. For example, @attribute [Authorize].@implements: The @implements directive implements an interface for the generated class. For example, @implements IDisposable.ASP.NET Core 3.0 offers authentication in Single Page Apps (SPAs) using the support for web API authorization. ASP.NET Core Identity for authenticating and storing users is combined with IdentityServer4 for implementing OpenID Connect.
IdentityServer4 is an OpenID Connect and OAuth 2.0 framework for ASP.NET Core 3.0. It enables the following security features:
For more information, see the IdentityServer4 documentation or Authentication and authorization for SPAs.
Certificate authentication requires:
Startup.Configure.Startup.ConfigureServices.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:
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 xref:security/authentication/certauth.
Windows Authentication has been extended onto Linux and macOS. In previous versions, Windows Authentication was limited to IIS and HTTP.sys. 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.
}
Host requirements:
For more information, see xref:security/authentication/windowsauth.
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 xref:fundamentals/host/generic-host. Previous versions used xref:Microsoft.AspNetCore.Hosting.WebHostBuilder. Using the .NET Core Generic Host (xref:Microsoft.Extensions.Hosting.HostBuilder) provides better integration of ASP.NET Core apps with other server scenarios that aren't 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 CreateDefaultBuilder.
The Generic Host only supports the following types for Startup constructor injection:
IWebHostEnvironmentAll 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).
ConfigureWebHostDefaults.Connections.Abstractions.HttpRequest.Body.Read, are a common source of thread starvation leading to app crashes. In 3.0, AllowSynchronousIO is disabled by default.For more information, see xref:migration/22-to-30#kestrel.
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.
The Hosting EventSource, Microsoft.AspNetCore.Hosting, emits the following new xref:System.Diagnostics.Tracing.EventCounter types related to incoming requests:
requests-per-secondtotal-requestscurrent-requestsfailed-requestsEndpoint Routing, which allows frameworks (for example, MVC) to work well with middleware, is enhanced:
Startup.Configure.For more information, see xref:fundamentals/routing#routing-basics.
Health Checks use endpoint routing with the Generic Host. In Startup.Configure, call MapHealthChecks on the endpoint builder with the endpoint URL or relative path:
app.UseEndpoints(endpoints =>
{
endpoints.MapHealthChecks("/health");
});
Health Checks endpoints can:
For more information, see the following articles:
It's now possible to read the request body and write the response body using the xref:System.IO.Pipelines API. The <!-- <xref:Microsoft.AspNetCore.Http.HttpRequest.BodyReader> --> HttpRequest.BodyReader property provides a xref:System.IO.Pipelines.PipeReader that can be used to read the request body. The <!-- <xref:Microsoft.AspNetCore.Http.> --> HttpResponse.BodyWriter property provides a xref:System.IO.Pipelines.PipeWriter that can be used to write the response body. HttpRequest.BodyReader is an analogue of the HttpRequest.Body stream. HttpResponse.BodyWriter is an analogue of the HttpResponse.Body stream.
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.
.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:
In previous versions of ASP.NET Core, calling xref:Microsoft.AspNetCore.Builder.HstsBuilderExtensions.UseHsts* and xref:Microsoft.AspNetCore.Builder.HttpsPolicyBuilderExtensions.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 true. 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:
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 three-year LTS period for .NET Core 2.1.
For migration information, see Port your code from .NET Framework to .NET Core.
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:
<Project Sdk="Microsoft.NET.Sdk.Web">
The most notable assemblies removed from the ASP.NET Core 3.0 shared framework are:
System.Text.Json for reading and writing JSON. For more information, see New JSON serialization in this document.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.
Use the articles in Breaking changes in .NET to find breaking changes that might apply when upgrading an app to a newer version of .NET.