Re-add proper API calls into Blazor WebAssembly template

[SteveSandersonMS]

As of .NET 8, the Blazor Web template with WebAssembly interactivity does not contain any example of calling a server API. The "weather forecast" page simply generates data on the client and thus only demonstrates how to render a table, not how to fetch data.

Actually calling a server API in all generality, accounting for all the main ways of setting up a site, is complicated by several factors, as pointed out by @mrpmorris:

• Deal with prerendering or auto mode. In these cases, you have to be able to load the data when running on WebAssembly and when running on the server. So you must either:
  • Register HttpClient in DI with a base address on both server and client, and have the server call itself via HTTP
  • Or, have some interface representing the datastore, and set up both server and client implementations
• Avoid the double-render problem whereby the data is loaded twice (once for prerendering, once for interactivity)
  • This is more complicated with per-page interactivity, since enanced nav doesn't currently work with persistent state
• Make this work sensibly with auth, including for both client and server data access

While typical apps don't usually have to solve all these problems simultaneously, we need to be able to demonstrate convenient, flexible patterns that do compose well with all the features and are clean enough to put them in the project template.

Solving this nicely likely depends on implementing some other features like #51584

Note for community: Recommendation for .NET 8 developers

As mentioned above, typical apps don't normally have to solve all these problems. It's always been simple to load data from the server with Blazor WebAssembly and that is still the case in .NET 8.

The easiest path is simply to disable WebAssembly prerendering, because then just about all the complexity vanishes. Whenever you used rendermode WebAssembly (e.g., in App.razor), replace it with new WebAssemblyRenderMode(prerender: false).

At that point your UI is just running in the browser and you can make HttpClient calls to the server as normal.

[mrpmorris]

Thanks for adding this!

I would like to propose this is two separate issues.

1. Double-render
2. WASM vs Server-side rendering of data using the same page

I think 1 is a user experience issue, whereas 2 is a developer experience issue - and as such should be dealt with at separate times.

I think it would be easy to solve item 1 without any changes to the Blazor framework by updating the default template to something like the attached. This uses the following approach

1. A new "Contracts" project that contains the DTOs used by the web api, and also an interface for fetching that data, e.g. IWeatherForecastService
2. A class implementing said interface is added to the WASM app and is simply a proxy to make HttpClient calls through to the API server endpoint.
3. The server registers a class that implements said interface by (simulating) fetching data from a database (Task.Delay).
4. The server API endpoint uses that service to fetch data and return it to the client.

This means we can inject IWeatherForcecastService into the /Weather page in order to retrieve the data. When server rendering it will use the server implementation and go straight to the simulated Db, and WASM rendering it will be injected with the proxy class instead and call to the API.

The benefits of this are

1. The I{Weather}Service naming pattern is well-known, and easy to understand for those who've never seen it before.
2. The client's implementation merely acts as a proxy through to the server service (via an API call), similar to good old RPC.
3. The page works on both WASM and Server-Side rendering without modification to the Razor page.
4. When server rendering, the server doesn't have to call itself via HTTP - instead it executes the same code that the API endpoint would have, which is obviously faster.

MyHostedBlazorWasmApp.zip

[EdCharbeneau]

I recently wrote a Blazor Interactive WebAssembly basics article. https://www.telerik.com/blogs/building-interactive-blazor-apps-webassembly

The end product was quite lengthy because I had to explain and provide examples of all the issues that arise when using the new Web App template. From the beginning, a selling point of Blazor is it's "low learning curve" for .NET developers. However, we now have a host of new features that improve the framework, but also increase complexity. A template to deal with some of the complexity and set best practices is desperately needed.

I think @mrpmorris has a good sample, this is a better organized version of what I wrote in my article.

[Hona]

At the moment, the current template doesn't show the intention or reason behind the web app project/client project.

@mrpmorris Has a good suggestion with the contracts project, demonstrating an interface, the double injection using different providers.

An awesome improvement (no idea on the feasibility) would be to make it 'feel' like writing traditional WASM or Server code, but the prerender persistence/auto issues are handled for you (opt in/out?).

