StellaOps.Workflow.Publisher
Publishes the workflow definitions an application bundles to a workflow engine over HTTP.
| Package | StellaOps.Workflow.Publisher |
| Component | Workflow |
| Licence | BUSL-1.1 (Workflow licence) |
| Package kind | Library |
| Target framework | net10.0 |
To add the package to a project, see Installing Stella Ops packages.
Namespaces
| Namespace | Types |
|---|---|
StellaOps.Workflow.Publisher | 13 |
StellaOps.Workflow.Publisher namespace
| Type | Kind | Description |
|---|---|---|
BundledWorkflow | record | A single canonical workflow of a plugin assembly: an entry of the generated _BundledCanonicalWorkflowRegistry.Entries, or a workflow the generator listed in RuntimeCompiledWorkflowTypes and the provider compiled with the runtime compiler. |
HttpWorkflowDefinitionImportTransport | class | Default transport — sends the import request as an HTTP POST to {Endpoint}{CommandPath}. |
IBundledWorkflowProvider | interface | Finds the canonical workflows bundled in plugin assemblies. |
IWorkflowDefinitionImportTransport | interface | Transport used by WorkflowPublisherto deliver a single WorkflowDefinitionImportRequestto the workflow engine’s definition-import endpoint. |
PublishSummary | record | The outcome of one publish run. |
PublisherServiceCollectionExtensions | class | Registers the workflow publisher. |
ReflectionBundledWorkflowProvider | class | Default IBundledWorkflowProvider: scans a provided list of assemblies for the generator-emitted _BundledCanonicalWorkflowRegistry type (in the StellaOps.Workflow.Generated namespace) and reads its Entries field via reflection. |
WorkflowDefinitionRemoteDeployRequest | record | What WorkflowDefinitionRemoteDeployServicedeploys, and where. |
WorkflowDefinitionRemoteDeployResult | record | The outcome of one remote deployment. |
WorkflowDefinitionRemoteDeployService | class | Pushes one exported definition to another workflow server through an IWorkflowDefinitionImportTransport. |
WorkflowPublisher | class | Publishes the canonical workflows bundled in plugin assemblies to a workflow server. |
WorkflowPublisherHostedService | class | Runs WorkflowPublisher.PublishAllAsync(CancellationToken)once on IHostedService.StartAsync(CancellationToken). |
WorkflowPublisherOptions | class | Configuration for the workflow publisher. |
BundledWorkflow record
public sealed record BundledWorkflow
A single canonical workflow of a plugin assembly: an entry of the generated _BundledCanonicalWorkflowRegistry.Entries, or a workflow the generator listed in RuntimeCompiledWorkflowTypes and the provider compiled with the runtime compiler. A runtime-compiled definition has no CanonicalContentHash (the workflow service computes its own). CompilationError is set, and the definition empty, when that runtime compilation failed: the workflow has no canonical definition and cannot be published.
Parameters
WorkflowName: The workflow name.WorkflowVersion: The workflow version.DisplayName: The display name.CanonicalDefinitionJson: The canonical definition, as JSON; empty when the compilation failed.CanonicalContentHash: The content hash of the canonical definition; empty for a runtime-compiled definition.SourceAssemblyName: The assembly the workflow comes from.CompilationError: Why the runtime compilation failed; not set when it succeeded.
BundledWorkflow(string, string, string, string, string, string, string) constructor
public BundledWorkflow(string WorkflowName, string WorkflowVersion, string DisplayName, string CanonicalDefinitionJson, string CanonicalContentHash, string SourceAssemblyName, string? CompilationError = null)
A single canonical workflow of a plugin assembly: an entry of the generated _BundledCanonicalWorkflowRegistry.Entries, or a workflow the generator listed in RuntimeCompiledWorkflowTypes and the provider compiled with the runtime compiler. A runtime-compiled definition has no CanonicalContentHash (the workflow service computes its own). CompilationError is set, and the definition empty, when that runtime compilation failed: the workflow has no canonical definition and cannot be published.
Parameters
WorkflowName: The workflow name.WorkflowVersion: The workflow version.DisplayName: The display name.CanonicalDefinitionJson: The canonical definition, as JSON; empty when the compilation failed.CanonicalContentHash: The content hash of the canonical definition; empty for a runtime-compiled definition.SourceAssemblyName: The assembly the workflow comes from.CompilationError: Why the runtime compilation failed; not set when it succeeded.
CanonicalContentHash property
public string CanonicalContentHash { get; init; }
The content hash of the canonical definition; empty for a runtime-compiled definition.
CanonicalDefinitionJson property
public string CanonicalDefinitionJson { get; init; }
The canonical definition, as JSON; empty when the compilation failed.
CompilationError property
public string? CompilationError { get; init; }
Why the runtime compilation failed; not set when it succeeded.
DisplayName property
public string DisplayName { get; init; }
The display name.
SourceAssemblyName property
public string SourceAssemblyName { get; init; }
The assembly the workflow comes from.
WorkflowName property
public string WorkflowName { get; init; }
The workflow name.
WorkflowVersion property
public string WorkflowVersion { get; init; }
The workflow version.
HttpWorkflowDefinitionImportTransport class
public sealed class HttpWorkflowDefinitionImportTransport : IWorkflowDefinitionImportTransport
Default transport — sends the import request as an HTTP POST to {Endpoint}{CommandPath}. Hosts that use a different delivery channel (RabbitMQ RPC, gRPC, etc.) should register their own IWorkflowDefinitionImportTransportimplementation before calling AddWorkflowPublisher.
HttpWorkflowDefinitionImportTransport(HttpClient) constructor
public HttpWorkflowDefinitionImportTransport(HttpClient httpClient)
No description.
ImportAsync(WorkflowDefinitionImportRequest, WorkflowPublisherOptions, CancellationToken) method
public Task<WorkflowDefinitionImportResponse> ImportAsync(WorkflowDefinitionImportRequest request, WorkflowPublisherOptions options, CancellationToken cancellationToken)
No description.
IBundledWorkflowProvider interface
public interface IBundledWorkflowProvider
Finds the canonical workflows bundled in plugin assemblies.
Enumerate() method
IReadOnlyList<BundledWorkflow> Enumerate()
Returns the bundled workflows.
Returns
The workflows.
IWorkflowDefinitionImportTransport interface
public interface IWorkflowDefinitionImportTransport
Transport used by WorkflowPublisherto deliver a single WorkflowDefinitionImportRequestto the workflow engine’s definition-import endpoint. Hosts that speak another protocol (RabbitMQ RPC, for example) plug their own implementation here; the default HTTP implementation keeps the publisher runnable out of the box.
ImportAsync(WorkflowDefinitionImportRequest, WorkflowPublisherOptions, CancellationToken) method
Task<WorkflowDefinitionImportResponse> ImportAsync(WorkflowDefinitionImportRequest request, WorkflowPublisherOptions options, CancellationToken cancellationToken)
Sends an import request to the server the options name.
Parameters
request: The import request.options: The server address, command path, token and timeout.cancellationToken: Cancels the operation.
Returns
The server’s answer: whether it imported the definition, and the version.
PublishSummary record
public sealed record PublishSummary
The outcome of one publish run.
Parameters
Total: The bundled workflows found.Imported: The workflows the server imported.HashSkipped: The workflows not imported: the server already had the same definition, or the run was dry.Failed: The workflows that failed after their retries.DisabledReason: Why nothing was published, such asEnabled=false; not set otherwise.
PublishSummary(int, int, int, int, string) constructor
public PublishSummary(int Total, int Imported, int HashSkipped, int Failed, string? DisabledReason)
The outcome of one publish run.
Parameters
Total: The bundled workflows found.Imported: The workflows the server imported.HashSkipped: The workflows not imported: the server already had the same definition, or the run was dry.Failed: The workflows that failed after their retries.DisabledReason: Why nothing was published, such asEnabled=false; not set otherwise.
DisabledReason property
public string? DisabledReason { get; init; }
Why nothing was published, such as Enabled=false; not set otherwise.
Failed property
public int Failed { get; init; }
The workflows that failed after their retries.
HashSkipped property
public int HashSkipped { get; init; }
The workflows not imported: the server already had the same definition, or the run was dry.
Imported property
public int Imported { get; init; }
The workflows the server imported.
Total property
public int Total { get; init; }
The bundled workflows found.
PublisherServiceCollectionExtensions class
public static class PublisherServiceCollectionExtensions
Registers the workflow publisher.
AddWorkflowPublisher(IServiceCollection, IConfiguration, params Assembly[]) extension method
public static IServiceCollection AddWorkflowPublisher(this IServiceCollection services, IConfiguration configuration, params Assembly[] pluginAssemblies)
PublisherServiceCollectionExtensions.AddWorkflowPublisher(IServiceCollection, params Assembly[]), with WorkflowPublisherOptionsbound from configuration (the section holding the options) instead of the host’s WorkflowPublisherOptions.SectionNamesection.
AddWorkflowPublisher(IServiceCollection, params Assembly[]) extension method
public static IServiceCollection AddWorkflowPublisher(this IServiceCollection services, params Assembly[] pluginAssemblies)
Registers the workflow publisher plus a WorkflowPublisherHostedServicethat runs the publish-all cycle on startup. WorkflowPublisherOptionsare bound from the WorkflowPublisherOptions.SectionNamesection of the host configuration and validated when the host starts: an enabled publisher needs an absolute http or https WorkflowPublisherOptions.Endpoint(unless it runs dry), a command path starting with ‘/’, a positive timeout and non-negative retries.
The default transport is HttpWorkflowDefinitionImportTransport. Hosts that speak another protocol (RabbitMQ RPC, for example) should register their own IWorkflowDefinitionImportTransportBEFORE calling this method; the publisher registers its transport with TryAddSingleton, which keeps the override in place.
Parameters
services: The service collection to add the publisher to.pluginAssemblies: Assemblies to scan for the generator-emitted registry. Defaults toAppDomain.GetAssemblies()of the current application domain at resolution time if none are provided.
Returns
The same service collection, for chaining.
ReflectionBundledWorkflowProvider class
public sealed class ReflectionBundledWorkflowProvider : IBundledWorkflowProvider
Default IBundledWorkflowProvider: scans a provided list of assemblies for the generator-emitted _BundledCanonicalWorkflowRegistry type (in the StellaOps.Workflow.Generated namespace) and reads its Entries field via reflection. The workflows the generator could not evaluate at compile time (WF021) are listed in the registry’s RuntimeCompiledWorkflowTypes; the provider creates each and compiles it with WorkflowCanonicalDefinitionCompiler. A workflow the runtime compiler rejects is returned with BundledWorkflow.CompilationErrorset.
ReflectionBundledWorkflowProvider(IEnumerable<Assembly>) constructor
public ReflectionBundledWorkflowProvider(IEnumerable<Assembly> assemblies)
Creates a provider over assemblies.
Parameters
assemblies: The assemblies to scan.
Enumerate() method
public IReadOnlyList<BundledWorkflow> Enumerate()
Returns the bundled workflows.
Returns
The workflows.
WorkflowDefinitionRemoteDeployRequest record
public sealed record WorkflowDefinitionRemoteDeployRequest
What WorkflowDefinitionRemoteDeployServicedeploys, and where.
WorkflowDefinitionRemoteDeployRequest() constructor
public WorkflowDefinitionRemoteDeployRequest()
Creates an instance of WorkflowDefinitionRemoteDeployRequest.
TargetAuthToken property
public string? TargetAuthToken { get; init; }
Optional bearer token the target’s import endpoint requires.
TargetCommandPath property
public string? TargetCommandPath { get; init; }
Path of the target’s import route, appended to WorkflowDefinitionRemoteDeployRequest.TargetServerUrl. Null or blank means WorkflowPublisherOptions.DefaultCommandPath, the route MapWorkflowEndpoints serves.
TargetServerUrl property
public required string TargetServerUrl { get; init; }
The base address of the target workflow server.
WorkflowName property
public required string WorkflowName { get; init; }
The workflow to deploy.
WorkflowVersion property
public string? WorkflowVersion { get; init; }
The version to deploy; the latest when not set.
WorkflowDefinitionRemoteDeployResult record
public sealed record WorkflowDefinitionRemoteDeployResult
The outcome of one remote deployment.
WorkflowDefinitionRemoteDeployResult() constructor
public WorkflowDefinitionRemoteDeployResult()
Creates an instance of WorkflowDefinitionRemoteDeployResult.
Error property
public string? Error { get; init; }
Why the deployment failed, when the export or the push failed.
Succeeded property
public bool Succeeded { get; init; }
Whether the target imported the definition; false also when the target already had the same definition.
TargetServerUrl property
public string? TargetServerUrl { get; init; }
The target workflow server.
ValidationIssues property
public string[]? ValidationIssues { get; init; }
The validation issues the target reported.
WorkflowName property
public string? WorkflowName { get; init; }
The workflow name.
WorkflowVersion property
public string? WorkflowVersion { get; init; }
The version the target reports.
WorkflowDefinitionRemoteDeployService class
public sealed class WorkflowDefinitionRemoteDeployService
Pushes one exported definition to another workflow server through an IWorkflowDefinitionImportTransport. The caller supplies the export (usually WorkflowDefinitionDeploymentService.CreateImportRequestAsync), so the service does not depend on the engine. Every failure, of the export or of the push, comes back as an unsuccessful result.
WorkflowDefinitionRemoteDeployService(IWorkflowDefinitionImportTransport, ILogger) constructor
public WorkflowDefinitionRemoteDeployService(IWorkflowDefinitionImportTransport transport, ILogger? logger = null)
Pushes one exported definition to another workflow server through an IWorkflowDefinitionImportTransport. The caller supplies the export (usually WorkflowDefinitionDeploymentService.CreateImportRequestAsync), so the service does not depend on the engine. Every failure, of the export or of the push, comes back as an unsuccessful result.
DeployAsync(WorkflowDefinitionRemoteDeployRequest, Func<CancellationToken, Task<WorkflowDefinitionImportRequest>>, CancellationToken) method
public Task<WorkflowDefinitionRemoteDeployResult> DeployAsync(WorkflowDefinitionRemoteDeployRequest request, Func<CancellationToken, Task<WorkflowDefinitionImportRequest?>> exportDefinition, CancellationToken cancellationToken = default)
Exports the definition and pushes it to the target.
Parameters
request: What to deploy, and where.exportDefinition: Exports the definition; returnsnullwhen the workflow version does not exist.cancellationToken: Cancels the operation.
Returns
The outcome; a failure is a result that did not succeed, never an exception.
WorkflowPublisher class
public sealed class WorkflowPublisher
Publishes the canonical workflows bundled in plugin assemblies to a workflow server.
WorkflowPublisher(IWorkflowDefinitionImportTransport, IBundledWorkflowProvider, IOptions<WorkflowPublisherOptions>, ILogger<WorkflowPublisher>) constructor
public WorkflowPublisher(IWorkflowDefinitionImportTransport transport, IBundledWorkflowProvider provider, IOptions<WorkflowPublisherOptions> options, ILogger<WorkflowPublisher> logger)
Creates the publisher.
Parameters
transport: Sends the import requests.provider: Finds the bundled workflows.options: The publisher options.logger: Receives the diagnostics.
PublishAllAsync(CancellationToken) method
public Task<PublishSummary> PublishAllAsync(CancellationToken cancellationToken)
Publishes every bundled workflow, retrying each up to WorkflowPublisherOptions.MaxRetriesPerWorkflowtimes with a doubling delay. A workflow without a canonical definition fails. A failure is counted and the run goes on, unless WorkflowPublisherOptions.FailOnErroris set.
Parameters
cancellationToken: Cancels the operation.
Returns
The counts of the run.
WorkflowPublisherHostedService class
public sealed class WorkflowPublisherHostedService : IHostedService
Runs WorkflowPublisher.PublishAllAsync(CancellationToken)once on IHostedService.StartAsync(CancellationToken). Wired by AddWorkflowPublisher(). Consumers using a non-.NET-Hosting bootstrap (e.g., a service initializer) can wire WorkflowPublisherinto their own startup mechanism directly without using this service.
WorkflowPublisherHostedService(WorkflowPublisher, ILogger<WorkflowPublisherHostedService>) constructor
public WorkflowPublisherHostedService(WorkflowPublisher publisher, ILogger<WorkflowPublisherHostedService> logger)
Creates the service.
Parameters
publisher: The publisher.logger: Receives the diagnostics.
StartAsync(CancellationToken) method
public Task StartAsync(CancellationToken cancellationToken)
Runs one publish run; an error stops the host start.
Parameters
cancellationToken: Cancels the operation.
Returns
A task that completes when the run ends.
StopAsync(CancellationToken) method
public Task StopAsync(CancellationToken cancellationToken)
Does nothing.
Parameters
cancellationToken: Cancels the operation.
Returns
A completed task.
WorkflowPublisherOptions class
public sealed class WorkflowPublisherOptions
Configuration for the workflow publisher. AddWorkflowPublisher binds it from the WorkflowPublisherOptions.SectionNamesection of the host configuration (or from the section a caller passes) and validates it when the host starts.
WorkflowPublisherOptions() constructor
public WorkflowPublisherOptions()
Creates an instance of WorkflowPublisherOptions.
DefaultCommandPath constant
public const string DefaultCommandPath = "/api/workflow/definitions/import"
The import route of the Workflow endpoints (MapWorkflowEndpoints in StellaOps.Workflow.AspNetCore), the default WorkflowPublisherOptions.CommandPath.
SectionName constant
public const string SectionName = "WorkflowPublisher"
The configuration section AddWorkflowPublisher binds.
AuthToken property
public string? AuthToken { get; init; }
Optional bearer token for the outbound request. Typically resolved from an external secret store before binding — the publisher treats this as an opaque bearer value.
CommandPath property
public string CommandPath { get; init; }
Path of the import route, appended to WorkflowPublisherOptions.Endpoint. Defaults to WorkflowPublisherOptions.DefaultCommandPath, the route a host built from MapWorkflowEndpoints serves; set it when the target maps the import elsewhere (for example behind a gateway prefix).
DryRun property
public bool DryRun { get; init; }
When true the publisher logs what it would POST but does not actually POST.
Enabled property
public bool Enabled { get; init; }
When false the publisher does nothing on startup. Handy for per-environment overrides.
Endpoint property
public string Endpoint { get; init; }
Base URL of the workflow service’s REST gateway (no trailing slash).
FailOnError property
public bool FailOnError { get; init; }
If false, publish failures are logged as warnings and the service continues to start up. If true, publish failures throw and take the startup down. Default false so a workflow-service outage does not cascade.
MaxRetriesPerWorkflow property
public int MaxRetriesPerWorkflow { get; init; }
Retries of a failed import, per workflow; not negative. The default is 3.
RetryBaseDelay property
public TimeSpan RetryBaseDelay { get; init; }
The delay before the first retry, doubled for each further retry; not negative. The default is 2 seconds.
ServiceName property
public string? ServiceName { get; init; }
Logical name of the publishing service, sent as the import request’s ImportedBy. A host built from MapWorkflowEndpoints records the authenticated principal as the importer instead.
Timeout property
public TimeSpan Timeout { get; init; }
The timeout of one import request; positive. The default is 30 seconds.
