[Blazor] Accept the blazor.web.js startup options format in blazor.{server|webassembly}.js

[MackinnonBuck]

Problem

When a Blazor app uses blazor.web.js, the options object passed to Blazor.start() has the following format:

Blazor.start({
  ssr: { /* ... */ },
  server: { /* ... */ },
  webAssembly: { /* ... */ },
});

However, when using blazor.server.js or blazor.webassembly.js, runtime-specific options are specified as top-level properties on the options object. So, for example, if you're using blazor.webassembly.js and you attempt to customize the loading of boot resources like this:

Blazor.start({
  webAssembly: {
    loadBootResource: function (/* ... */) {
      // ...
    },
  },
});

...then it will just silently "not work". This could create a pit of failure for customers who see examples in docs using the blazor.web.js options format but are writing a Blazor WebAssembly standalone app, for example.

Solution

We should update blazor.webassembly.js and blazor.server.js to accept the options format used by blazor.web.js.

Summary Comment: #51611 (comment)

[ghost]

Thanks for contacting us.

We're moving this issue to the .NET 9 Planning milestone for future evaluation / consideration. We would like to keep this around to collect more feedback, which can help us with prioritizing this work. We will re-evaluate this issue, during our next planning meeting(s).
If we later determine, that the issue has no community involvement, or it's very rare and low-impact issue, we will close it - so that the team can focus on more important and high impact issues.
To learn more about what to expect next and how this issue will be handled you can read more about our triage process here.

[ghost]

Thanks for contacting us.

We're moving this issue to the .NET 9 Planning milestone for future evaluation / consideration. We would like to keep this around to collect more feedback, which can help us with prioritizing this work. We will re-evaluate this issue, during our next planning meeting(s).
If we later determine, that the issue has no community involvement, or it's very rare and low-impact issue, we will close it - so that the team can focus on more important and high impact issues.
To learn more about what to expect next and how this issue will be handled you can read more about our triage process here.

[mkArtakMSFT]

@MackinnonBuck can you please follow the https://aka.ms/aspnet/processes/help-wanted process to turn this into a help wanted issue? Thanks!

[MackinnonBuck]

Help Wanted

Issue Summary

See #51611 (comment)

Potential Design

We can add one additional property to CircuitStartOptions and WebAssemblyStartOptions each:

export interface CircuitStartOptions {
  // <existing members>

  // Exists for compatibility with WebStartOptions.
  circuit?: CircuitStartOptions;
}

export interface WebAssemblyStartOptions {
  // <existing members>

  // Exists for compatibility with WebStartOptions.
  webAssembly?: WebAssemblyStartOptions;
}

Then we'll update Boot.Server.ts and Boot.WebAssembly.ts to "normalize" the options. Without loss of generality between circuit and WebAssembly options, something like this should work:

async function boot(options?: Partial<WebAssemblyStartOptions>): Promise<void> {
  // ...
  const normalizedOptions = options?.webAssembly ?? options ?? {};
  setWebAssemblyOptions(Promise.resolve(normalizedOptions));
}

This approach always prioritizes the "nested" options over top-level options. I don't anticipate there being any cases where nested and top-level options are specified on the same object, so the simplicity of this approach seems preferable over introducing more complicated option merging semantics.

Code References

CircuitStartOptions.ts
WebAssemblyStartOptions.ts
Boot.Server.ts
Boot.WebAssembly.ts

Additional Notes

• If the change you are going to make will include a public API change in the framework, then the change will need to go through our API Review Process. Please read this process to take any necessary steps, to avoid any potential delays down the road with accepting this change.
• If this is your first contribution to the repo, you may find it useful to learn How to build the repo
• Please note, that the changes will be considered for the vNext version of the framework by default. That is, after the change gets merged in main, it will be available only in the next preview release of the framework and will be shipped in the upcoming major release of the product.

[ghost]

Looks like this issue has been identified as a candidate for community contribution. If you're considering sending a PR for this issue, look for the Summary Comment link in the issue description. That comment has been left by an engineer on our team to help you get started with handling this issue. You can learn more about our Help Wanted process here

[woefulpines]

Hello, I'm starting to get my feet wet in open source development, mind if I try my hand at this issue?

[vladimir-shirmanov]

Hi there,
@MackinnonBuck your link on How to build the repo is broken.
Can you please provide a valid one?

[vladimir-shirmanov]

Hello,

I created a PR that I believe will resolve this issue, can somebody please take a look if it is valid?