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

Theming

Type

AppSurfaceThemeServiceCollectionExtensions

Source

Registers immutable AppSurface theme-pair services for a host.

Method

AddAppSurfaceTheming

2 overloads
IServiceCollection AddAppSurfaceTheming(this IServiceCollection services, Action<AppSurfaceThemeRegistryOptions> configure) Source

Validates and registers configured semantic pairs and their default resolver.

Parameters

  • servicesService collection receiving the sealed registry.
  • configureHost configuration for pairs and the default mode.

Returns

The original services instance.

Exceptions

  • ArgumentNullExceptionThrown when an argument is null.
  • AppSurfaceThemeValidationExceptionThrown when configuration cannot safely produce a complete pair.
IServiceCollection AddAppSurfaceTheming(this IServiceCollection services, AppSurfaceThemeRegistryOptions options) Source

Validates and registers an explicit semantic pair configuration snapshot.

Parameters

  • servicesService collection receiving the sealed registry.
  • optionsHost configuration for pairs and the default mode.

Returns

The original services instance.

Exceptions

  • ArgumentNullExceptionThrown when an argument is null.
  • AppSurfaceThemeValidationExceptionThrown when configuration cannot safely produce a complete pair.
Method

AddRequiredThemeExtension

IServiceCollection AddRequiredThemeExtension<TSettings>(this IServiceCollection services) Source

Requires an application-owned extension provider to cover every configured semantic pair.

Type Parameters

  • TSettingsApplication-owned non-null settings type.

Parameters

  • servicesService collection receiving the required-provider validator.

Returns

The original services instance.

Exceptions

  • ArgumentNullExceptionThrown when services is null.
  • AppSurfaceThemeValidationExceptionThrown when IAppSurfaceThemeRegistry is first resolved and the provider is missing (ASTHEME201) or supplies no non-null setting for a registered pair (ASTHEME202). This method itself does not throw it.

Remarks

Register IAppSurfaceThemeExtensionProvider{TSettings} before the neutral registry is first resolved. The provider remains application-owned: this method verifies only provider presence and one non-null setting for each registered pair. It neither validates, serializes, nor logs TSettings.

Type

AppSurfaceThemeRegistryOptions

Source

Configures registered theme pairs and the host's default rendering mode.

Property

DefaultTheme

AppSurfaceThemeId DefaultTheme { get; set; } Source

Gets or sets the pair used by IAppSurfaceThemeResolver.ResolveDefault.

Property

DefaultMode

AppSurfaceThemeMode DefaultMode { get; set; } Source

Gets or sets the host's default browser rendering mode.

Property

Pairs

IList<AppSurfaceThemePair> Pairs { get; } Source

Gets the registered semantic light/dark pairs.

Type

IAppSurfaceThemeRegistry

Source

Looks up validated registered pairs by identifier.

Method

GetRequired

AppSurfaceThemePair GetRequired(AppSurfaceThemeId id) Source

Gets a sealed pair by its canonical identifier.

Parameters

  • idRegistered pair identifier.

Returns

The sealed semantic pair.

Exceptions

  • KeyNotFoundExceptionThrown when id is not registered.
Property

ThemeIds

IReadOnlyCollection<AppSurfaceThemeId> ThemeIds { get; } Source

Gets the canonical ids of every sealed registered pair in registration order.

Type

IAppSurfaceThemeResolver

Source

Resolves the host-selected default theme pair.

Method

ResolveDefault

AppSurfaceThemeResolution ResolveDefault() Source

Resolves the sealed pair and rendering mode configured by the host.

Returns

The host's default semantic theme resolution.

Type

AppSurfaceThemeDiagnostic

Source

Provides a stable, safe theme configuration diagnostic.

Parameters

  • CodeStable ASTHEME diagnostic code.
  • SeveritySafety impact of the condition.
  • ProblemSafe one-line failure description.
  • CauseSafe explanation with applicable pair, role, or configuration path.
  • FixConcrete remediation.
  • DocumentationCanonical troubleshooting link.
Method

Create

AppSurfaceThemeDiagnostic Create(string code, string problem, string cause, string fix, AppSurfaceThemeDiagnosticSeverity severity = AppSurfaceThemeDiagnosticSeverity.Error) Source

Creates a diagnostic linked to the canonical theme troubleshooting reference.

Parameters

  • codeStable diagnostic code.
  • problemSafe one-line failure description.
  • causeSafe explanation.
  • fixConcrete remediation.
  • severitySafety impact of the condition.

Returns

A stable diagnostic with its canonical documentation link.

Type

AppSurfaceThemeValidationException

Source

