AppSurface Search
Section API Reference
API Reference Language: C# Component: Theming Audience: developer

Theming

Type

IAppSurfaceThemeDocumentProvider

Source

Provides the immutable Web document for the configured default AppSurface theme.

Method

GetDocument

AppSurfaceThemeDocument GetDocument()
Source

Gets the current safe document snapshot.

Returns

A renderable document, or AppSurfaceThemeDocument.Empty when it is unsafe.

Type

AppSurfaceThemeDocumentProvider

Source

Builds and retains the immutable Web document from the neutral default-theme resolver.

Type

AppSurfaceThemeCspNonce

Source

Provides the documented request-item key for a host-generated AppSurface theme CSP nonce.

Method

Get

string? Get(HttpContext httpContext)
Source

Gets the host-generated nonce from the current request, when one is available.

Parameters

  • httpContext
    Current request context.

Returns

The nonce supplied by the host, or null when the host does not use a nonce-based CSP.

Type

AppSurfaceThemeSelectionDocumentCache

Source

Builds immutable Web documents for every pair in the sealed neutral registry.

Remarks

The cache is keyed only by registered pair id because its values contain package-owned CSS and HTML derived from immutable pairs. A pair id is never a host response-cache key: applications remain responsible for partitioning or disabling any cache that contains tenant-specific content, authorization, or other host-owned state.

Method

TryGet

bool TryGet(AppSurfaceThemeId themeId, out AppSurfaceThemeDocument document)
Source

Attempts to get the prevalidated document for a selected registered pair.

Property

DefaultDocument

AppSurfaceThemeDocument DefaultDocument { get; } Source

Gets the ordinary configured-default document used when a policy has no selection.

Type

AppSurfaceThemeSelectionStartupValidator

Source

Rejects a document-provider replacement that bypasses the selection adapter.

Method

Configure

Action<IApplicationBuilder> Configure(Action<IApplicationBuilder> next)
Source

Validates the resolved document-provider contract after host pipeline composition.

Method

Validate

void Validate()
Source

Validates that no later registration replaced the opt-in selection provider.

Type

AppSurfaceThemePreferenceRegistrationMarker

Source

Marks the browser-preference adapter so conflicting registrations fail predictably.

Type

AppSurfaceThemeSelectionRegistrationMarker

Source

Marks the selection adapter so duplicate registration fails predictably.

Type

AppSurfaceThemeSelectionRegistrationState

Source

Retains the mutable registration collection until startup can validate its final selection contract.

Method

ValidatePolicyLifetime

void ValidatePolicyLifetime()
Source

Rejects a later policy registration that changes the effective service lifetime.

Method

ValidateNeutralServiceLifetimes

void ValidateNeutralServiceLifetimes()
Source

Rejects a later neutral-service registration that violates the cache lifetime contract.

Method

ValidateDocumentProviderRegistration

void ValidateDocumentProviderRegistration()
Source

Rejects a later document-provider registration that violates the scoped selection contract.

Type

AppSurfaceThemePreferenceDocumentProvider

Source

Provides a cached System-first document for browser-local theme preferences.

Remarks

The neutral resolver is evaluated exactly once during construction. The resulting document is cached for every request and is empty when the resolved pair cannot safely be serialized. This provider does not inspect HTTP state or browser storage; the deterministic bootstrap performs browser-local selection after rendering.

Method

GetDocument

AppSurfaceThemeDocument GetDocument()
Source

Gets the cached document without re-resolving the configured theme pair.

Returns

The cached renderable document, or an empty document when the resolved pair was unsafe.

Type

AppSurfaceThemeSelectionDocumentProvider

Source

Provides one host-selected, prevalidated theme document for a Web request scope.

Type

AppSurfaceThemeDocument

Source

Represents the deterministic HTML fragments required to apply one AppSurface theme resolution.

Remarks

The document contains no request-specific values. In particular, HeadContent never contains a CSP nonce; the live head TagHelper adds one only to its inline style element. Only the package serializer can create a renderable instance, so adapters cannot accidentally bypass the validated neutral-theme boundary.

Property

RootAttributes

string RootAttributes { get; } Source

Gets serialized attributes placed on the theme root.

Property

RootThemeId

string RootThemeId { get; } Source

Gets the theme identifier for the root metadata.

Property

RootThemeMode

string RootThemeMode { get; } Source

Gets the rendered theme mode for the root metadata.

Property

RootSchemaVersion

string RootSchemaVersion { get; } Source

Gets the rendered payload schema version for the root metadata.

Property

RootStyle

string RootStyle { get; } Source

Gets the safe color-scheme declaration for the theme root.

Property

HeadContent

string HeadContent { get; } Source

Gets serialized head metadata and critical CSS without a nonce.

Property

Empty

AppSurfaceThemeDocument Empty { get; } Source

Gets an empty document used when a resolver cannot produce a safe renderable snapshot.

Property

IsRenderable

bool IsRenderable { get; } Source

Gets a value indicating whether the document contains renderable theme fragments.

Type

IAppSurfaceWebThemeSelectionPolicy

Source

Selects one registered AppSurface theme pair from already-authorized host context.

Remarks

Implement this scoped policy in the Web host when the rendered pair depends on application-owned request context, such as an authorized tenant. The policy is a presentation seam only: it does not establish tenancy, authenticate callers, authorize access, read a cache, or validate a theme identifier supplied by untrusted input.

