Category: Microsoft Webdev

.NET 5 Release Candidate 1 (RC1) is now available and is ready for evaluation. Here’s what’s new in this release:

• Blazor WebAssembly performance improvements
• Blazor component virtualization
• Blazor WebAssembly prerendering
• Browser compatibility analyzer for Blazor WebAssembly
• Blazor JavaScript isolation and object references
• Blazor file input support
• Custom validation class attributes in Blazor
• Blazor support for ontoggle event
• Model binding DateTime as UTC
• Control Startup class activation
• Open API Specification (Swagger) on-by-default in ASP.NET Core API projects
• Better F5 Experience for ASP.NET Core API Projects
• SignalR parallel hub invocations
• Added Messagepack support in SignalR Java client
• Kestrel endpoint-specific options via configuration

See the .NET 5 release notes for additional details and known issues.

Get started

To get started with ASP.NET Core in .NET 5 RC1 install the .NET 5 SDK. .NET RC1 also is included with Visual Studio 2019 16.8 Preview 3.

You need to use Visual Studio 2019 16.8 Preview 3 or newer to use .NET 5 RC1. .NET 5 is also supported with the latest preview of Visual Studio for Mac. To use .NET 5 with Visual Studio Code, install the latest version of the C# extension.

Upgrade an existing project

To upgrade an existing ASP.NET Core app from .NET 5 Preview 8 to .NET 5 RC1:

• Update all Microsoft.AspNetCore.* package references to 5.0.0-rc.1.*.
  • If you’re using the new Microsoft.AspNetCore.Components.Web.Extensions package, update to version 5.0.0-preview.9.*. This package doesn’t have an RC version number yet because we expect to make a few more design changes to the components it contains before it’s ready to ship.
• Update all Microsoft.Extensions.* package references to 5.0.0-rc.1.*.
• Update System.Net.Http.Json package references to 5.0.0-rc.1.*.

In Blazor WebAssembly projects, also make the follwowing updates to the project file:

• Update the SDK from “Microsoft.NET.Sdk.Web” to “Microsoft.NET.Sdk.BlazorWebAssembly”
• Remove the <RuntimeIdentifier>browser-wasm</RuntimeIdentifier> and <UseBlazorWebAssembly>true</UseBlazorWebAssembly> properties.

That’s it! You should be all ready to go.

See also the full list of breaking changes in ASP.NET Core for .NET 5.

What’s new?

Blazor WebAssembly performance improvements

For .NET 5, we’ve made significant improvements to Blazor WebAssembly runtime performance, with a specific focus on complex UI rendering and JSON serialization. In our performance tests, Blazor WebAssembly in .NET 5 is 2-3x faster for most scenarios.

Runtime code execution in Blazor WebAssembly in .NET 5 is generally faster than Blazor WebAssembly 3.2 due to optimizations in the core framework libraries and improvements to the .NET IL interpreter. Things like string comparisons, dictionary lookups, and JSON handling are generally much faster in .NET 5 on WebAssembly.

As shown in the chart below, JSON handling is almost twice as fast in .NET 5 on WebAssembly:

We also optimized the performance of Blazor component rendering, particularly for UI involving lots of components, like when using high-density grids.

To test the performance of grid component rendering in .NET 5, we used three different grid component implementations, each rendering 200 rows with 20 columns:

• Fast Grid: A minimal, highly optimized implementation of a grid
• Plain Table: A minimal but not optimized implementation of a grid.
• Complex Grid: A maximal, not optimized implementation of a grid, using a wide range of Blazor features at once, deliberately intended to create a bad case for the renderer.

From our tests, grid rendering is 2-3x faster in .NET 5:

You can find the code for these performance tests in the ASP.NET Core GitHub repo.

You can expect ongoing work to improve Blazor WebAssembly performance. Besides optimizing the Blazor WebAssembly runtime and framework, the .NET team is also working with browser implementers to further speed up WebAssembly execution. And for .NET 6, we expect to ship support for ahead-of-time (AoT) compilation to WebAssembly, which should further improve performance.

Blazor component virtualization

You can further improve the perceived performance of component rendering using the new built-in virtualization support. Virtualization is a technique for limiting the UI rendering to just the parts that are currently visible, like when you have a long list or table with many rows and only a small subset is visible at any given time. Blazor in .NET 5 adds a new Virtualize component that can be used to easily add virtualization to your components.

A typical list or table-based component might use a C# foreach loop to render each item in the list or each row in the table, like this:

@foreach (var employee in employees)
{ <tr> <td>@employee.FirstName</td> <td>@employee.LastName</td> <td>@employee.JobTitle</td> </tr>
}

If the list grew to include thousands of rows, then rendering it may take a while, resulting in a noticeable UI lag.

