PluginConfigurationForm14.1

Class in Unbroken.LaunchBox.Plugins.Capabilities.Configuration

public sealed class PluginConfigurationForm

Describes one host-rendered plugin configuration form and its submission handler.

Constructors

PluginConfigurationForm(string, string, PluginFormDefinition, Func<…>, string)Initializes a new instance of the PluginConfigurationForm class.
PluginConfigurationForm(string, PluginText, PluginFormDefinition, Func<…>, PluginText)Initializes a configuration form with localizable, formattable presentation text.
PluginConfigurationForm(string, PluginText, PluginFormDefinition, Func<…>, Func<…>, Func<…>, PluginText)Creates a configuration form with explicit initial values and optional named scopes.

PluginConfigurationForm(string, string, PluginFormDefinition, Func<…>, string)

public PluginConfigurationForm(
    string id,
    string name,
    PluginFormDefinition form,
    Func<IReadOnlyDictionary<string, string?>,
        CancellationToken,
        Task<PluginFormResult>> submit,
    string? description = null
)

Initializes a new instance of the PluginConfigurationForm class.

id: The stable configuration form ID within the component, compared ordinally.

name: The required literal name used when localization is unavailable.

form: The framework-neutral form presented by the host.

submit: The asynchronous handler that validates and saves submitted values. It must return a non-null task with a non-null result and observe cancellation during asynchronous work.

description: An optional nonblank literal description used when localization is unavailable.

Exception: ArgumentNullException: A required argument is null.

Exception: ArgumentException: A supplied ID, name, or description is blank.

PluginConfigurationForm(string, PluginText, PluginFormDefinition, Func<…>, PluginText)

public PluginConfigurationForm(
    string id,
    PluginText name,
    PluginFormDefinition form,
    Func<IReadOnlyDictionary<string, string?>,
        CancellationToken,
        Task<PluginFormResult>> submit,
    PluginText? description = null
)

Initializes a configuration form with localizable, formattable presentation text.

id: The stable configuration form ID within the component, compared ordinally.

name: The form name, including its required fallback format.

form: The framework-neutral form presented by the host.

submit: The asynchronous handler that validates and saves submitted values.

description: An optional description with its fallback format.

PluginConfigurationForm(string, PluginText, PluginFormDefinition, Func<…>, Func<…>, Func<…>, PluginText)

public PluginConfigurationForm(
    string id,
    PluginText name,
    PluginFormDefinition form,
    Func<CancellationToken, Task<PluginConfigurationValues>> loadValues,
    Func<PluginConfigurationValues,
        CancellationToken,
        Task<PluginFormResult>> submit,
    Func<IPluginConfigurationValues, PluginFormResult>? validate,
    PluginText? description = null
)

Creates a configuration form with explicit initial values and optional named scopes.

id: The stable form identity within the component.

name: The localizable form name.

form: The shared field definition.

loadValues: Loads detached explicit values. Bind instance identity in this callback.

submit: Persists the complete accepted snapshot once, including all scopes.

validate: Validates one effective scope without persisting or changing the submitted snapshot.

description: Optional localizable explanation.

Remarks

The host retains drafts and validates every supplied scope before submitting. Field defaults are presentation fallbacks and are not stored unless explicitly edited. This non-secret scoped contract cannot contain secret fields.

Properties

DescriptionGets the optional localizable, formattable description.
FormGets the framework-neutral form presented by the host.
IdGets the stable configuration form ID within the component, compared ordinally.
NameGets the localizable, formattable name and its fallback format.
SupportsScopesGets whether this form exchanges explicit values across optional named scopes.

Description

public PluginText? Description { get; }

Gets the optional localizable, formattable description.

Form

public PluginFormDefinition Form { get; }

Gets the framework-neutral form presented by the host.

Id

public string Id { get; }

Gets the stable configuration form ID within the component, compared ordinally.

Name

public PluginText Name { get; }

Gets the localizable, formattable name and its fallback format.

SupportsScopes

public bool SupportsScopes { get; }

Gets whether this form exchanges explicit values across optional named scopes.

Methods

LoadValuesAsyncLoads detached scoped values. Ordinary forms instead supply initial field defaults.
SubmitAsyncSubmits configuration values for validation and persistence by the plugin.
SubmitValuesAsyncSubmits a complete scoped snapshot after host validation.
ValidateValuesValidates one effective scope without persisting. Ordinary forms validate during submission.

LoadValuesAsync

public Task<PluginConfigurationValues?> LoadValuesAsync(
    CancellationToken cancellationToken
)

Loads detached scoped values. Ordinary forms instead supply initial field defaults.

cancellationToken: Cancels retrieval.

Returns

The explicit values for a scoped form, or null for an ordinary form.

SubmitAsync

public Task<PluginFormResult> SubmitAsync(
    IReadOnlyDictionary<string, string?> values,
    CancellationToken cancellationToken
)

Submits configuration values for validation and persistence by the plugin.

values: Submitted values keyed by form field ID. Values are passed unchanged to the handler; the plugin determines which values are required and how they are saved.

cancellationToken: A token used to cancel submission.

Returns

The plugin's acceptance result, including any form or field validation errors.

Remarks

Cancellation requested before this call prevents the handler from running. Once invoked, the handler is responsible for observing the token. Handler exceptions and cancellation propagate to the caller; cancellation does not automatically undo plugin persistence.

Exception: ArgumentNullException: values is null.

Exception: OperationCanceledException: Cancellation has already been requested.

SubmitValuesAsync

public Task<PluginFormResult> SubmitValuesAsync(
    PluginConfigurationValues values,
    CancellationToken cancellationToken
)

Submits a complete scoped snapshot after host validation.

values: All explicit values, including scopes and preserved unknown fields.

cancellationToken: Cancels submission.

Returns

The plugin's acceptance result.

Remarks

This method is only available for forms constructed with scoped callbacks. Cancellation does not roll back completed writes.

ValidateValues

public PluginFormResult ValidateValues(IPluginConfigurationValues values)

Validates one effective scope without persisting. Ordinary forms validate during submission.

values: A detached view, including declared defaults.

Returns

The validation result.