Partie Providers

Providers

A Provider creates a value when another context requests it. Registering one makes the value available; it runs only if a matching consumer needs that value. Use Providers for request-specific lookups, connections, and configuration that some handlers need.

Create a value

The four generic arguments name the provided value, context, request, and handler result:

// AcademicYear.cs
public sealed record AcademicYear(string Name);

// AcademicYearProvider.cs
public sealed record AcademicYearContext(
    [Parameter] string Name = "2026-2027"
);

public sealed class AcademicYearProvider :
    IQueryProvider<AcademicYear, AcademicYearContext, CourseSearchQuery, CourseSearchResult>
{
    public static ValueTask<Result<CourseSearchResult>> OnQueryAsync(
        AcademicYearContext context,
        CourseSearchQuery query,
        Next<AcademicYear, CourseSearchResult> next,
        CancellationToken cancellationToken
    )
    {
        return next(new AcademicYear(context.Name));
    }
}

next accepts the provided AcademicYear and returns the final Result<CourseSearchResult>. The year feeds a context, while the result goes back to the caller.

Register and consume

Partie generates [AcademicYearProvider] from the class name. The attribute's arguments come from [Parameter] values in the context:

[AcademicYearProvider("2027-2028")]
...

The handler receives the year through its context:

public sealed record CourseSearchContext(
    [Inject] ICourseCatalog Catalog,
    [Provide] AcademicYear Year
);

The Provider runs once for this registration within the invocation. If a Partie and the handler both request its value, they share it. If no matching context requests the year, the Provider does no work. Registering the same Provider twice creates separate sources, each with its own parameters.

Use services and asynchronous work

A Provider's context supports the same attributes as a handler's context. Use [Inject] to call an application service and [Provide] or [Decorate] for dependencies from other steps.

For an asynchronous lookup, declare async ValueTask<Result<TResult>>, await the lookup with the supplied cancellation token, and then await next(value). A Provider can return a failure without calling next when it cannot supply the value. That failure must be a Result<TResult> for the handler's result type, rather than a result of the provided type.

Commands and matching

Command Providers implement ICommandProvider<TProvided, TContext, TCommand, TResult> and declare OnCommandAsync. Its parameters are context, command, Next<TProvided, TResult>, and cancellation token. Both hooks must be static and return exactly ValueTask<Result<TResult>>.

A Provider registered on a group runs only for operations and types its contract matches. The example above matches only the exact CourseSearchQuery and CourseSearchResult. Use Generic matching to share a Provider across handlers.

Use a Partie when behavior must run for each matching request even if nobody consumes its output. See Contexts for value selection and Routes and groups for registration scope.