Instead, you can replace the foreach loop with the Virtualize component, which only renders the rows that are currently visible.

<Virtualize Items="employees" Context="employee"> <tr> <td>@employee.FirstName</td> <td>@employee.LastName</td> <td>@employee.JobTitle</td> </tr>
</Virtualize>

The Virtualize component calculates how many items to render based on the height of the container and the size of the rendered items.

If you don’t want to load all items into memory, you can specify an ItemsProvider, like this:

<Virtualize ItemsProvider="LoadEmployees" Context="employee"> <tr> <td>@employee.FirstName</td> <td>@employee.LastName</td> <td>@employee.JobTitle</td> </tr>
</Virtualize>

An items provider is a delegate method that asynchronously retrieves the requested items on demand. The items provider receives an ItemsProviderRequest, which specifies the required number of items starting at a specific start index. The items provider then retrieves the requested items from a database or other service and returns them as an ItemsProviderResult<TItem> along with a count of the total number of items available. The items provider can choose to retrieve the items with each request, or cache them so they are readily available.

async ValueTask<ItemsProviderResult<Employee>> LoadEmployees(ItemsProviderRequest request)
{ var numEmployees = Math.Min(request.Count, totalEmployees - request.StartIndex); var employees = await EmployeesService.GetEmployeesAsync(request.StartIndex, numEmployees, request.CancellationToken); return new ItemsProviderResult<Employee>(employees, totalEmployees);
}

Because requesting items from a remote data source might take some time, you also have the option to render a placeholder until the item data is available.

<Virtualize ItemsProvider="LoadEmployees" Context="employee"> <ItemContent> <tr> <td>@employee.FirstName</td> <td>@employee.LastName</td> <td>@employee.JobTitle</td> </tr> </ItemContent> <Placeholder> <tr> <td>Loading...</td> </tr> </Placeholder>
</Virtualize>

Blazor WebAssembly prerendering

The component tag helper now supports two additional render modes for prerendering a component from a Blazor WebAssembly app:

• WebAssemblyPrerendered: Prerenders the component into static HTML and includes a marker for a Blazor WebAssembly app to later use to make the component interactive when loaded in the browser.
• WebAssembly: Renders a marker for a Blazor WebAssembly app to use to include an interactive component when loaded in the browser. The component is not prerendered. This option simply makes it easier to render different Blazor WebAssembly components on different cshtml pages.

To setup prerendering in an Blazor WebAssembly app:

1. Host the Blazor WebAssembly app in an ASP.NET Core app.
2. Replace the default static index.html file in the client project with a _Host.cshtml file in the server project.
3. Update the server startup logic to fallback to _Host.cshtml instead of index.html (similar to how the Blazor Server template is set up).

4. Update _Host.cshtml to use the component tag helper to prerender the root App component:

   <component type="typeof(App)" render-mode="WebAssemblyPrerendered" />
   

You can also pass parameters to the component tag helper when using the WebAssembly-based render modes if the parameters are serializable. The parameters must be serializable so that they can be transferred to the client and used to initialize the component in the browser. If prerendering, you’ll also need to be sure to author your components so that they can gracefully execute server-side without access to the browser.

<component type="typeof(Counter)" render-mode="WebAssemblyPrerendered" param-IncrementAmount="10" />

In additional to improving the perceived load time of a Blazor WebAssembly app, you can also use the component tag helper with the new render modes to add multiple components on different pages and views. You don’t need to configure these components as root components in the app or add your own marker tags on the page – the framework handles that for you.

Browser compatibility analyzer for Blazor WebAssembly

Blazor WebAssembly apps in .NET 5 target the full .NET 5 API surface area, but not all .NET 5 APIs are supported on WebAssembly due to browser sandbox constraints. Unsupported APIs throw PlatformNotSupportedException when running on WebAssembly. .NET 5 now includes a platform compatibility analyzer that will warn you when your app uses APIs that are not supported by your target platforms. For Blazor WebAssembly apps, this means checking that APIs are supported in browsers.

We haven’t added all of the annotations yet to the core libraries in .NET 5 to indicate which APIs are not supported in browsers, but some APIs, mostly Windows specific APIs, are already annotated:

To enable browser compatibilty checks for libraries, add “browser” as a supported platform in your project file (Blazor WebAssembly projects and Razor class library projects do this for you):

<SupportedPlatform Include="browser" />

When authoring a library, you can optionally indicate that a particular API is not supported in browsers by applying the UnsupportedOSPlatformAttribute:

[UnsupportedOSPlatform("browser")]
private static string GetLoggingDirectory()
{ // ...
}

Blazor JavaScript isolation and object references

Blazor now enables you to isolate your JavaScript as standard JavaScript modules. This has a couple of benefits:

