TL;DR: This post walks through migrating a Blazor WebAssembly project to FluentUI Blazor server, highlighting key improvements in UI, authentication, and containerization using Azure Container Apps and .NET Aspire.
(👓Version en français ici)
Why Migrate?
The migration to FluentUI Blazor server brought three major benefits:
- 🎨 Modern UI with FluentUI components
- 🔒 Simplified authentication using Azure Container Apps
- 🚀 Better development experience with .NET Aspire
In this post, I'm sharing my journey while migrating a Blazor WebAssembly (WASM) project to a FluentUI Blazor server project. The goal was to use the new FluentUI Blazor components library, take advantage of .NET Aspire and be able to execute the project in a container.
Recently, I've been working on the migration of AzUrlShortener. Upgrading SDKs and packages, improving the security, and changing the architecture of the solution. This post is part of a series of posts where I share a few interesting details, tips, and tricks I learned while working on this project.
AzUrlShortener is an Open source project that consist of simple URL shortener that I built a few years ago. The goal was simple: having a budget friendly solution to share short URL that would be secure, easy to use and where the data would stay mine. Each instance is hosted in Azure and consist of an API (Azure Function), an Blazor WebAssembly website (Azure Static Web App), and Data Storage (Azure Storage table).
This post is part of a series about modernizing the AzUrlShortener project:
Migration Strategy: Fresh Start vs. Refactor
When migrating an existing project, you have two options: Editing the existing project to reshaping it into the new type or creating a new project and copy-pasting pieces of code from the old project to the new one. In this case, I chose to create a new project and copy-paste the code. This way, I could keep the old project as a backup in case something went wrong.
Creating a New Project
Like mentioned earlier I wanted to use the new FluentUI Blazor components library. It's an open-source project that provides a set of components for building web applications using the Fluent Design System. It makes it easy to create beautiful and responsive user interfaces that are consistent. To create a new project we can use the available template.
dotnet new fluentblazor -n Cloud5mins.ShortenerTools.TinyBlazorAdmin
Dark Mode & Theming Support 🌙
The one thing I do to all my FluentUI Blazor projects is to add a settings page. This page allows the user to change the theme and color of the application. I should do a template to save time, but until then here the required code to add the settings page.
Settings.razor
Let's start by creating that new page called Settings.razor. With two selects, one for the theme (dark or light) and one for the accent color.
@page "/settings"
@using Microsoft.FluentUI.AspNetCore.Components.Extensions
@rendermode InteractiveServer
<FluentDesignTheme @bind-Mode="@Mode"
@bind-OfficeColor="@OfficeColor"
StorageName="theme" />
<h3>Settings</h3>
<div>
<FluentStack Orientation="Orientation.Vertical">
<FluentSelect Label="Theme" Width="150px"
Items="@(Enum.GetValues<DesignThemeModes>())"
@bind-SelectedOption="@Mode" />
<FluentSelect Label="Color"
Items="@(Enum.GetValues<OfficeColor>().Select(i => (OfficeColor?)i))"
Height="200px" Width="250px" @bind-SelectedOption="@OfficeColor">
<OptionTemplate>
<FluentStack>
<FluentIcon Value="@(new Icons.Filled.Size20.RectangleLandscape())" Color="Color.Custom"
CustomColor="@(@context.ToAttributeValue() != "default" ? context.ToAttributeValue() : "#036ac4" )" />
<FluentLabel>@context</FluentLabel>
</FluentStack>
</OptionTemplate>
</FluentSelect>
</FluentStack>
</div>
@code {
public DesignThemeModes Mode { get; set; }
public OfficeColor? OfficeColor { get; set; }
}
App.razor
In the App it self, we need to some JavaScript and the loading theme component. Just after the </body> tag, we need to add the following code:
<!-- Set the default theme -->
<script src="_content/Microsoft.FluentUI.AspNetCore.Components/js/loading-theme.js" type="text/javascript"></script>
<loading-theme storage-name="theme"></loading-theme>
Imports.razor
I noticed some warning in the code about missing using directives. To fix that, find the line that reference to Components.Icons in the _Imports.razor and change it by the following. The Icons alias should resolve the problem.
@using Icons = Microsoft.FluentUI.AspNetCore.Components.Icons
MainLayout.razor
The main layout is our base page by default. We need to add Mode and OfficeColor to make the accessible to the entire application.
@code {
public DesignThemeModes Mode { get; set; }
public OfficeColor? OfficeColor { get; set; }
}
NavMenu.razor
The only thing left is to be able to easily access this new page. This can be done simply by adding an option in the navigation menu.
<FluentNavLink Href="/settings" Match="NavLinkMatch.All" Icon="@(new Icons.Regular.Size20.TextBulletListSquareSettings())">Settings</FluentNavLink>
Test it
And voilà! You should now have a settings page that allows you to change the theme and color of the application. This is all great and it's not really related to the migration, but it's a nice addition to have. Dark mode for the win!
The migration
The migration itself had many little pieces, but wasn't that complex. The project is part of a .NET Aspire solution, so I added the project to the solution dotnet sln add ./Cloud5mins.ShortenerTools.TinyBlazorAdmin. Then added the references to Cloud5mins.ShortenerTools.Core (the class library with all the model, and services) and the ServiceDefault project that was generated when we added Aspire to the solution.
The next logical step was to add our Blazor project the the orchestrator with those lines in the Program.cs of the AppHost project.
builder.AddProject<Projects.Cloud5mins_ShortenerTools_TinyBlazorAdmin>("admin")
.WithExternalHttpEndpoints()
.WithReference(manAPI);
This will make sure the TinyBlazorAdmin project starts with a reference to the API and have accessible endpoints. Without the .WithExternalHttpEndpoints() the project wouldn't be accessible once deployed to Azure.
To use the capability of .NET Aspire to orchestrate the different projects, we need to replace our previous HttpClient creation in the Program.cs of the TinyBlazorAdmin by the following code:
builder.Services.AddHttpClient<UrlManagerClient>(client =>
{
client.BaseAddress = new Uri("https+http://api");
});
This will make sure the UrlManagerClient receives an httpClient using the correct address and port when calling the API. Let's have a look at the UrlManagerClient class and one of the method that will be used to call the API.
public class UrlManagerClient(HttpClient httpClient)
{
public async Task<IQueryable<ShortUrlEntity>?> GetUrls()
{
IQueryable<ShortUrlEntity> urlList = null;
try{
using var response = await httpClient.GetAsync("/api/UrlList");
if(response.IsSuccessStatusCode){
var urls = await response.Content.ReadFromJsonAsync<ListResponse>();
urlList = urls!.UrlList.AsQueryable<ShortUrlEntity>();
}
}
catch(Exception ex){
Console.WriteLine(ex.Message);
}
return urlList;
}
// ...
}
As the code shows the httpClient is injected in the constructor and used to call the API. The GetUrls method is a simple GET request that returns a list of ShortUrlEntity. The API is the one created in a previous post: How to use Azure Storage Table with .NET Aspire and a Minimal API, and all the classes are part of the Cloud5mins.ShortenerTools.Core project.
The URL Grid
Part of the migration was also to replace the Syncfusion grid by the new FluentUI Blazor Grid. Not that Syncfusion controls are not great, quite the contrary, but because the AzUrlShortener project has moved to a different owner, I think it would be better to use components that required no licenses.
For this initial iteration, the Syncfusion grid will be replace by the FluentUI Blazor Grid. In a future iteration the Syncfusion Charts component will also be replace. Thank you Syncfusion for the community license used in this project.
The code of UrlManager.razor changed quite a lot as the to grid were a bit different in there naming and usage. The sorting required a bit more code as the column name are not the same as the property name. To provide an example the "Vanity" column is in fact the RowKey property of the ShortUrlEntity class. To be able to sort the column, we need to create a GridSort object that will be used in the TemplateColumn definition.
Definition of the column in the grid:
<TemplateColumn Title="Vanity" Width="150px" Sortable="true" SortBy="@sortByVanities">
<FluentAnchor Href="@context!.ShortUrl" Target="_blank" Aearance="Appearance.Hypeext">@context!.RowKey</FluentAnchor>
</TemplateColumn>
Definition of the GridSort object:
GridSort<ShortUrlEntity> sortByVanities = GridSort<ShortUrlEntity>.ByAscending(p => p.RowKey);
One big improvement that could be done in the future would be to use the virtual grid. The virtual grid is a great way to improve the performance of the grid when dealing with large amount of data as it only loads the data that is visible on the screen. I show how to use the virtual grid in a previous post: How use a Blazor QuickGrid with GraphQL.
Removing the fake popup div
One of the FluentUI Blazor component is the FluentUIDialogue. This component is used to display a popup window, and will help us keeping the code more structure and clean. Instead of having <div> in the code, we can typed <FluentUIDialog> and it will be rendered as a popup.
var dialog = await DialogService.ShowDialogAsync<NewUrlDialog>(shortUrlRequest, new DialogParameters()
{
Title = "Create a new Short Url",
PreventDismissOnOverlayClick = true,
PreventScroll = true
});
Replacing the Authentication
Instead of having to implementing the authentication in the Blazor project, we will be using the a feature of Azure Container Apps that required no code changes! You don't need to change a single line of code to secure your application deployed on Azure Container Apps (ACA)! Instead, your application is automatically protected simply by enabling the authentication feature, called EasyAuth.
Once the solution is deployed to Azure the TinyBlazorAdmin will be installed in a container app named "admin". To secured it, navigate to the Azure Portal, and select the Container App you want to secure. In this case, it will be the "admin" container app. From the left menu, select Authentication and click Add identity provider.
You can choose between multiple providers, but let's use Microsoft since it's deployed in Azure and you are already logged in. Once Microsoft is chosen, you will see many configuration options. Select the recommended client secret expiration (e.g., 180 days). You can keep all the other default settings. Click Add. After a few seconds, you should see a notification in the top right corner that the identity provider was added successfully.
Voila! Your app now has authentication. Next time you navigate to the app, you will be prompted to log in with your Microsoft account. Notice that your entire app is protected. No page is accessible without authentication.
Conclusion
The migration from Blazor WebAssembly to FluentUI Blazor Server has been a successful journey that brought several meaningful improvements to the project:
- Enhanced user interface with modern FluentUI components
- Cleaner, more maintainable code structure
- Simplified authentication using Azure Container Apps' EasyAuth
- Improved local development experience with .NET Aspire orchestration
The end result is a modern, containerized application that's both easier to maintain and more pleasant to use. The addition of dark mode support and theming capabilities are great improvements to the user experience.
Want to Learn more?
To learn more about Azure Container Apps I strongly suggest this repository:
Getting Started .NET on Azure Container Apps, it contains many step-by-step tutorials (
with videos) to learn how to use Azure Container Apps with .NET.
Have questions about the migration process or want to share your own experiences with FluentUI Blazor? Feel free to reach out to me on @fboucheros.bsky.social or open an issue on the AzUrlShortener GitHub repository. I'd love to hear your thoughts!
References