The ideal dev ex would be quick to figure out intention & not have to google issues (find out you should disable prerendering, which is a must have for SEO).

I think optimising for the best DevEx of prerender ON & Auto render mode, will fix a lot of issues on the side.

For example, an app I'm playing with using the Blazor Web App paradigm has to write a lot of code to call 1 Web API endpoint, then display that data as is.

Example page here: https://github.com/Hona/TempusHub2/blob/main/UI/src/TempusHub.WebUI/TempusHub.WebUI.Client/Components/Pages/Leaderboards/Map/MapPage.razor

[mrpmorris]

With regards to the double-render, the following code works fine. Note the code to simulate fetching data has been moved into FetchDataAsync for brevity.

public partial class Weather : ComponentBase
{
    private WeatherForecast[]? forecasts;

    [Inject]
    private PersistentComponentState PersistentComponentState { get; set; } = null!;

    protected override async Task OnInitializedAsync()
    {
        PersistentComponentState.RegisterOnPersisting(SaveStateAsync);
        if (!PersistentComponentState.TryTakeFromJson(nameof(forecasts), out forecasts))
        {
            await FetchDataAsync();
        }
    }

    private Task SaveStateAsync()
    {
        PersistentComponentState.PersistAsJson(nameof(forecasts), forecasts);
        return Task.CompletedTask;
    }

    private async Task FetchDataAsync()
    {
        // ...
    }
}

Here are my thoughts for improvement.

The code above is nice and easy mainly because there is only one property to persist. Once there are multiple calling x.TryTakeFromState for each is laborious. I would like to propose being able to write (something like) the following code instead.

public partial class Weather : ComponentBase
{
    public WeatherForecast[]? Forecasts; // Made public
    public int SelectedIndex;
    public string SomeOtherState = "This is serialized too.";

    protected override async Task OnInitializedAsync(bool stateWasDeserialized)
    {
        if (!stateWasDeserialized)
        {
            await FetchDataAsync();
        }
    }
    // ...
}

1. All public fields and properties (with getter + setter) are automatically serialized and deserialized (presumably excluding parameters/cascading values as these will be set by outer components and passed in).
2. Any of those can be excluded from serialization if decorated with [DoNotSerializeState].
3. Lower visibility members can be included in serialized if decorated with [SerializeState].
4. Introduce an overloaded OnInitializedAsync that has a bool parameter indicating whether or not the component state was deserialized, by default this just calls OnInitializedAsync (which can possibly be marked [Obsolete] in V10 and removed in V11?)
5. All components are automatically opt-in unless the coder of the component explicitly marks their component or assembly with [DoNotSerializeState].

I think this gives the easiest experience for new users and also allows more experienced users to tweak more precisely if needed.

1. Automatically deals with serializing state from the server pre-render down to the WASM client to avoid double-rendering.
2. The the user must explicitly write code to not fetch data when deserializing state, so existing code bases will continue to work.
3. The default implementation of the new overloaded OnInitializedAsync can call OnInitializedAsync, so no code breakage.
4. In apps where 99% of pages are accessed only via WASM navigation and not server pre-rendering, it will have no impact at all.

Possible alternative names for this parameter hasPreRenderedState. It would be nice if the meaning could be negated in order to avoid the ! in the if, but I can't think of a good name. Chat-GPT (Cheat-Petey) suggests stateIsUninitialized - which I think works quite well.

if (stateIsUnitialized)
  await FetchDataAsync();

Another benefit of this approach is that it could be retrofitted to .net 8 using a Roslyn Analyzer, the only difference being there would be no override on OnInitializedAsync - the OnInitialized would have to be implemented by Roslyn, determine if there is state to deserialize, and then call a new partial OnInitializedAsync with the new parameter. But I don't know if that's a requirement or not.

[Hona]

@mrpmorris I love that design. I want to leave my thoughts that follow on from your ideas.

I believe for the success of Blazor there should be a lot more magic/convenience by default, and it be suggested by way of the templates.

The basis is using Auto render mode with prerendering on. My experience of using this is its incredibly clunky & beginner unfriendly (e.g. when does something render, what project do I put this in, is this called on the client, or the server, or both (twice?))

