Skip to content

API proposal for Culture Persistence for Blazor WebAssembly Components #63183

@dariatiurina

Description

@dariatiurina

Background and Motivation

This API addresses the need to persist culture information from server-side rendering to WebAssembly components during hydration. Currently, when Blazor WebAssembly components are prerendered on the server with a specific culture, that culture information is lost when the components become interactive on the client side. This creates inconsistency in localization behavior between server-side rendering and client-side interactivity.

The proposed solution enables automatic persistence of CultureInfo.CurrentCulture and CultureInfo.CurrentUICulture from the server to the WebAssembly client, ensuring consistent localization throughout the component lifecycle.

Proposed API

namespace Microsoft.Extensions.DependencyInjection
{
    public static class WebAssemblyRazorComponentsBuilderExtensions
    {
        public static IRazorComponentsBuilder AddInteractiveWebAssemblyComponents(this IRazorComponentsBuilder builder);
        
+       public static IRazorComponentsBuilder AddInteractiveWebAssemblyComponents(this IRazorComponentsBuilder builder, bool persistCultureFromServer);
    }
}

Usage Examples

// Enable culture persistence (default behavior)
builder.Services.AddRazorComponents()
    .AddInteractiveWebAssemblyComponents();

// Explicitly enable culture persistence
builder.Services.AddRazorComponents()
    .AddInteractiveWebAssemblyComponents(persistCultureFromServer: true);

// Disable culture persistence
builder.Services.AddRazorComponents()
    .AddInteractiveWebAssemblyComponents(persistCultureFromServer: false);

When enabled, the server culture will be automatically captured during prerendering and restored on the WebAssembly client:

@* Server sets culture to fr-FR during prerendering *@
@page "/my-component"
@using System.Globalization

<p>Culture: @CultureInfo.CurrentCulture.Name</p>
<p>UI Culture: @CultureInfo.CurrentUICulture.Name</p>

@* After WebAssembly hydration, culture remains fr-FR when persistence is enabled *@

Alternative Designs

Several alternative approaches were considered:

  1. Manual culture persistence: Requiring developers to manually persist and restore culture using PersistentComponentState. This approach would provide more control but increase boilerplate code.

  2. Always-on culture persistence: Making culture persistence mandatory without an opt-out option. This was rejected to maintain backward compatibility.

  3. Separate API for culture configuration: Creating a dedicated method like ConfigureCulturePersistence(). This was deemed unnecessary for a single boolean flag.

The proposed design was chosen because it leverages the existing persistent component state infrastructure and provides a simple opt-in/opt-out mechanism while maintaining backward compatibility through method overloading.

Risks

  1. Breaking Change in Default Behavior: The parameterless AddInteractiveWebAssemblyComponents() now defaults to enabling culture persistence (persistCultureFromServer: true). This changes existing behavior and could affect applications that rely on WebAssembly components using default culture instead of server culture.

Metadata

Metadata

Assignees

No one assigned

    Labels

    api-ready-for-reviewAPI is ready for formal API review - https://github.com/dotnet/apireviewsarea-blazorIncludes: Blazor, Razor Components

    Type

    No type

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions