Skip to content

AIFACTORY-FEAT-168: Blazor microfrontend library template: AppShell chrome, a neutral exemplar and a generated-solution gate

Generated from the architecture model

This page is rendered from model/**/*.yaml by tools/docs_model during mkdocs build. Edit the YAML, not this page; hand-written design lives on the linked service, platform and plane pages.

A design artefact, not a tracker

This backlog is generated from model/backlog/ and validated against the architecture model. No work item exists in any tracker, and no item carries a date, an estimate or an assignee (ADR-0029).

Epic Ecosystem component extensions · Increment I3 Studio · State elaborated · Route frontend-developer · Phase before development · Build order 32 of 185 (Templates and libraries)

Before development

Template or library work: every task of this feature changes a template or a shared library the Factory builds on, and it lands before the Factory's own repositories of I3 are developed. The mark travels with every task (tag phase:before-development).

The Studio microfrontends are scaffolded from the microfrontend library template. Its own F11 record logs the gaps left open: the sample chrome is a custom navigation instead of the UIKit AppShell and still uses raw Tailwind colours instead of the cs-* semantic tokens, the sample microfrontends are Identity teaching stubs, the build has no MAX_PATH redirect, and the epic-level acceptance of the template (install, generate every parameter combination, build, run) is still unchecked. Component: Blazor Shell + MFEs + UIKit (extend).

Delivers —
Stubs —
Realizes components: cmp-blazor-shell
adrs: ADR-0007
Requirements —
Depends on AIFACTORY-FEAT-167 Blazor shell template: gateway adapters, filter diagnostics and pinned packages before the Studio
Sources model/components.yaml, ConnectSoft.Blazor.MicrofrontendLibraryTemplate/docs/F11-microfrontend-library.md, ConnectSoft.Blazor.MicrofrontendLibraryTemplate/docs/EPIC-PLANNING.md

AIFACTORY-US-323: Blazor microfrontend library template: the generated shell host renders the UIKit AppShell bound to the shell abstractions, and its chrome uses only the cs-* tokens

enabling · persona asset-maintainer As an asset maintainer, I want the shell host of the microfrontend library template to use the same chrome as the standalone shell template, so that a Studio microfrontend is developed inside the chrome it will be composed into.

The F11 record of the template lists its chrome as a gap: the layout of the core project and its stylesheet are a custom header and navigation, not the UIKit AppShell, and the sample chrome still uses raw Tailwind gray-* and dark: utilities and legacy classes instead of the cs-* semantic tokens; the record leaves the migration as a follow-up. The manual compose matrix of its integration checklist still has two unchecked items: light and dark themes without raw colour regressions, and a mirrored navigation in right-to-left direction. The standalone shell template already renders the AppShell with its regions A to E bound to the shell abstractions. A microfrontend developed in one chrome and composed into another is reviewed twice, so this PBI moves the generated shell host of the library onto the same chrome. The layout of the core project renders the AppShell regions bound to the shell abstractions as the standalone shell template does, with the navigation taken from the microfrontend registry through the navigation filter. The layout and the stylesheet hold no raw gray-* utility, no dark: variant and no legacy class; colour, spacing, type and radius come from the cs-* tokens, so the theme, density and enableRTL parameters of the template switch the chrome through the tokens and the direction attribute. The Gallery sample stays the minimal stub the record describes. The record and the integration checklist mark the two gaps and the two matrix items as closed.

Acceptance criteria

AC1 Given a solution generated from the template, when its shell host renders, then the layout of the core project is the UIKit AppShell with its regions bound to the shell abstractions and its navigation comes from the registry through the navigation filter, as in a shell generated from the standalone shell template (ADR-0007: the modules share a common design system and auth context; model/templates.yaml lists both templates).
AC2 Given the layout and the stylesheet of the core project, when the token test scans them, then it finds no raw gray-* utility, no dark: variant and no legacy class, and a planted raw utility fails the test with the file and the class named (ADR-0007, model/components.yaml names the AppShell chrome as a need of this component).
AC3 Given solutions generated with theme Light and Dark, with each density value and with enableRTL on, when the chrome renders, then theme and density change through the tokens only and the navigation is mirrored in right-to-left direction with no clipped text (ADR-0007, model/template-parameters/connectsoft-blazor-mfe.yaml lists the three parameters).
Traces: adrs ADR-0007
Depends on feature:component-blazor-shell-template-studio, feature:component-uikit-factory-compositions
Sources model/components.yaml, model/templates.yaml, model/template-parameters/connectsoft-blazor-mfe.yaml, docs/architecture/adr/0007-blazor-mfe-studio-frontend.md

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-613 Sample chrome on the UIKit AppShell with cs-* tokens implementation The generated shell host of the library renders the UIKit AppShell regions A to E bound to the shell abstractions, as the standalone shell template does; no raw gray-* utility, dark: variant or legacy class remains in the core layout and its stylesheet; theme, density and direction switch through the tokens; the F11 record and the integration checklist mark the chrome gaps as closed. ConnectSoft.Blazor.MicrofrontendLibraryTemplate
AIFACTORY-TASK-1388 Token scan test and chrome component tests of the core layout fixture The unit test project holds a scan test over the core layout and its stylesheet that fails on a raw gray-* utility, a dark: variant or a legacy class with the file named, and component tests that render the chrome for both themes, the three density values and right-to-left direction. ConnectSoft.Blazor.MicrofrontendLibraryTemplate
AIFACTORY-TASK-1389 Verify the AppShell chrome, the token scan and the theme, density and direction cases verification Generate solutions for the theme, density and direction values and run the tests of AIFACTORY-TASK-1388; the chrome is the AppShell, the scan is clean and fails on a planted utility, which proves AC1 to AC3 of AIFACTORY-US-323 (ADR-0007). ConnectSoft.Blazor.MicrofrontendLibraryTemplate

AIFACTORY-US-324: Blazor microfrontend library template: one neutral exemplar microfrontend replaces the Identity teaching stubs and shows the contract a Studio microfrontend follows

enabling · persona asset-maintainer As an asset maintainer, I want the microfrontend the template generates to be a neutral example of the composition contract, so that a Studio microfrontend starts from a clean pattern and not from identity screens it must delete.

The template generates two sample microfrontends, an Identity administration one and an Identity self-service one, and its F11 record calls their screens teaching stubs. They carry a product domain the Studio does not have, and the integration checklist warns that the embedded samples and the standalone Identity templates follow two different navigation contracts that must not be mixed in one host. The composition contract itself is small and is documented in the record: a static descriptor with the assembly and the navigation items of the microfrontend, each item with an id, a text, a target, an icon, an optional required policy and an order, and one registration method that owns the dependency injection and the authorization policies of the microfrontend and that the shell calls once. A microfrontend references the shell contracts and the shell service abstractions and never the shell services package. This PBI replaces the two Identity stubs in the generated solution by one neutral exemplar microfrontend that carries no product domain. It has a descriptor, two navigation items of which one requires a policy, the registration method, one page that reads the scope and the user from the shell abstractions and one page that shows the loading, empty and error states with the kit components, and component tests for both. The registry, the host wiring, the contract tests and the scaffold test of the template follow the exemplar. Two parameters were meant for the Identity samples and gate nothing: IncludeSampleData is a symbol definition without a use, and UseLocalDb appears only in a conditional whose branches change no generated file; the parameter snapshot of this repository already binds UseLocalDb to false because a microfrontend holds no database. With the samples gone both are removed from the template configuration and its host files, and a scaffold test keeps the rule that every remaining parameter changes at least one generated file. The standalone Identity sample templates are other repositories and stay as they are. The record, the sample notes and the checklist describe the exemplar as the pattern.

Acceptance criteria