The suggested paradigm relies on server first, client side second.

I'd suggest the following structure:

Contoso

• ASP.NET Core host
• Layout, Pages, Components (note, this is the only place to write Razor files)
• Contracts: Server implementation (e.g. call EF Core directly)

Contoso.Contracts

• View Model definitions
• Data access interfaces

Contoso.Client

• Contracts: Clientside implementation (e.g. call an authenticated Web API)

Now, what would this look like?

Contoso/Components/WeatherPage.razor

@page "/weatherforecast"
@inject IWeatherRepository WeatherRepository

<!-- Put a table here -->

@code {
    public WeatherForecast[] Forecasts;

    protected override async Task OnInitializedAsync(bool stateWasDeserialized)
    {
        if (!stateWasDeserialized)
        {
            Forecasts = await WeatherRepository.GetForecastsAsync();
        }
    }
}

Contoso.Contracts/Models/WeatherForecast.cs

public record WeatherForecast(...);

`Contoso.Contracts/Repositories/IWeatherRepository.cs

public interface IWeatherRepository
{
    Task<WeatherForecast[]> GetForecastsAsync();
}

Now the important stuff, showing which is server, which is client implementations.

Contoso/Repositories/WeatherRepository.cs

public class WeatherRepository(AppDbContext DbContext) : IWeatherRepository
{
    public Task<WeatherForecast[]> GetForecastsAsync()
    {
         // Simulating some sort of EF query
         return await DbContext.Forecasts
             .ToListAsync();
    } 
}

Contoso.Client/Repositories/WeatherRepository.cs

public class WeatherRepository(HttpClient Client) : IWeatherRepository
{
    public Task<WeatherForecast[]> GetForecastsAsync()
    {
         // Simulating some sort of EF query
         return await Client.GetFromJsonAsync<WeatherForecast[]>("/api/weatherforecasts");
    } 
}

Now the wireup code

Contoso.Client/Program.cs (I'd prefer something like DependencyInjection.cs or something that shows this is only for wiring up contract interfaces to implementations)

...
builder.Services.AddSingleton<IWeatherRepository, WeatherRepository>();
...

Contoso/Program.cs

...
builder.Services.AddSingleton<IWeatherRepository, WeatherRepository>();
...

I think in this way there could even be the possibility to automatically detect what is server only, client only, where there is only a server implementation of the interface, it can only be on the server.

There was some code omitted obviously, interactivity models I generally ignored, where prerenders/client and server switches are the priority for me.

Further Improvements

• I don't like the full sharding of 3 projects out of the gate, we could move code to be a bit closer
  I do think the sharding & abstractions come at a cost, so I think it needs some balancing.
• I didn't put too much thought in the abstractions naming, e.g. repository/service etc.
• I didn't consider how configured HttpClients could be convenient for consumers

I'd even consider a separate method on ComponentBase, taking this snipped from the previous message:

protected override async Task OnInitializedAsync(bool stateWasDeserialized)
{
    if (!stateWasDeserialized)
    {
        await FetchDataAsync();
    }
}

I think this leads to two separate concerns being thrown into one method.
A fresh load is inside an if, or past a guard clause, then deserialization cleanup/handling is next to it.

I feel there is enough to warrant something like the following (ignoring async overloads):

// Note that this method would be written the same with classic blazor paradigms
protected override async Task OnInitializedAsync()
{
        FetchDataAsync();
}

// Note that this is opt in, if the framework's magic is not correct for specific use cases
protected override void OnDeserialized()
{
    // Do something 
   // Maybe provide parameters mentioning what changed?
}

I think if:

• the default template has 1 project somehow than my suggestions (following a bit more of a code locality structure)
• the pattern is established for data access & reuse between client/server
• a single spot for razor pages/components (my samples would mean you only write that inside the Contoso server project
• beginners are shown the path, and experts are allowed to have control (opt in)

Then, Blazor could be open to wider adoption.

Feedback from the 10 or so different people I've seen try the Blazor Web App paradigm, have all come to the same conclusion as me, where you should just stick with the classic project structures.
The foundation is there for the new methods, but let's make it easy to use.

Keen to hear everyone's thoughts :)