Migration

This guide takes a site from Osirion.Blazor 3.x to 4.0, and from 4.0 to 4.1. It lists the changes that can break a build or change what a site does, with the code to change. It is for developers who run an existing site; a new site needs none of it.

Every item comes from CHANGELOG.md and was checked against the code at the tags v3.0.1, v4.0.0 and v4.1.0. The full list of 4.0 changes, with more detail on the admin and on custom implementations, is in docs/MIGRATION.md in the repository.

Before you start

• A clean working tree and a build that passes on your current version.
• Both 3.0.1 and 4.x target net9.0 and net10.0, so the upgrade does not change your target framework.
• Read the steps for the features you use and skip the rest. Steps are marked with who must act.

Part 1. From 3.x to 4.0

1. Update the packages

dotnet add package Osirion.Blazor --version 4.1.0

Version 4.1.0 is the current release. If you reference single modules instead of Osirion.Blazor, update each one to the same version.

2. Decide which content is a draft (every site)

A content file without a published key in its front matter is now published. In 3.x it was hidden as a draft. Add the key to every file that must stay hidden:

---
title: "Not ready yet"
published: false
---

3. Review HTML sanitizing (every site that renders content)

Rendered Markdown and ingested content are sanitized with an allow-list. OsirionHtmlRenderer.SanitizeHtml now defaults to true (it was false), which also covers HTML you pass yourself, for example the custom content of a home page. Script, event handler attributes, javascript:, vbscript: and data: URLs, forms, iframes, inline styles, <style>, svg and the name attribute are removed. class, id, role, aria-* and table cell text-align stay.

If content that used to render now looks different, extend the allow-list instead of turning sanitizing off:

using Osirion.Blazor.Core.Extensions;

builder.Services.AddOsirionHtmlSanitizer(options =>
    options.AllowElement("chart", "type", "title", "caption", "colors"));

Set SanitizeHtml="false" only for markup your own code builds. Read Security first.

4. Add antiforgery (sites that use cookie consent)

MapOsirionCookieConsent requires an antiforgery token, which the banner form carries. Call UseAntiforgery after UseAuthentication and UseAuthorization, and before the endpoints. The Blazor Web App template already does. Razor Pages and MVC hosts that render the banner must add it:

app.UseAntiforgery();
app.MapOsirionCookieConsent();

Custom forms that post to the consent endpoint must include <AntiforgeryToken /> and post a local path as returnUrl; any other value redirects to /. UseOsirionCookieConsent no longer writes a Permissions-Policy header: set one yourself if you relied on it.

5. Set the webhook secret (sites that call UseGitHubWebhook)

The webhook verifies X-Hub-Signature-256 against the provider's WebhookSecret and rejects every delivery while no provider has one. Set the secret and use the same value in the webhook settings on GitHub, with content type application/json:

dotnet user-secrets set "Osirion:Cms:Web:GitHub:Site:WebhookSecret" "<long random value>"

A verified delivery that matches no provider now answers 202 instead of 400, and tags and deleted branches no longer refresh content.

6. Add authentication to the admin (sites that map the admin pages)

Every routed admin page requires the authorization policy CmsAdminAuthorization.PolicyName ("Osirion.Cms.Admin"). The default policy lets in any authenticated user. The library adds no authentication scheme, so add one, and replace the policy where anyone can register:

using Microsoft.AspNetCore.Authentication.Cookies;
using Osirion.Blazor.Cms.Admin.Features.Security;

builder.Services.AddAuthentication(CookieAuthenticationDefaults.AuthenticationScheme)
    .AddCookie(options => options.LoginPath = "/account/login");

builder.Services.AddAuthorization(options =>
    options.AddPolicy(CmsAdminAuthorization.PolicyName, policy => policy.RequireRole("Editor")));

var app = builder.Build();

app.UseAuthentication();
app.UseAuthorization();
app.UseAntiforgery();

The configured Osirion:Cms:Admin:Authentication:PersonalAccessToken no longer signs in every visitor of /osirion/login. Rotate it: earlier versions applied it to every visitor and wrote it to their browser storage. Admin services never use a content provider's ApiToken. GitHub sign-in with OAuth now redirects to {BaseUri}osirion/login (it was /osirion/auth/callback, which has no route): register https://<your host>/osirion/login as the callback of your OAuth app, or set Osirion:Cms:Admin:Authentication:GitHubRedirectUri to the address you registered. A site that never maps the admin needs none of this.

7. Move the FileSystem section

The local folder provider reads Osirion:Cms:Web:FileSystem (FileSystemOptions.WebSection). The old section Osirion:Cms:FileSystem:Web is still read when the new one is missing, so nothing breaks, but change it:

{
  "Osirion": {
    "Cms": {
      "Web": {
        "FileSystem": {
          "BasePath": "content",
          "IsDefault": true
        }
      }
    }
  }
}

The provider marked IsDefault is now the default even when you do not call UseOsirionCms; before, the first registered provider won. A folder's _index.md is served at the folder's URL, as the GitHub provider already did: remove _index.md files you do not want published.

8. Fix code that breaks the build or the startup

The changelog also deprecates DomainEntityBase<TId>, CommandDispatcher, StateManager, ErrorHandlingService, CmsAdminStartupService and BaseContentRepository.GenerateMarkdownWithFrontMatter. They still compile. The first five will be removed in the next major release; use GenerateMarkdownWithFrontMatterAsync instead of the last one.

9. Check markup and CSS you depend on