AC1 Given a solution generated from the template, when its projects are listed, then it holds one exemplar microfrontend project and no Identity sample project, the exemplar has a descriptor with its assembly and two navigation items and one registration method, and the shell host composes it through the registry (ADR-0007: each module of the Studio is a microfrontend composed into the shell; model/templates.yaml row of connectsoft-blazor-mfe).
AC2 Given the exemplar project, when the architecture tests run, then it references the shell contracts and the shell service abstractions only, a planted reference to the shell services package fails the test, and no type or route of the exemplar names a product domain (ADR-0007, docs/architecture/adr/0007-blazor-mfe-studio-frontend.md).
AC3 Given the generated solution, when its tests run, then the component tests of the two exemplar pages pass, the item that requires a policy is hidden from a user without it, and the contract tests assert the ids, targets and unique orders of the exemplar navigation (ADR-0007, model/components.yaml names the neutral exemplar as a need of this component).
AC4 Given the template configuration after this PBI, when the parameter-effect test generates a solution per value of every parameter, then every parameter changes at least one generated file, UseLocalDb and IncludeSampleData are defined in no configuration or host file of the template, and a planted parameter that gates nothing fails the test by name; the next inventory drops both from model/template-parameters/connectsoft-blazor-mfe.yaml (ADR-0007).
Traces: adrs ADR-0007
Depends on AIFACTORY-US-323
Sources model/components.yaml, model/templates.yaml, model/template-parameters/connectsoft-blazor-mfe.yaml, docs/architecture/adr/0007-blazor-mfe-studio-frontend.md

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-614 Neutral exemplar microfrontend with its descriptor and navigation contribution contract One neutral exemplar microfrontend with its descriptor, its navigation contribution, the {X}Mfe and Add{X}Mfe pair, two pages and component tests shows the contract a Studio microfrontend follows; the exemplar carries no product domain and references the shell contracts and abstractions only. ConnectSoft.Blazor.MicrofrontendLibraryTemplate
AIFACTORY-TASK-1390 Identity teaching stubs removed and the host, registry and tests moved to the exemplar implementation The two Identity sample projects leave the template and the solution; the registry, the host wiring, the contract tests, the coverage tests and the scaffold test that asserted both Identity microfrontends assert the exemplar; the template configuration and the nuspec name no removed project. ConnectSoft.Blazor.MicrofrontendLibraryTemplate
AIFACTORY-TASK-1427 Dead parameters UseLocalDb and IncludeSampleData removed and a parameter-effect test added contract The template configuration, dotnetcli.host.json and ide.host.json of the template no longer define UseLocalDb and IncludeSampleData, and the conditional on UseLocalDb whose branches change nothing is gone; the scaffold test project holds a parameter-effect test that generates a solution per value of every parameter and fails with the parameter named when a parameter changes no generated file; the removal is noted for the next inventory of model/template-parameters/connectsoft-blazor-mfe.yaml. ConnectSoft.Blazor.MicrofrontendLibraryTemplate
AIFACTORY-TASK-1391 F11 record, sample notes and integration checklist describe the exemplar documentation The F11 record, the sample notes of the source folder, the Architecture page and the integration validation checklist of the template describe the exemplar as the composition pattern, drop the embedded Identity routes and keep the note that the standalone Identity templates are separate. ConnectSoft.Blazor.MicrofrontendLibraryTemplate
AIFACTORY-TASK-1392 Verify the exemplar contract, the reference rule and the navigation tests verification Generate a solution, build and test it, plant a reference to the shell services package in the exemplar and plant a parameter that gates nothing; the solution holds the exemplar only, its tests pass, the planted reference fails the architecture test and the planted parameter fails the parameter-effect test, which proves AC1 to AC4 of AIFACTORY-US-324 (ADR-0007). ConnectSoft.Blazor.MicrofrontendLibraryTemplate

AIFACTORY-US-325: Blazor microfrontend library template: a generated solution shortens its intermediate and output roots so that long nested paths build on Windows

enabling · persona asset-maintainer As an asset maintainer, I want a solution generated from the template to build under a long repository path on Windows, so that a Studio repository with long project names does not fail on the path length limit.

The F11 record of the template states that its build properties file is present but holds no redirect of the intermediate output path, unlike the administration microfrontend templates of the SaaS family, which shorten their intermediate and output roots for the Windows path limit; the record leaves the redirect as a follow-up to adopt when a build hits the limit. The repositories of the Factory carry long names, and a solution generated under such a name nests the project name several times inside its intermediate folders, so the Studio is the case the record anticipated. This PBI adopts the redirect. The build properties file of a generated solution sets short roots for the intermediate and the output folders of the source, test and sample projects, in the style the record points at, and the ignore file, the test settings and the pipeline of the generated solution follow the new roots. The redirect changes no assembly name and no package content. A generation under a root path near the limit, with a solution name of the length of a Factory repository name, restores, builds and tests on a Windows agent. The record marks the gap as closed and names the roots.

Acceptance criteria

AC1 Given a solution generated under a deep root path with a name as long as a Factory repository name, when it is restored, built in Release and tested on a Windows agent, then no step fails on the path length limit (ADR-0007; model/components.yaml names the generated-solution gate of this template, which this case joins).
AC2 Given a generated solution with the short roots, when its package content and assembly names are compared with those of a solution built without the redirect, then they are equal, and the ignore file and the pipeline of the generated solution name the new roots (ADR-0007, model/template-parameters/connectsoft-blazor-mfe.yaml gains no parameter by this PBI).
Traces: adrs ADR-0007
Sources model/components.yaml, model/template-parameters/connectsoft-blazor-mfe.yaml, docs/architecture/adr/0007-blazor-mfe-studio-frontend.md

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-1393 Short intermediate and output roots in the build properties of a generated solution implementation The build properties file of a generated solution redirects the intermediate and the output folders of its source, test and sample projects to short roots; the ignore file, the test settings and the pipeline follow them; the F11 record names the roots and marks the gap as closed. ConnectSoft.Blazor.MicrofrontendLibraryTemplate
AIFACTORY-TASK-1394 Verify a deep-path generation on a Windows agent verification Generate a solution with a long name under a deep root on a Windows agent, restore, build and test it, and compare its package content with a build without the redirect; no path error occurs and the content is equal, which proves AC1 and AC2 of AIFACTORY-US-325. ConnectSoft.Blazor.MicrofrontendLibraryTemplate

