pipelogiq.NET SDK reference
Package selection, configuration defaults, public APIs, compatibility, and migration notes.
This reference covers SDK 0.5.0, targeting net8.0, paired with Pipelogiq server 0.5.0 and its database migrations. Use exact package versions when deploying a fleet of producers and workers.
Package map
| Package | Purpose | Dependencies to understand |
|---|---|---|
PipelogiqSDK.Core | Contracts, builders, API client, shared stage execution | No broker runtime. |
PipelogiqSDK | AMQP PipelineRunner | Core and RabbitMQ.Client 6.8.1. |
PipelogiqSDK.Http | HTTP HttpPipelineRunner | Core; no broker client. |
PipelogiqSDK.Agent | Agent stages, providers, tools, channels | AMQP package. |
PipelogiqSDK.Redis | Agent session and memory stores | Agent; StackExchange.Redis 2.8.16. |
PipelogiqSDK.Postgres | Agent session and memory stores | Agent; Npgsql 8.0.5. |
PipelogiqSDK.Testing | Agent test harness and scripted planner | Agent. |
The package IDs use PipelogiqSDK; source-directory names do not always match them. Core APIs retain the PipelogiqSDK namespace. HTTP runtime namespaces are PipelogiqSDK.Http.Api and PipelogiqSDK.Http.Runner. Redis, PostgreSQL, and testing namespaces are PipelogiqSDK.Redis, PipelogiqSDK.Postgres, and PipelogiqSDK.Testing.
Availability
NuGet.org was checked on September 22, 2026. The existing PipelogiqSDK package index did not contain 0.5.0; the six new package indexes returned 404. These docs therefore require a local/private feed containing 0.5.0. The getting-started guide includes that configuration and source preparation. Recheck availability before switching installation instructions to NuGet.org.
The repository's release workflow prepares packages and can publish through an explicitly configured release process. A version number, successful local tests, or a release workflow file alone does not establish public package availability.
Connection and worker options
PipelogiqRunnerOptions lives in PipelogiqSDK.Configuration.
| Property | Default / use |
|---|---|
ApiKey | Required application credential for registered services and requests. |
ApiUrl | http://localhost:8081; set the external API base URL. |
ApiTimeout | 30 seconds per API request; HTTP long polls add their wait duration. |
WorkerName | Optional human-readable worker name. |
InstanceId | Optional instance identifier. |
WorkerVersion | Optional application worker version. |
Environment | Optional deployment environment metadata. |
Capabilities | Optional dictionary of capability flags for bootstrap. |
Metadata | Optional string dictionary for bootstrap metadata. |
QueueProvisioningMode | AssertOnly checks existing queues; Ensure creates missing queues from bootstrap settings. |
DrainGracePeriod | 30 seconds for in-flight handler drain. |
AllowInsecureServerCertificate | false; disabling validation is only for explicitly isolated development. |
AppId | Obsolete; bootstrap supplies the application identifier. |
The SDK reads connection values passed to options; the sample applications map environment variables into those options. PIPELOGIQ_API_KEY is a sample/deployment convention, not automatic configuration binding for every property. AMQP additionally recognizes the explicit PIPELOGIQ_RABBITMQ_URL local broker override.
AddPipelogiqCore registers the options, factory-managed API client, and stage executor. AddPipelogiq and AddPipelogiqHttpWorker build on it to add a runtime. When supplying your own HttpClient, its timeout is an additional upper bound; use Timeout.InfiniteTimeSpan there if SDK per-request timeouts should be the only bound. A caller-supplied client remains caller-owned. Builders own a client and should be disposed with using.
Handler and result contracts
| API | Role |
|---|---|
IStageHandler<TInput>.ExecuteAsync(input, context) | Typed reference-type input. |
IStageHandler.ExecuteAsync(context) | Input-free handler. |
IStageContext | Pipeline/stage identifiers and mutable execution payload. |
IStageExecutionContext | Attempt, execution ID, idempotency key, timeout, cancellation, and trace metadata. |
IStageResult / StageResultDto | Success/failure, output, context changes, logs, approval, appended stages. |
IClassifiedStageResult.Retryable | Nullable explicit retry classification. |
Helpers in PipelogiqSDK.StageHelper include TryGetValue<T>, AddItem, RemoveItem, AddSensitiveItem, GetCancellationToken, GetAttempt, GetExecutionId, and GetIdempotencyKey. StageResult provides successful, retryable, and terminal factory results. See workflow recipes.
StageOptions has TimeOut, MaxRetries, RetryInterval, RetryOnErrorCodes, Backoff, MaxRetryInterval, Jitter, DependsOn, RunNextIfFailed, RunInParallelWith, FailIfOutputEmpty, NotifyOnFailure, and RunAsUser. These are serialized execution requests; the server implements their effective policy and behavior. Use explicit DependsOn for documented branch/join examples instead of inferring concurrency solely from the presence of RunInParallelWith. RunAsUser is not an authorization system for your business services.
Builders and client operations
| Task | Public API |
|---|---|
| Create pipeline | PipelineBuilder.Create(name, options) → WithAction → SendAsync |
| Idempotent creation | WithIdempotencyKey(key) or PostIdempotentPipelineAsync |
| Create event | EventBuilder.Create(name, handler, options) → SendAsync |
| Add event stage | PipelineBuilder.AsEvent<THandler>(name) |
| Submit application log | LogBuilder.Create(level, message, options) → SendAsync |
| Get pipeline | PipelogiqApiClient.GetPipelineAsync(id, ct) |
| Lookup creation key | GetPipelineByIdempotencyKeyAsync(key, ct) |
| Cancel pipeline | CancelPipelineAsync(id, ct) |
| Append stages | Result AppendedStages, or AppendAgentStagesAsync(id, request, ct) |
| Resolve approval | ResumeStageApprovalAsync(stageId, approved, reason, ct) |
| Apply schedule | ScheduleBuilder.Create(name, options) → trigger/actions → ApplyAsync |
| Schedule administration | GetScheduleAsync, ListSchedulesAsync, ListScheduleRunsAsync, PauseScheduleAsync, ResumeScheduleAsync, TriggerScheduleAsync, ArchiveScheduleAsync |
Worker bootstrap, heartbeat, lease, pull, acknowledgement, and result-reporting APIs are also public for transport integration. Application handlers should normally let a supported runner own that protocol.
PipelogiqApiException derives from HttpRequestException and exposes StatusCode. Its normal message omits response payloads. ResponseBody contains bounded diagnostic text that can include sensitive data; do not automatically log it or expose it to end users.
Status values and execution guarantees
Pipeline status helpers recognize NotStarted, Pending, Running, Paused, Completed, Failed, and Cancelled. PipelineStatuses.IsTerminal recognizes completion, failure, and cancellation, including the alternate Canceled spelling. A server-provided IsTerminal is preferable when available.
Stage helpers include NotStarted, Pending, Running, RetryScheduled, Throttled, WaitingForApproval, Completed, Failed, and Skipped. StageDto can include attempts, retry time, error classification, execution ID, output, logs, and retained failure history. Present current state separately from historical failures.
Delivery is at least once. Leases and execution fences suppress outdated results; they do not undo external effects or force-stop arbitrary application code. Context patches prevent unchanged values from overwriting other branches, but concurrent writes to one key are last-applied-result. Sensitive masking is not encryption. Read workflow reliability before adding side effects.
Upgrade to 0.5.0
- Back up and apply the server migrations for 0.5.0, including sensitive-value redaction history and cleanup of old schedule definitions.
- Upgrade API and scheduler/result-consumer components together.
- Rebuild producer and worker applications against the seven coordinated SDK packages as applicable.
- Verify representative pipelines, approvals, schedules, and business effects in an isolated environment before deployment.
Rebuild consumers after the earlier package split; do not replace a single DLL beside an old application. Use explicit builder options. Replace AddKeyword with AddLabel; the wire field remains compatible. Remove unsupported context calls on LogBuilder. Register handlers before runtime start, and prefer type registration for scoped dependencies. Use context mutations rather than relying on whole-context snapshots.
Current Telegram approvals require pipeline and stage IDs plus immutable sender/chat bindings. Old waiting requests may need a trusted administrative resolution. Built-in agent budgets now use accurate PerRun names; obsolete PerSession aliases retain per-run behavior.
Server 0.5.0 also schedules standalone and mixed event stages through the normal scheduler. Review unfinished older pipelines during upgrade: event stages that previously remained unstarted can become runnable.
The previously documented 0.6.0-preview.1 server was an unpublished development draft consolidated into server 0.5.0; it is not another supported release to install. On the 0.x line, minor SDK updates can contain documented breaking changes; patch versions are intended for compatible fixes.
Scope of the release
Agent providers, OpenAPI import, Telegram, stores, and the deterministic test harness are implemented. Built-in RAG packages and vector retrieval described in older design documents are planned extensions, not installable modules in this release. Session stores do not provide distributed locking or end-user authorization. Tracing and metrics require application exporters. Consult agent limits and test evidence before making production guarantees.