---
title: ".NET SDK reference"
description: "Package selection, configuration defaults, public APIs, compatibility, and migration notes."
category: ".NET SDK"
---

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](https://api.nuget.org/v3-flatcontainer/pipelogiqsdk/index.json) 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](/docs/net/getting-started) 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](/docs/net/workflows).

`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](/docs/net/workflows) before adding side effects.

## Upgrade to 0.5.0

1. Back up and apply the server migrations for 0.5.0, including sensitive-value redaction history and cleanup of old schedule definitions.
2. Upgrade API and scheduler/result-consumer components together.
3. Rebuild producer and worker applications against the seven coordinated SDK packages as applicable.
4. 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](/docs/net/agents) and [test evidence](/docs/net/testing) before making production guarantees.