Install Osirion.Blazor

This guide adds Osirion.Blazor to a Blazor Web App you already have: the packages, the service registration, the stylesheet links and the choice of CSS framework. It is for developers who want to control each step. To start a new site from a template instead, use Getting started.

Before you start

• The .NET 9 or .NET 10 SDK. Every library package targets net9.0 and net10.0.
• A Blazor Web App. dotnet new blazor -n MySite creates one. Osirion's content and layout components render with static server-side rendering, so no interactive render mode is needed.
• This guide is written for Osirion.Blazor 4.1.0.

1. Choose the packages

Install Osirion.Blazor unless you know you need less. It references the Core, Cms, Analytics, Navigation and Theming packages and adds the AddOsirion registration method and OsirionSiteLayout.

Osirion.Blazor.Cms.Core, .Application, .Domain and .Infrastructure are internal layers of the content modules. They are restored for you; you do not reference them. With single modules instead of the meta-package you register each module with its own method (AddOsirionTheming, AddOsirionContent, AddOsirionNavigation, AddOsirionAnalytics), because AddOsirion ships only in Osirion.Blazor. AddOsirionContent registers the script loader that some components use, but AddOsirionTheming does not, so a site that references Osirion.Blazor.Theming alone also calls AddJSComponents(), as the Theming page shows. See the package pages for each module.

2. Add the package

From the project folder:

dotnet add package Osirion.Blazor

To take a single module, name it instead, for example dotnet add package Osirion.Blazor.Theming.

3. Register the services

In Program.cs, add the using and one line after AddRazorComponents():

using Osirion.Blazor.Extensions;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorComponents();
builder.Services.AddOsirion(builder.Configuration);

AddOsirion(IConfiguration) always registers the same defaults: enhanced navigation and scroll to top, theming with no CSS framework, the HTML sanitizer that cleans rendered Markdown, and the script loader (AddJSComponents) that some components use for their own small scripts. You do not call AddJSComponents yourself.

It then reads the Osirion section of your configuration and configures a module only when its section exists:

The configuration guide covers each key. To register in code instead of configuration, use the overload that takes a builder:

using Osirion.Blazor.Components;
using Osirion.Blazor.Extensions;

builder.Services.AddOsirion(osirion => osirion
    .UseTheming(theming => theming.UseFramework(CssFramework.Bootstrap))
    .UseSite(site => site.Name = "My site"));

This overload does not read the Osirion section; you set each value in the delegate. Use one of the two overloads, not both.

4. Link the stylesheets and scripts

A site references three things. Everything else Osirion needs, it loads itself.

1. The app's scoped style bundle, {AssemblyName}.styles.css. It imports the scoped styles of every referenced Osirion package. In Components/App.razor, with MySite as the assembly name:

   <!DOCTYPE html>
   <html lang="en">
   <head>
       <meta charset="utf-8" />
       <meta name="viewport" content="width=device-width, initial-scale=1.0" />
       <base href="/" />
       <link rel="stylesheet" href="@Assets["MySite.styles.css"]" />
       <HeadOutlet />
   </head>
   <body>
       <Routes />
       <script src="@Assets["_framework/blazor.web.js"]"></script>
   </body>
   </html>
   

2. OsirionStyles, rendered once in your main layout. It links Osirion's stylesheets and, for the configured CSS framework, the adapter that maps the framework's colors onto Osirion's. Add it to Components/Layout/MainLayout.razor:

   @inherits LayoutComponentBase
   @using Osirion.Blazor.Theming.Components
   
   <main>
       @Body
   </main>
   
   <OsirionStyles />
   

   If you use OsirionSiteLayout as the default layout, as the templates do, it already renders OsirionStyles.

3. The Blazor script, _framework/blazor.web.js, which the Blazor Web App template already links.

OsirionStyles loads its own script (osirion-styles.js) through the script loader, so you reference no Osirion JavaScript by hand. Its parameters are on the OsirionStyles page.

5. Choose a CSS framework

Osirion has its own design system and works without a CSS framework. If your app already uses one, tell Osirion so its colors and dark mode follow the framework:

Set it in appsettings.json:

{
  "Osirion": {
    "Theming": {
      "Framework": "Bootstrap"
    }
  }
}

Osirion does not load the framework itself. Reference Bootstrap, Fluent UI, MudBlazor or Radzen the way that framework documents. The Theming page lists the adapters and the other theming options.

Check that it works

Build and run:

dotnet build
dotnet run

Open any page and view its source. You should see a <link> to _content/Osirion.Blazor.Core/css/index.min.css, one to _content/Osirion.Blazor.Theming/css/index.min.css, and one to your style bundle, which @Assets writes with a fingerprint, for example MySite.0uxv3q46bu.styles.css. In the browser's network tab each loads with status 200.

If the page has no Osirion styling, check the network tab:

• The style bundle answers 404, or the page has no link to it: the name in App.razor does not match your project's assembly name.
• No index.min.css request: <OsirionStyles /> is not in a layout that the page uses.
• A framework's colors are missing: the framework itself is not referenced, or Osirion:Theming:Framework names a different one.

Next steps

• Configuration: the Osirion section and everything under it.
• Content providers: read Markdown from a folder or a GitHub repository.
• Getting started: list and article pages for a blog.
• OsirionStyles and Theming: stylesheets, palettes and dark mode.