1. Imported JavaScript no longer pollutes the global namespace.
2. Consumers of your library and components no longer need to manually import the related JavaScript.

For example, the following JavaScript module exports a simple JavaScript function for showing a browser prompt:

export function showPrompt(message) { return prompt(message, 'Type anything here');
}

You can add this JavaScript module to your .NET library as a static web asset (wwwroot/exampleJsInterop.js) and then import the module into your .NET code using the IJSRuntime service:

var module = await jsRuntime.InvokeAsync<JSObjectReference>("import", "./_content/MyComponents/exampleJsInterop.js");

The “import” identifier is a special identifier used specifically for importing a JavaScript module. You specify the module using its stable static web asset path: _content/[LIBRARY NAME]/[PATH UNDER WWWROOT].

The IJSRuntime imports the module as a JSObjectReference, which represents a reference to a JavaScript object from .NET code. You can then use the JSObjectReference to invoke exported JavaScript functions from the module:

public async ValueTask<string> Prompt(string message)
{ return await module.InvokeAsync<string>("showPrompt", message);
}

JSObjectReference greatly simplifies interacting with JavaScript libraries where you want to capture JavaScript object references, and then later invoke their functions from .NET.

Blazor file input support

Blazor now offers an InputFile component for handling file uploads, or more generally for reading browser file data into your .NET code.

The InputFile component renders as an HTML input of type “file”. By default, the user can select single files, or if you add the “multiple” attribute then the user can supply multiple files at once. When one or more files is selected by the user, the InputFile component fires an OnChange event and passes in an InputFileChangeEventArgs that provides access to the selected file list and details about each file.

<InputFile OnChange="OnInputFileChange" multiple /> <div class="image-list"> @foreach (var imageDataUrl in imageDataUrls) { <img src="@imageDataUrl" /> }
</div> @code { IList<string> imageDataUrls = new List<string>(); async Task OnInputFileChange(InputFileChangeEventArgs e) { var imageFiles = e.GetMultipleFiles(); var format = "image/png"; foreach (var imageFile in imageFiles) { var resizedImageFile = await imageFile.RequestImageFileAsync(format, 100, 100); var buffer = new byte[resizedImageFile.Size]; await resizedImageFile.OpenReadStream().ReadAsync(buffer); var imageDataUrl = $"data:{format};base64,{Convert.ToBase64String(buffer)}"; imageDataUrls.Add(imageDataUrl); } }
}

To read data from a user-selected file, you call OpenReadStream on the file and read from the returned stream. In a Blazor WebAssembly app, the data is streamed directly into your .NET code within the browser. In a Blazor Server app, the file data is streamed to your .NET code on the server as you read from the stream. In case you’re using the component to receive an image file, Blazor also provides a RequestImageFileAsync convenience method for resizing images data within the browser’s JavaScript runtime before they’re streamed into your .NET application.

Custom validation class attributes in Blazor

You can now specify custom validation class names in Blazor. This is useful when integrating with CSS frameworks, like Bootstrap.

To specify custom validation class names, create a class derived from FieldCssClassProvider and set it on the EditContext instance.

var editContext = new EditContext(model);
editContext.SetFieldCssClassProvider(new MyFieldClassProvider()); // ... class MyFieldClassProvider : FieldCssClassProvider
{ public override string GetFieldCssClass(EditContext editContext, in FieldIdentifier fieldIdentifier) { var isValid = !editContext.GetValidationMessages(fieldIdentifier).Any(); return isValid ? "legit" : "totally-bogus"; }
}

Blazor support for ontoggle event

Blazor now has support for the ontoggle event:

<div> @if (detailsExpanded) { <p>Read the details carefully!</p> } <details id="details-toggle" @ontoggle="OnToggle"> <summary>Summary</summary> <p>Detailed content</p> </details>
</div> @code { bool detailsExpanded; string message { get; set; } void OnToggle() { detailsExpanded = !detailsExpanded; }
}

Thank you Vladimir Samoilenko for this contribution!

Model binding DateTime as UTC