AIFACTORY-US-326: Blazor microfrontend library template: the packed template is installed, generated across its documented parameters, built, tested and started before the package publishes

evidence · persona asset-maintainer As an asset maintainer, I want every change of the microfrontend library template to be gated by the solutions it generates from the packed candidate, so that a package that would scaffold a solution that does not build or start never reaches the feed.

This PBI is the gate of the feature. The planning page of the template keeps its epic-level acceptance unchecked: the template installs, generates a complete solution that builds, the generated solution runs with its shell and microfrontends, the UI kit works with all three adapters, every parameter is functional and the pipelines are tested. The installer pipeline file of the template only calls the shared installer job of ConnectSoft.AzurePipelines, whose steps pack, validate one instantiation and push in one sequence, and the scaffold test project of the repository covers one composed solution. A gate between pack and push and a refusal of a repeated version are changes of the shared steps: the gate hook and the version guard that AIFACTORY-TASK-1426 of the feature component-base-template-findings adds, the guard being opt-in. This template switches the hook on and defines its cases, which turn the acceptance list into cases of the pipeline. The candidate is packed once and installed. The scaffold tests instantiate it across the parameters that gate generated files: uiKitAdapter in its three values, theme, density, enableRTL, includeTests and EnableHttps, reduced to the pairs of values so that the run stays bounded while every pair is covered, and the deep-path case on a Windows agent. The two dead parameters AIFACTORY-US-324 removes are not part of the matrix, and its parameter-effect test is what proves the line that every parameter is functional. Each output is restored, built in Release and tested; its host is started and the home route and the route of the exemplar are probed; the output is scanned for template placeholders that were not replaced. A case that fails any stage fails the run with the parameter values and the stage named, and the push is not reached. Publication pushes the package to the ConnectSoft feed with a version that is not yet on the feed. The template gains no Factory profile, so no additional profile case is declared. The planning page marks its acceptance by the cases that prove it. This is an evidence PBI: a template feature has no scenario, so the gate names what it proves through traces.adrs and its sources.

Acceptance criteria

AC1 Given a change of the template, when its installer pipeline runs, then the candidate is packed once and installed, the gate hook of the shared installer steps runs the scaffold cases across the pairwise matrix of uiKitAdapter, theme, density, enableRTL, includeTests and EnableHttps and for the deep-path case, and each output is restored, built in Release, tested, started, probed on the home route and the exemplar route and scanned (ADR-0007; model/template-parameters/connectsoft-blazor-mfe.yaml lists the parameters of the matrix).
AC2 Given a case fails any stage, when the pipeline evaluates the run, then the run fails with the parameter values and the stage named, no later stage of that case is reported as passed and the publication stage is not reached; a fixture with a planted failing case proves the refusal (ADR-0007, model/backlog/epics.yaml states the gate as the completion of the epic).
AC3 Given every case is green, when the push step runs, then the package is pushed to the ConnectSoft feed with a version that is not on the feed, the version guard of the shared installer steps refuses a repeated version with the reason, and the planning page of the template marks each line of its epic-level acceptance by the case that proves it, the line on functional parameters by the parameter-effect test of AIFACTORY-US-324 (ADR-0007, docs/architecture/catalogs/templates.md keeps the row of the template).
Traces: adrs ADR-0007
Depends on AIFACTORY-US-323, AIFACTORY-US-324, AIFACTORY-US-325, feature:component-blazor-shell-template-studio, feature:component-base-template-findings
Sources model/components.yaml, model/backlog/epics.yaml, model/template-parameters/connectsoft-blazor-mfe.yaml, docs/architecture/catalogs/templates.md, docs/architecture/adr/0007-blazor-mfe-studio-frontend.md

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-1395 Parameter matrix of the scaffold tests passed to the gate hook of the shared installer steps operations The scaffold test project defines the pairwise matrix of uiKitAdapter, theme, density, enableRTL, includeTests and EnableHttps and the deep-path case, each case restoring, building, testing, starting and probing its output; the installer pipeline file of the template switches on the gate hook of the shared installer steps, delivered by AIFACTORY-TASK-1426 of the feature component-base-template-findings, passes it these cases and sets no allowPackageConflicts; the planning page maps each acceptance line to its case. ConnectSoft.Blazor.MicrofrontendLibraryTemplate
AIFACTORY-TASK-1396 Planted failing case fixture for the gate fixture A pipeline fixture generates one case whose exemplar route is not registered and asserts that the run fails at the probe stage with the parameter values named and that the publication stage is not reached. ConnectSoft.Blazor.MicrofrontendLibraryTemplate
AIFACTORY-TASK-615 Generated-solution gate and MAX_PATH redirect verification One green run and one planted run of the gate: the pipeline installs the packed template, generates the parameter combinations the template documents and the deep-path case, builds, tests and starts each generated solution and fails when any case fails; the planted case stops the run before publication and the green run publishes the package with a verified version, which proves AC1 to AC3 of AIFACTORY-US-326 (ADR-0007). ConnectSoft.Blazor.MicrofrontendLibraryTemplate

