Piral.Blazor ·

All .NET things to make <a href="https://blazor.net" rel="nofollow"><img src="https://devblogs.microsoft.com/aspnet/wp-content/uploads/sites/16/2019/04/BrandBlazor_nohalo_1000x.png" height="10"> Blazor</a> work seamlessly in microfrontends using <a href="https://piral.io" rel="nofollow"> <img src="https://piral.io/logo-simple.f8667084.png" height="10">  Piral</a>.

This is the branch for Blazor 8.0 with .NET 8.0. If you want to switch to Blazor with the older .NET Core 3.2, please refer to the blazor-3.2, blazor-5.0, blazor-6.0, orblazor-7.0 branch. For the most recent version see the blazor-10.0 or the blazor-9.0 branch.

Getting Started

You'll also find some information in the piral-blazor package.

Creating a Blazor Pilet

We recommend that you watch the video on scaffolding from the standard VS template before you go over the details below.

In general, to create a Blazor pilet using Piral.Blazor, two approaches can be used:

1. From Scratch

In this case, it is highly recommended to use our template. More information and installation instructions can be found in Piral.Blazor.Template.

2. Transforming an Existing Application

In this case, follow these steps:

1. Add a PiralInstance property to your .csproj file (The Piral instance name should be the name of the Piral instance you want to use, as it is published on npm.)

   <PropertyGroup>
       <TargetFramework>net8.0</TargetFramework>
       <PiralInstance>my-piral-instance</PiralInstance>
   </PropertyGroup>
   

   (You can optionally also specify an NpmRegistry property. The default for this is set to https://registry.npmjs.org/)

2. Install the Piral.Blazor.Tools and Piral.Blazor.Utils packages, make sure they both have a version number of format 8.0.x

3. Remove the Microsoft.AspNetCore.Components.WebAssembly.DevServer package and install the Piral.Blazor.DevServer package (using the same version as the packages from (2))

4. Rename Program.cs to Module.cs, and make sure to make the Main method an empty method.

5. Build the project. The first time you do this, this can take some time as it will fully scaffold the pilet.

If you run the solution using F5 the Piral.Blazor.DevServer will start the Piral CLI under the hood. This allows you to not only use .NET Hot-Reload, but also replace the pilets on demand.

Usage

Build Configuration

The *.csproj file of your pilet offers you some configuration steps to actually tailor the build to your needs.

Here is a minimal example configuration:

<Project Sdk="Microsoft.NET.Sdk.BlazorWebAssembly">

  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <PiralInstance>../../app-shell/dist/emulator/app-shell-1.0.0.tgz</PiralInstance>
  </PropertyGroup>

  <!-- ... -->
</Project>

This one gets the app shell from a local directory. Realistically, you'd have your app shell on a registry. In case of the default registry it could look like

<Project Sdk="Microsoft.NET.Sdk.BlazorWebAssembly">

  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <PiralInstance>@mycompany/app-shell</PiralInstance>
  </PropertyGroup>

  <!-- ... -->
</Project>

but realistically you'd publish the app shell to a private registry on a different URL. In such scenarios you'd also make use of the NpmRegistry setting:

<Project Sdk="Microsoft.NET.Sdk.BlazorWebAssembly">

  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <PiralInstance>@mycompany/app-shell</PiralInstance>
    <NpmRegistry>https://registry.mycompany.com/</NpmRegistry>
  </PropertyGroup>

  <!-- ... -->
</Project>

Besides these two options (required PiralInstance and optional NpmRegistry) the following settings exist:

• Version: Sets the version of the pilet. This is a/the standard project property.
• PiralInstance: Sets the name (or local path) of the app shell.
• NpmRegistry: Sets the URL of the npm registry to use. Will be used for getting npm dependencies of the app shell (and the app shell itself).
• Bundler: Sets the name of the bundler to use. By default this is esbuild. The list of all available bundlers can be found in the Piral documentation.
• ProjectsWithStaticFiles: Sets the names of the projects that contain static files, which require to be copied to the output directory. Separate the names of these projects by semicolons.
• Monorepo: Sets the behavior of the scaffolding to a monorepo mode. The value must be enable to switch this on.
• PiralCliVersion: Determines the version of the piral-cli tooling to use. By default this is latest.
• PiralBundlerVersion: Determines the version of the piral-cli-<bundler> to use. By default, this is the same as the value of the PiralCliVersion.
• OutputFolder: Sets the temporary output folder for the generated pilet (default: ..\piral~).
• ConfigFolder: Sets the folder where the config files are stored (default: empty, i.e., current project folder).
• MocksFolder: Sets the folder where the Kras mock files are stored (default: .\mocks).
• PiletKind: Sets the pilet kind (values: global, local; default: local). Global pilets will always be published without trimming.
• PiletPriority: Sets the optional priority of the pilet when loading (any representable positive number). DLLs of Blazor pilets with higher numbers will always be loaded before the current DLLs (default: none).
• PublishFeedUrl: Sets the URL to be used for publishing the pilet. If this is left free then using "Publish" in Visual Studio will not trigger a publish of the pilet.
• PublishFeedApiKey: Sets the API Key to be used when publishing the pilet. If this is left free then the interactive upload is used, which will open a web browser for logging into the feed service.

A more extensive example:

<Project Sdk="Microsoft.NET.Sdk.BlazorWebAssembly">

  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <Version>1.2.3</Version>
    <PiralInstance>@mycompany/app-shell</PiralInstance>
    <PiralCliVersion>next</PiralCliVersion>
    <PiralBundlerVersion>1.1.0</PiralBundlerVersion>
    <NpmRegistry>https://registry.mycompany.com/</NpmRegistry>
    <Bundler>esbuild</Bundler>
    <Monorepo>disable</Monorepo>
    <ProjectsWithStaticFiles>
      designsystem;
      someotherproject;
      thirdproj
    </ProjectsWithStaticFiles>
    <PiletPriority>999</PiletPriority>
  </PropertyGroup>

  <!-- ... -->
</Project>

While pilets that define PiletKind to be global only have shared dependencies, the default for local pilets is to have integrated dependencies. If certain dependencies of local pilets should also be loaded into the global context (effectively sharing the dependency between all pilets - independent of the version) then you need to put those dependencies into a dedicated ItemGroup using the Label shared:

<Project Sdk="Microsoft.NET.Sdk.BlazorWebAssembly">

  <!-- ... -->

  <ItemGroup Label="shared">
    <PackageReference Include="Autofac.Extensions.DependencyInjection" Version="8.0.0" />
  </ItemGroup>

  <ItemGroup>
    <!-- ... -->
    <PackageReference Include="Microsoft.AspNetCore.Components.WebAssembly" Version="8.0.24" />
    <PackageReference Include="Microsoft.AspNetCore.Components.WebAssembly.DevServer" Version="8.0.24" PrivateAssets="all" />
  </ItemGroup>

</Project>

Pages

A standard page in Blazor, using the @page directive, will work as expected, and will be automatically registered on the pilet API.

Extensions

To register an extension, the PiralExtension attribute can be used. You will also have to provide the extension slot name that defines where the extension should be rendered. The component can even be registered into multiple slots using multiple attributes.

//counter.razor

@attribute [PiralExtension("my-counter-slot")]
@attribute [PiralExtension("another-extension-slot")]

<h1>Counter</h1>

<p>Current count: @currentCount</p>

<button @onclick="IncrementCount">Click me</button>

@code {
    int currentCount = 0;

    void IncrementCount()
    {
        currentCount++;
    }
}

To use an extension within a Blazor component, the <Extension> component can be used.

<Extension Name="my-counter-slot"></Extension>

Components, Tiles, Menu Items, and Others

To register a Blazor component for use in the pilet API, the `PiralC