Return false when the host intentionally wants the configured default pair. Return true only with a registered pair identifier. The Web adapter validates that result against the sealed neutral registry before rendering; an empty or unknown id fails closed. A host that wants a missing or unauthorized context to fail owns that decision before this policy returns.

Method

TrySelect

bool TrySelect(out AppSurfaceThemeId themeId)
Source

Attempts to select a registered theme pair for the current host context.

Parameters

  • themeId
    The selected registered pair when this method returns true ; otherwise ignored.

Returns

true to render themeId , or false to render the configured default pair.

Type

AppSurfaceThemeDocumentSerializer

Source

Serializes validated neutral theme resolutions into deterministic Web document fragments.

Method

Serialize

AppSurfaceThemeDocument Serialize(AppSurfaceThemeResolution resolution)
Source

Creates a deterministic, nonce-free document for a neutral theme resolution.

Parameters

  • resolution
    The sealed neutral theme resolution.

Returns

A renderable document, or AppSurfaceThemeDocument.Empty when the snapshot is unsafe.

Method

SerializePreference

AppSurfaceThemeDocument SerializePreference(AppSurfaceThemeResolution resolution)
Source

Creates the System-first document used by the browser-local preference enhancement.

Parameters

  • resolution
    The configured theme-pair resolution whose Light and Dark branches are emitted.

Returns

A document with System, Light, and Dark selectors, or AppSurfaceThemeDocument.Empty when the resolution is unsafe to render.

Remarks

This method deliberately replaces the configured startup mode with System while retaining the same Light and Dark pair. The browser bootstrap can then select an explicit branch without changing the URL or duplicating the HTML document. Safety validation is repeated before serialization so an invalid resolution fails closed instead of emitting partially trusted markup.

Method

TrySerialize

bool TrySerialize(AppSurfaceThemeResolution? resolution, out AppSurfaceThemeDocument document)
Source

Attempts to create a deterministic document from a neutral theme resolution.

Parameters

  • resolution
    The sealed neutral theme resolution.
  • document
    The renderable document when the snapshot is safe.

Returns

true when all values are safe to emit; otherwise false .

Method

SerializeHeadContent

string SerializeHeadContent(AppSurfaceThemeDocument document, string? nonce = null)
Source

Adds an encoded nonce to the live inline style in a previously serialized head fragment.

Parameters

  • document
    The nonce-free document.
  • nonce
    The CSP nonce to apply to the inline style, if present.

Returns

Head content with the nonce applied only to the inline style element.

Type

AppSurfaceThemePreferenceOptions

Source

Configures the browser-local System/Light/Dark preference enhancement for Web theme documents.

Remarks

The enhancement stores only an explicit Light or Dark selection in browser local storage for the current origin; selecting System removes that value and returns to the operating-system preference. It neither reads nor writes cookies, server-side preference state, or additional document URLs.

Method

Snapshot

AppSurfaceThemePreferenceOptions Snapshot()
Source

Validates and copies this configuration for service registration.

Returns

A validated snapshot detached from the caller's mutable options instance.

Exceptions

  • ArgumentException
    StorageKey is blank, unsafe for an HTML data attribute, or longer than 64 characters.
Property

StorageKey

string StorageKey { get; set; } Source

Gets or sets the origin-scoped local-storage key used for explicit Light or Dark selection.

Remarks

The default is as_theme . Keys must contain 1 to 64 non-whitespace characters and cannot include quote or control characters because the value is emitted as an encoded HTML data attribute.

Type

AppSurfaceThemePreferenceBootstrap

Source

Renders the deterministic browser bootstrap for local theme preferences.

Remarks

The bootstrap reads the configured origin-scoped local-storage key before the critical theme style renders, applies a System/Light/Dark selection to the document root, and synchronizes every rendered preference control. Storage access is best-effort: blocked or malformed browser storage falls back to the System mode without affecting server rendering, HTTP state, or the canonical document URL. Keep Script deterministic because CspHash is the public Content Security Policy source expression for its exact contents.

Method

Render

string Render(string? nonce)
Source

Renders the bootstrap script with an optional encoded CSP nonce.

Parameters

  • nonce
    The request-specific nonce, if the host uses nonce-based CSP.

Returns

A script element that supplies the configured storage key by data attribute.

Property

StorageKey

string StorageKey { get; } Source

Gets the encoded-data-attribute-safe key read and written by the browser bootstrap.

Property

CspHash

string CspHash { get; } Source

Gets the stable sha256- source expression for Script .

Type

AppSurfaceThemePreferenceCsp

Source

Provides the stable CSP source hash for the opt-in theme-preference bootstrap.

Remarks

The hash covers only the deterministic inline script emitted by <appsurface-theme-head> after AppSurfaceWebThemingServiceCollectionExtensions.AddAppSurfaceWebThemePreferences(Microsoft.Extensions.DependencyInjection.IServiceCollection, Action{AppSurfaceThemePreferenceOptions}?) . The configured storage key is supplied by an encoded data attribute, so it does not change this value. A dynamic host can instead supply its request nonce through the TagHelper. Static hosts remain responsible for separately hashing their generated critical styles.

Property

ScriptHash

string ScriptHash { get; } Source

Gets the sha256- source expression for the deterministic bootstrap script.