Model binding in ASP.NET Core now supports correctly binding UTC time strings to DateTime. If the request contains a UTC time string (for example https://example.com/mycontroller/myaction?time=2019-06-14T02%3A30%3A04.0576719Z), model binding will correctly bind it to a UTC DateTime without the need for further customization.

Control Startup class activation

We’ve provided an additional UseStartup overload that lets you provide a factory method for controlling Startup class activation. This is useful if you want to pass additional parameters to Startup that are initialized along with the host.

public class Program
{ public static async Task Main(string[] args) { var logger = CreateLogger(); var host = Host.CreateDefaultBuilder() .ConfigureWebHost(builder => { builder.UseStartup(context => new Startup(logger)); }) .Build(); await host.RunAsync(); }
}

Open API Specification On-by-default

Open API Specification is a industry-adopted convention for describing HTTP APIs and integrating them into complex business processes or with 3rd parties. Open API is widely supported by all cloud providers and many API registries, so developers who emit Open API documents from their Web APIs have a variety of new opportunities in which those APIs can be used. In partnership with the maintainers of the open-source project Swashbuckle.AspNetCore, we’re excited to announce that the ASP.NET Core API template in RC1 comes pre-wired with a NuGet dependency on Swashbuckle, a popular open-source NuGet package that emits Open API documents dynamically. Swashbuckle does this by introspecting over your API Controllers and generating the Open API document at run-time, or at build time using the Swashbuckle CLI.

In .NET 5 RC1, running dotnet new webapi will result in the Open API output being enabled by default, but if you prefer to have Open API disabled, use dotnet new webapi --no-openapi true. All .csproj files that are created for Web API projects will come with the NuGet package reference.

<ItemGroup> <PackageReference Include="Swashbuckle.AspNetCore" Version="5.5.1" />
</ItemGroup>

In addition to the NuGet package reference being in the .csproj file we’ve added code to both the ConfigureServices method in Startup.cs that activates Open API document generation.

public void ConfigureServices(IServiceCollection services)
{ services.AddControllers(); services.AddSwaggerGen(c => { c.SwaggerDoc("v1", new OpenApiInfo { Title = "WebApplication1", Version = "v1" }); });
}

The Configure method is also pre-wired to enlist in the Swashbuckle middleware. This lights up the document generation process and turns on the Swagger UI page by default in development mode. This way you’re confident that the out-of-the-box experience doesn’t accidentally expose your API’s description when you publish to production.

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{ if (env.IsDevelopment()) { app.UseDeveloperExceptionPage(); app.UseSwagger(); app.UseSwaggerUI(c => c.SwaggerEndpoint("/swagger/v1/swagger.json", "WebApplication1 v1")); } // ...
}

Azure API Management Import

When ASP.NET Core API projects are wired to output Open API in this way, the Visual Studio 2019 version 16.8 Preview 2.1 publishing experience will automatically offer an additional step in the publishing flow. Developers who use Azure API Management have an opportunity to automatically import their APIs into Azure API Management during the publish flow.

This additional publishing step reduces the number of steps HTTP API developers need to execute to get their APIs published and used with Azure Logic Apps or PowerApps.

Better F5 Experience for Web API Projects

With Open API enabled by default, we were able to significantly improve the F5 experience for Web API developers. With .NET 5 RC1, the Web API template comes pre-configured to load up the Swagger UI page. The Swagger UI page provides both the documentation you’ve added for your API, but enables you to test your APIs with a single click.

SignalR parallel hub invocations

In .NET 5 RC1, ASP.NET Core SignalR is now capable of handling parallel hub invocations. You can change the default behavior and allow clients to invoke more than one hub method at a time.

public void ConfigureServices(IServiceCollection services)
{ services.AddSignalR(options => { options.MaximumParallelInvocationsPerClient = 5; });
}

Added Messagepack support in SignalR Java client

We’re introducing a new package, com.microsoft.signalr.messagepack, that adds messagepack support to the SignalR java client. To use the messagepack hub protocol, add .withHubProtocol(new MessagePackHubProtocol()) to the connection builder.

HubConnection hubConnection = HubConnectionBuilder.create("http://localhost:53353/MyHub") .withHubProtocol(new MessagePackHubProtocol()) .build();

Kestrel endpoint-specific options via configuration

We have added support for configuring Kestrel’s endpoint-specific options via configuration. The endpoint-specific configurations includes the Http protocols used, the TLS protocols used, the certificate selected, and the client certificate mode.

You are able to configure the which certificate is selected based on the specified server name as part of the Server Name Indication (SNI) extension to the TLS protocol as indicated by the client. Kestrel’s configuration also support a wildcard prefix in the host name.

The example belows shows you how to specify endpoint-specific using a configuration file:

{ "Kestrel": { "Endpoints": { "EndpointName": { "Url": "https://*", "Sni": { "a.example.org": { "Protocols": "Http1AndHttp2", "SslProtocols": [ "Tls11", "Tls12"], "Certificate": { "Path": "testCert.pfx", "Password": "testPassword" }, "ClientCertificateMode" : "NoCertificate" }, "*.example.org": { "Certificate": { "Path": "testCert2.pfx", "Password": "testPassword" } }, "*": { // At least one subproperty needs to exist per SNI section or it // cannot be discovered via IConfiguration "Protocols": "Http1", } } } } }
}

Give feedback

We hope you enjoy this release of ASP.NET Core in .NET 5! We are eager to hear about your experiences with this latest .NET 5 release. Let us know what you think by filing issues on GitHub.

Thanks for trying out ASP.NET Core!