AIFACTORY-US-126: Blazor microfrontend library template: AppShell chrome, a neutral exemplar and a generated-solution gate is delivered and proven on a generated solution

enabling · persona asset-maintainer As an asset maintainer, I want Blazor Shell + MFEs + UIKit to carry AppShell chrome, a neutral exemplar and a generated-solution gate, so that it serves Factory Studio and generated product UIs without later rework.

This is the integration PBI of the feature. An asset maintainer packs the microfrontend library template with the AppShell chrome on the cs-* tokens, the neutral exemplar, the short build roots and the aligned pins of the shell family, installs the package and instantiates it across its parameters in the installer pipeline. Every generated solution builds, passes its tests and starts before the package is allowed to publish; a case that fails any stage fails the run and blocks publication. The implementation lives in the earlier PBIs of this file; this PBI proves them together on the solution a Studio microfrontend is developed in. From the published package a solution is generated with the Tokens adapter under a long repository name. Its shell host renders the AppShell with the exemplar in the navigation, the exemplar follows the descriptor pair and references no shell services package, the chrome holds no raw colour utility, and the solution builds on a Windows agent. The feature is done when that solution is generated from a fresh install of the published package. Repository of the feature: ConnectSoft.Blazor.MicrofrontendLibraryTemplate.

Acceptance criteria

AC1 Given the template repository ConnectSoft.Blazor.MicrofrontendLibraryTemplate with the work of this feature, when the template is packed, installed and instantiated in its pipeline, then the generated solution of every case builds and its tests pass before the package publishes with a verified version (ADR-0007, model/components.yaml).
AC2 Given the work of AIFACTORY-TASK-613 (sample chrome on the UIKit AppShell with cs-* tokens) is done, then the generated shell host of the library renders the UIKit AppShell regions bound to the shell abstractions, as the standalone shell template does, no raw gray-* or dark: utility remains in the core layout and its stylesheet, and theme, density and direction switch through the tokens (ADR-0007, model/template-parameters/connectsoft-blazor-mfe.yaml).
AC3 Given the work of AIFACTORY-TASK-614 (neutral exemplar microfrontend with its descriptor and navigation contribution) is done, then the Identity teaching stubs are replaced by one neutral exemplar microfrontend whose descriptor, navigation contribution, descriptor pair and component tests show the contract a Studio microfrontend follows, and the exemplar carries no product domain (ADR-0007, model/templates.yaml).
AC4 Given the work of AIFACTORY-TASK-615 (generated-solution gate and MAX_PATH redirect) is done, then the pipeline installs the packed template, generates the combinations of the parameters that gate generated files, builds and runs each generated solution and fails when any case fails, and a generated solution shortens its intermediate and output roots so that long nested paths build on Windows (ADR-0007, docs/architecture/catalogs/templates.md).
Traces: adrs ADR-0007
Depends on AIFACTORY-US-323, AIFACTORY-US-324, AIFACTORY-US-325, AIFACTORY-US-326
Sources model/components.yaml, model/templates.yaml, model/template-parameters/connectsoft-blazor-mfe.yaml, docs/architecture/catalogs/templates.md

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-1397 Generate a solution from the published package under a long name and start it verification A probe installs the published package, generates a solution with the Tokens adapter under a name of the length of a Factory repository name on a Windows agent, builds and tests it, starts the host and probes the home route and the exemplar route; the run proves AC2 to AC4 of AIFACTORY-US-126 on the published package (ADR-0007). ConnectSoft.Blazor.MicrofrontendLibraryTemplate
AIFACTORY-TASK-675 Verify blazor-mfe-library-template-delivered by running the declared command verification Run dotnet build -c Release and dotnet test -c Release --no-build on the authoring solution and on every generated case after the published package is installed; they pass and prove AC1 to AC4 of AIFACTORY-US-126. ConnectSoft.Blazor.MicrofrontendLibraryTemplate