Building UIs
Anarchy.Toolkit.Web.Ui provides a generic UI host: an interactive-server Blazor application that runs without a login, with an opt-in cookie session where users sign in with OAuth client credentials and the UI calls downstream APIs on their behalf. Everything domain-specific (APIs, pages and environment URLs) is supplied by the application. The examples below build an administration UI for a user-management API.
samples/Samples.Ui is a runnable example of the features described in this guide.
What you get
| Piece | Where | What it does |
|---|---|---|
AddToolkitUi / ToolkitUiBuilder |
Ui/Extension/DependencyInjection |
Razor components, interactive server mode, presenters and routing options; AddCookieSession adds the cookie session, cascading auth state and LoginPresenter. |
UseToolkitUi / MapToolkitUi |
Extension/Service/Builder |
Static assets and antiforgery; the login/logout endpoints when the cookie session is on. |
UiWebAppStartupBase<TAppSettingsDiModule, TAppSettings> |
Ui/Composition/Startup |
Thin startup wrapper over the above, plus the toolkit common middlewares; session opt-in through GetUiAuthenticationOptions and add-ons through ConfigureUi. |
UiAuthenticationOptions |
Entity/Ui |
Cookie settings, login/logout/home paths, OAuth Scope, and the Environments a session can target. |
UiRoutingOptions |
Entity/Ui |
Route prefixes and the optional /{environment} link prefix, for hosts served behind an API gateway stage. |
UiEnvironment / IUiEnvironmentCatalog |
Core/Entity/Ui, Core/Service/Ui |
Auth service URL and named downstream API URLs per environment. |
IUiSessionContext |
Core/Service/Ui/Session |
Access token, client name and target environment of the signed-in user. |
UiApiClientBase + AddToolkitUiApiHttpClient |
Infrastructure/Service/Http/Client, Configuration/Extension/Microsoft/DependencyInjection |
Bearer-authenticated JSON/GraphQL calls to the session’s environment; failures raise DownstreamHttpRequestException with a readable body. |
NotificationService, JsonModalState, PaginationState |
Ui/Presentation |
Circuit-scoped notifications and JSON modal, client-side pagination. |
| Components | Ui/Template/Component |
LoginForm, RedirectToLogin, RootRedirect, LogoutRedirect, SessionBadge, NotificationHost, JsonModalHost, JsonViewLink, JsonObjectProperties, ConfirmationModal, TypedConfirmationModal, Pagination, TablePaginationFooter, EnvironmentPill, UiHeadAssets, UiBodyScripts, LoginLayout. |
toolkit-ui.css, toolkit-ui.js |
wwwroot (embedded) |
Styles for the components above, layered on the consumer’s theme stylesheet; scroll-edge shadows for wide tables. |
Wiring a UI
The UI is a core plus opt-in add-ons. The core (AddToolkitUi) needs no login, no environment catalog and no startup base, so it runs on a plain WebApplication:
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddToolkitUi();
var app = builder.Build();
app.UseToolkitUi(); // toolkit + embedded UI static files, antiforgery
app.MapToolkitUi(); // session endpoints only when the cookie session is on
app.MapRazorComponents<App>().AddInteractiveServerRenderMode();
app.Run();
Components such as ThemeToggle, JsonViewLink, JsonModalHost, Pagination and NotificationHost work as they are. The session components (LoginForm, SessionBadge, RootRedirect, RedirectToLogin) and UiApiClientBase need the cookie session add-on:
builder.Services.AddToolkitUi(ui => ui
.UseRouting(new UiRoutingOptions { EnableEnvironmentNamePathPrefix = true })
.AddCookieSession(new UiAuthenticationOptions { Scope = "UserApi:Admin", Environments = [/* ... */] }));
To mount the UI under a sub-path, call UseToolkitUi() inside app.Map("/admin", branch => ...) and set UiRoutingOptions.PathBase = "/admin" (through ui.UseRouting(...)) so links and <base href> resolve under it.
With a session, add UseRouting(), UseAuthentication() and UseAuthorization() before UseToolkitUi().
UiWebAppStartupBase wraps the same pieces for toolkit hosts. The session is off by default; return options from GetUiAuthenticationOptions to opt in, and override ConfigureUi(ToolkitUiBuilder) for further add-ons:
public class UserAdminStartup(IWebHostEnvironment environment, IConfiguration configuration)
: UiWebAppStartupBase<ModuleAppSettings, AppSettings>(environment, configuration)
{
protected override string ApiName => "User Admin";
protected override UiAuthenticationOptions GetUiAuthenticationOptions() => new() {
Scope = "UserApi:Admin",
Environments = [
new UiEnvironment("Development", new Uri("http://localhost:6001/"),
new Dictionary<string, Uri> { ["UserApi"] = new("https://localhost:5005") }),
new UiEnvironment("Testing", new Uri("https://auth.testing.example.com/"),
new Dictionary<string, Uri> { ["UserApi"] = new("https://users.testing.example.com/") }),
]
};
protected override IServiceCollection ConfigureWebCustomServices(IServiceCollection services)
{
base.ConfigureWebCustomServices(services)
.AddToolkitUiApiHttpClient(TimeSpan.FromSeconds(30));
return services.AddScoped<IUserApiClient, UserApiClient>();
}
protected override void ConfigureUiEndpoints(IEndpointRouteBuilder endpoints)
{
endpoints
.MapRazorComponents<App>()
.AddInteractiveServerRenderMode();
}
}
The login (POST /endpoint/auth/login, antiforgery-protected) and logout (GET /endpoint/auth/logout) endpoints are mapped for you. Locally, the login form lets the user select any catalog environment; deployed hosts always use their own environment, so it must be in the catalog.
A downstream client only names the API and the route:
public class UserApiClient(IHttpClientFactory factory, IUiSessionContext session, IUiEnvironmentCatalog catalog, AppTelemetry telemetry)
: UiApiClientBase(factory, session, catalog, telemetry), IUserApiClient
{
public async Task<UserOutput> GetUserAsync(string id) =>
await SendAsync<UserOutput>(HttpMethod.Get, await GetApiBaseUriAsync("UserApi"), BindRoute("users/{id}", ("id", id)));
}
Static web assets outside Development
Blazor’s _framework/blazor.web.js, and the static assets of referenced packages, come from the build’s static web
assets manifest. ASP.NET Core only loads it in Development, so an unpublished build run in Local, Testing or a test
host would answer an empty script and render blank interactive pages. UseToolkitHostUi calls
UseToolkitUiStaticWebAssets() first to load it in every environment; call it yourself before MapStaticAssets() if you
build the pipeline without UseToolkitHostUi. Published applications are unaffected: their assets are in wwwroot.
Pages and layout
Pages belong to the application (routes are compile-time constants), composed from the toolkit components. Add @using Anarchy.Toolkit.Web.Ui.Ui.Template.Component.Session (and .Shared, .Json, .Layout) to the application’s _Imports.razor, and register the toolkit assembly with the router only if you add routable components of your own there.
@* App.razor *@
<head>
<UiHeadAssets Stylesheets='["user-admin.css"]' />
</head>
<body>
<Routes />
<UiBodyScripts />
</body>
@* Routes.razor: <NotAuthorized><RedirectToLogin /></NotAuthorized> *@
@* Pages/Login.razor *@
@page "/ui/login"
@layout LoginLayout
<LoginForm Title="User Admin" LogoPath="logo.png" Subtitle="User management" />
@* Pages/Logout.razor *@
@page "/ui/logout"
<LogoutRedirect />
@* Layout/MainLayout.razor *@
<header class="navbar-shell">
<nav class="navbar">... <SessionBadge /></nav>
<NotificationHost />
</header>
<main class="main-content">@Body</main>
<JsonModalHost />
A paginated table pairs the toolkit’s classes with PaginationState (call Paginate once per change and keep the result):
<div class="users-table table-with-footer">
<div class="table-scroll">
<table class="sticky-edges-table">...</table>
</div>
<TablePaginationFooter State="Presenter.Pagination" OnChanged="Presenter.Refresh" />
</div>
<Pagination State="Presenter.Pagination" OnChanged="Presenter.Refresh" />
In presenters, report failures with notifications.Error(exception); a DownstreamHttpRequestException shows the downstream response body under “More details”.