Thrown when a theme registry cannot produce a safe sealed snapshot.

Property

Diagnostics

IReadOnlyList<AppSurfaceThemeDiagnostic> Diagnostics { get; } Source

Gets all safe diagnostics that prevented registry creation.

Type

AppSurfaceThemeRegistry

Source

Validates and resolves immutable semantic theme pairs.

Method

GetRequired

AppSurfaceThemePair GetRequired(AppSurfaceThemeId id) Source

Gets a sealed pair by its canonical identifier.

Parameters

  • idRegistered pair identifier.

Returns

A defensive snapshot of the registered pair.

Exceptions

  • KeyNotFoundExceptionThrown when id is not registered.
Method

ResolveDefault

AppSurfaceThemeResolution ResolveDefault() Source

Resolves the host-selected default pair and mode.

Returns

A defensive snapshot of the default resolution.

Method

Validate

IReadOnlyList<AppSurfaceThemeDiagnostic> Validate(AppSurfaceThemeRegistryOptions options) Source

Validates a candidate registry configuration without creating a registry.

Parameters

  • optionsCandidate host configuration.

Returns

All stable diagnostics that prevent safe registry creation.

Method

IsSafeResolution

bool IsSafeResolution(AppSurfaceThemeResolution? resolution) Source

Determines whether a sealed resolution can be safely consumed by a package-owned adapter.

Parameters

  • resolutionThe resolution to validate.

Returns

true when the resolution satisfies the neutral pair contract; otherwise false.

Remarks

This predicate is intended for adapters that need a fail-closed boundary without serializing a Web document. It applies the same identifier, mode, role, and contrast checks used for registry registration.

Enum

AppSurfaceThemeDiagnosticSeverity

Source

Classifies the safety impact of a theme diagnostic.

Type

AppSurfaceThemeId

Source

Identifies a registered semantic theme pair.

Property

Value

string Value { get; } Source

Gets the canonical identifier value.

Type

AppSurfaceThemeRoles

Source

Defines the minimum semantic color roles consumed by AppSurface-owned UI.

Property

Canvas

string Canvas { get; } Source

Gets the primary page canvas color.

Property

Surface

string Surface { get; } Source

Gets the default content-surface color.

Property

RaisedSurface

string RaisedSurface { get; } Source

Gets the raised content-surface color.

Property

Text

string Text { get; } Source

Gets the primary readable text color.

Property

MutedText

string MutedText { get; } Source

Gets the secondary readable text color.

Property

Border

string Border { get; } Source

Gets the visible border and divider color.

Property

Accent

string Accent { get; } Source

Gets the default accent color.

Property

AccentStrong

string AccentStrong { get; } Source

Gets the high-emphasis accent color.

Property

Danger

string Danger { get; } Source

Gets the error and destructive-action color.

Property

Focus

string Focus { get; } Source

Gets the keyboard-visible focus color.

Type

AppSurfaceThemePair

Source

Pairs complete light and dark semantic role sets under one identifier.

Method

AppSurface

AppSurfaceThemePair AppSurface() Source

Creates AppSurface's built-in accessible semantic pair.

Returns

A new immutable pair instance named appsurface.

Property

Id

AppSurfaceThemeId Id { get; } Source

Gets the canonical pair identifier.

Property

Light

AppSurfaceThemeRoles Light { get; } Source

Gets the complete light role set.

Property

Dark

AppSurfaceThemeRoles Dark { get; } Source

Gets the complete dark role set.

Type

AppSurfaceThemeResolution

Source

Represents the sealed default pair together with its host-selected mode.

Property

Id

AppSurfaceThemeId Id { get; } Source

Gets the resolved pair identifier.

Property

Mode

AppSurfaceThemeMode Mode { get; } Source

Gets the host-selected rendering mode.

Property

Light

AppSurfaceThemeRoles Light { get; } Source

Gets the sealed light role set.

Property

Dark

AppSurfaceThemeRoles Dark { get; } Source

Gets the sealed dark role set.

Type

IAppSurfaceThemeExtensionProvider<TSettings>

Source

Allows an adapter to obtain application-owned settings for a registered pair.

Type Parameters

  • TSettingsApplication-owned settings type. Neutral theming neither validates nor serializes it.
Method

TryGet

bool TryGet(AppSurfaceThemeId themeId, out TSettings settings) Source

Attempts to get settings for the supplied sealed pair.

Parameters

  • themeIdRegistered theme-pair identifier.
  • settingsApplication-owned settings when available.

Returns

true when settings exist for themeId; otherwise false.

Enum

AppSurfaceThemeMode

Source

Identifies the host-selected rendering behavior for a semantic theme pair.