docs/en/release-info/migration-guides/abp-8-2-blazor-web-app.md
//[doc-seo]
{
"Description": "Learn how to migrate to the ABP v8.2 Blazor Web App template, exploring new features and rendering modes for enhanced web UI development."
}
ASP.NET Blazor in .NET 8 allows you to use a single powerful component model to handle all of your web UI needs, including server-side rendering, client-side rendering, streaming rendering, progressive enhancement, and much more!
ABP v8.2.x supports the new Blazor Web App template, in this guide, we will introduce some new changes and features in the new Blazor Web App template.
Please make sure you have installed the 8.2.x version of the ABP CLI.
You can create a new Blazor Web App using the abp new BookStore -t app -u blazor-webapp command. The -u blazor-webapp option is used to select the Blazor Web App template.
Of course, you can also create Blazor WASM and Blazor Server applications. We have changed them to use the new Blazor Web App mode:
abp new BookStore -t app -u blazor
abp new BookStore -t app -u blazor-server
The template project use different render modes for different types of projects in the App.razor component.
| Type | Render mode |
|---|---|
| WASM | InteractiveWebAssembly(prerender: false) |
| Server | InteractiveServer |
| WebApp | InteractiveAuto |
The new Web App template has two projects, each containing a system of ABP modules.
The Blazor.WebApp is the startup project, and there is an App.razor component in the Blazor.WebApp project, which is the root component of the Blazor application.
The main differences between it, and a regular Blazor server project are:
PreConfigure the IsBlazorWebApp to true in AbpAspNetCoreComponentsWebOptions:public override void PreConfigureServices(ServiceConfigurationContext context)
{
PreConfigure<AbpAspNetCoreComponentsWebOptions>(options =>
{
options.IsBlazorWebApp = true;
});
}
MyProjectNameBlazorClientModule to the AdditionalAssemblies by configuring AbpRouterOptions:public override void ConfigureServices(ServiceConfigurationContext context)
{
// Add services to the container.
context.Services.AddRazorComponents()
.AddInteractiveServerComponents()
.AddInteractiveWebAssemblyComponents();
Configure<AbpRouterOptions>(options =>
{
options.AppAssembly = typeof(MyProjectNameBlazorModule).Assembly;
options.AdditionalAssemblies.Add(typeof(MyProjectNameBlazorClientModule).Assembly);
});
}
UseAntiforgery middleware and MapRazorComponents/AddInteractiveServer/WebAssemblyRenderMode/AddAdditionalAssemblies in the OnApplicationInitialization method.public override void OnApplicationInitialization(ApplicationInitializationContext context)
{
var env = context.GetEnvironment();
var app = context.GetApplicationBuilder();
// ...
app.UseAntiforgery();
app.UseAuthorization();
app.UseConfiguredEndpoints(builder =>
{
builder.MapRazorComponents<App>()
.AddInteractiveServerRenderMode()
.AddInteractiveWebAssemblyRenderMode()
.AddAdditionalAssemblies(builder.ServiceProvider.GetRequiredService<IOptions<AbpRouterOptions>>().Value.AdditionalAssemblies.ToArray());
});
}
There is a Routers.razor component in the Blazor.WebApp.Client project, which is used by the App.razor component.
The main differences between it and a regular Blazor WASM project are:
PreConfigure the IsBlazorWebApp to true in AbpAspNetCoreComponentsWebOptions:public override void PreConfigureServices(ServiceConfigurationContext context)
{
PreConfigure<AbpAspNetCoreComponentsWebOptions>(options =>
{
options.IsBlazorWebApp = true;
});
}
AddBlazorWebAppServices to replace Authentication code:private static void ConfigureAuthentication(WebAssemblyHostBuilder builder)
{
builder.Services.AddBlazorWebAppServices();
}
builder.RootComponents.Add<App>("#ApplicationContainer"); code.The tiered projects are the same as the WebApp projects, but the authentication configuration is different.
We need share the access_token to Client project.
Add code block to App.razor of MyCompanyName.MyProjectName.Blazor.WebApp.Tiered as below:
@code{
[CascadingParameter]
private HttpContext HttpContext { get; set; } = default!;
[Inject]
private PersistentComponentState PersistentComponentState { get; set; }
private string? Token { get; set; } = default!;
protected override async Task OnInitializedAsync()
{
if (HttpContext.User?.Identity?.IsAuthenticated == true)
{
Token = await HttpContext.GetTokenAsync("access_token");
}
PersistentComponentState.RegisterOnPersisting(OnPersistingAsync, RenderMode.InteractiveWebAssembly);
}
async Task OnPersistingAsync()
{
if (!Token.IsNullOrWhiteSpace())
{
PersistentComponentState.PersistAsJson(PersistentAccessToken.Key, new PersistentAccessToken
{
AccessToken = Token
});
}
await Task.CompletedTask;
}
}
Add ConfigureAuthentication to MyProjectNameBlazorClientModule of MyCompanyName.MyProjectName.Blazor.WebApp.Tiered.Client as below:
private static void ConfigureAuthentication(WebAssemblyHostBuilder builder)
{
builder.Services.AddBlazorWebAppTieredServices();
}
You need set IsBlazorWebApp and InteractiveAuto to true in the appsettings.json file of the MyCompanyName.MyProjectName.Blazor.WebApp.Client project:
{
"AbpCli": {
"Bundle": {
"Mode": "BundleAndMinify", /* Options: None, Bundle, BundleAndMinify */
"Name": "global",
"IsBlazorWebApp": true,
"InteractiveAuto": true,
"Parameters": {
}
}
}
}
For Blazor WASM and Blazor Server applications, you need to set IsBlazorWebApp to true and not need to change the InteractiveAuto:
{
"AbpCli": {
"Bundle": {
"Mode": "BundleAndMinify", /* Options: None, Bundle, BundleAndMinify */
"Name": "global",
"IsBlazorWebApp": true,
"Parameters": {
}
}
}
}
Then run the abp bundle command to under the MyCompanyName.MyProjectName.Blazor.WebApp.Client project to generate the global.css and global.js files.
If you encounter any problems during the migration, please create a new template project and compare the differences between the new and old projects.