If you wrote CSS or script against Osirion markup, check these:

• OsirionCookieConsent: the form has the class osirion-cookie-consent-form and the buttons sit in a div.osirion-cookie-consent-actions. Target .osirion-cookie-consent-form.
• DocumentPage: the body is a div, not a second main. Update CSS that targeted main.osirion-document-main.
• OsirionFooter section titles are h2, not h3. Inside the layout's footer slot the footer renders a div.
• Menu ids changed from osirion-menu-{orientation} to osirion-menu-{orientation}-{suffix}: set Id if CSS or script targets the old one. Submenus no longer use role="menu".
• ArticlePage tag badges are a.osirion-tag-badge links, not img.osirion-tag-shield; default tag and category URLs are URL-encoded slugs (C# becomes c%23).
• Media queries now use literal breakpoint values; a custom property in a media condition never matched.

10. Check ids, analytics and SEO output

• Stored ids. Content, directory, localization and FileSystem provider ids are now SHA-256 based and stable. They used to change on every restart, so a site that stored them (bookmarks, database rows, cache keys) must look them up again. No data migration is needed.
• Navigation. Configured Osirion:Navigation:Enhanced values now apply when the EnhancedNavigation parameter is not set, so PreserveScrollForSamePageNavigation set to false now scrolls same-page navigations to the top.
• Analytics. An invalid tracker setting stops the app at startup with an OptionsValidationException that names the key. The consent gate (Osirion:Analytics:Consent:RequireConsent) is off by default. Yandex Metrica options bind from Osirion:Analytics:YandexMetrica; the old YandexMetrica key is still read. Matomo and Yandex Metrica add an external script when AutoTrackPageViews is on.
• SEO. SeoMetadataRenderer drops the query string from canonical and og:url addresses (keep chosen parameters with CanonicalQueryParameters), emits viewport and theme-color tags only with EmitMobileMetaTags, and writes generated FAQ data only with EnableGeneratedFaq.
• 404. ArticlePage, DocumentPage and HomePage answer missing content with status 404. On .NET 10 the router's NotFoundPage renders, so set one. The page needs its own route, for example @page "/not-found"; the router throws InvalidOperationException for a type without a Route attribute:

<Router AppAssembly="typeof(Program).Assembly" NotFoundPage="typeof(Pages.NotFound)">
    <Found Context="routeData">
        <RouteView RouteData="routeData" DefaultLayout="typeof(Layout.MainLayout)" />
    </Found>
</Router>

Part 2. From 4.0 to 4.1

The changelog lists no removed members for 4.1.0. Four changes can alter what a site does:

11. Link your app's stylesheet (every site)

OsirionStyles no longer links Osirion.Blazor.Core.bundle.scp.css. Your app's own {App}.styles.css already imports the scoped styles of every referenced package, so 4.0 downloaded that bundle twice. Make sure the head of your App.razor links the app stylesheet; the Blazor template does:

<head>
    <link rel="stylesheet" href="@Assets["MySite.styles.css"]" />
    <HeadOutlet />
</head>

Use the name of your project in place of MySite. Without the link, components lose their own styles.

12. Decide how last-modified dates are set (sites that use the local folder provider)

A file's write time no longer stands in for the last-modified date. Without last_modified in front matter, an item is last modified on its date. A fresh checkout gives every file the time of the checkout, and that time had reached dateModified, article:modified_time and the sitemap's lastmod. Add last_modified to the front matter of files you edit, or turn the old behavior back on where files are edited in place:

{
  "Osirion": {
    "Cms": {
      "Web": {
        "FileSystem": {
          "UseFileWriteTimeAsLastModified": true
        }
      }
    }
  }
}

13. Check the SEO output

• SeoMetadataRenderer now applies AllowAiDiscovery, AllowAiTraining, AllowSearchIndexing, EnableGeoOptimization, EnableAeoOptimization and GenerateMultipleSchemas from SeoMetadataOptions unless the page sets the parameter. Before, the component's own default of true won, so AllowAiTraining: false was ignored. Check the values in your Osirion:Seo section.
• The <title> is no longer cut at 60 characters.
• Structured data no longer carries an author URL guessed from the name. Set AuthorUrl to a page that identifies the author, such as /about, to get one.
• The publisher logo no longer declares a fixed width and height, and the share image is no longer preloaded.

14. Expect focusable code blocks and different list matches

• OsirionHtmlRenderer gives code blocks and tables tabindex="0", so a keyboard user can scroll them. Set FocusableScrollBlocks="false" to turn it off.
• A Category or Tag query matches the name (ignoring case) or the slug exactly. Before, "Dev" also listed "Web Dev", and a category with a hyphen of its own listed nothing at its address.
• In the dark theme, the active navigation item, danger and info messages use lighter tokens (--osirion-nav-active-text, --osirion-status-danger-text, --osirion-status-info-text). If you override these, check your values.

Check that it works

• dotnet build passes with no obsolete warnings from the table in step 8.
• The site starts, and the log has no "Access token is required" or analytics validation errors.
• A draft file with published: false is not listed; a file without the key is.
• The cookie banner accepts a choice and redirects back (it returns 400 without UseAntiforgery).
• Pages look as before: if component styles are missing, revisit step 11.

Next steps

• Security: what sanitizing, antiforgery and the webhook secret protect.
• Troubleshooting: symptoms after an upgrade and their fixes.
• Getting started: the registration and configuration a current site uses.
• Changelog: every change, release by release.