Tutorial · .NET

.NET with an OpenAI-compatible API

The official OpenAI .NET SDK works against a compatible endpoint once you change the base URL. The rest is ordinary .NET engineering: DI lifetimes, streaming, tool loops, retries and tests.

Short answer. Install the OpenAI NuGet package, give ChatClient an ApiKeyCredential and an OpenAIClientOptions whose Endpoint is https://api.plugsky.com/v1, then use the same streaming, tool-calling and dependency-injection patterns you would use with OpenAI. Keep the key in an environment variable, register the client as a singleton, and test with a stubbed transport or a gated integration test.

1. Install the SDK and override the endpoint

The OpenAI .NET library is generated from the OpenAI OpenAPI specification and published as the OpenAI package. It is compatible with .NET Standard 2.0 applications, so it works in .NET 8, .NET 9 and .NET 10 services. The only change for a compatible provider is the endpoint and, usually, the model ID.

dotnet add package OpenAI
using System.ClientModel;
using OpenAI;
using OpenAI.Chat;

var apiKey = Environment.GetEnvironmentVariable("PLUGSKY_API_KEY")
    ?? throw new InvalidOperationException("PLUGSKY_API_KEY is not set");

var options = new OpenAIClientOptions
{
    Endpoint = new Uri("https://api.plugsky.com/v1")
};

var chat = new ChatClient(
    model: "plugsky-coder",
    credential: new ApiKeyCredential(apiKey),
    options: options);

Endpoint is the base URL, not the full /chat/completions path. The SDK appends the resource path. A duplicated /v1/v1 usually produces a 404 that looks like a bad key.

2. Register the client with dependency injection

ChatClient is thread-safe. Register one instance as a singleton and let it reuse connections; creating a client per request wastes sockets and adds latency. Read the model and base URL from configuration so a staging deployment can point somewhere else without a rebuild.

builder.Services.AddSingleton(sp =>
{
    var config = sp.GetRequiredService<IConfiguration>();
    var key = Environment.GetEnvironmentVariable("PLUGSKY_API_KEY")
        ?? throw new InvalidOperationException("PLUGSKY_API_KEY is not set");

    return new ChatClient(
        model: config["Plugsky:Model"] ?? "plugsky-coder",
        credential: new ApiKeyCredential(key),
        options: new OpenAIClientOptions
        {
            Endpoint = new Uri(config["Plugsky:BaseUrl"]
                ?? "https://api.plugsky.com/v1")
        });
});

Do not put the key in appsettings.json or in the container image. Use the host's secret store, a managed identity that fetches the secret at startup, or an environment variable injected by the platform.

3. Stream tokens to the caller

Streaming matters for interactive tools: the user sees the first token instead of waiting for the whole answer. CompleteChatStreamingAsync returns an async collection of updates, and each update can contain zero or more content parts.

var messages = new List<ChatMessage>
{
    new SystemChatMessage("You review C# for correctness. Be brief."),
    new UserChatMessage("Review this method for null handling.")
};

await foreach (var update in chat.CompleteChatStreamingAsync(
    messages, cancellationToken: ct))
{
    foreach (var part in update.ContentUpdate)
        await response.WriteAsync(part.Text, ct);
}

In ASP.NET Core, disable response buffering and flush after each write. If the client disconnects, the cancellation token stops the upstream request. That also stops billing for the unused remainder where the provider supports cancellation.

4. Add tool calls

Tool calling is a loop, not a single request. Define the tool with a JSON Schema, send it in ChatCompletionOptions, execute any requested function, then append a ToolChatMessage with the matching call ID. Repeat until FinishReason is Stop.

var tool = ChatTool.CreateFunctionTool(
    functionName: "get_build_status",
    functionDescription: "Return the latest build status for a repository.",
    functionParameters: BinaryData.FromString("""
    {
      "type": "object",
      "properties": { "repo": { "type": "string" } },
      "required": ["repo"],
      "additionalProperties": false
    }
    """));

var chatOptions = new ChatCompletionOptions { Tools = { tool } };
var completion = await chat.CompleteChatAsync(messages, chatOptions, ct);

Validate arguments before you run anything. The model can invent a repository name, a path or an ID. Treat every tool argument as untrusted input and check it against your own allowlist. Cap the loop as well: a model that keeps calling the same tool should fail closed, not spin.

5. Retries, timeouts and Polly

The SDK already retries 408, 429, 500, 502, 503 and 504 up to three additional times with exponential backoff. Do not stack a second retry policy on top; you will multiply traffic during an outage. Use Polly for what the SDK does not do: a circuit breaker, a per-operation deadline and metrics. If you must retry a whole multi-step tool workflow at the application layer, give it an idempotency key and a longer backoff rather than wrapping the single SDK call in both policies.

using Polly;
using Polly.CircuitBreaker;

var breaker = new ResiliencePipelineBuilder()
    .AddCircuitBreaker(new CircuitBreakerStrategyOptions
    {
        FailureRatio = 0.5,
        MinimumThroughput = 10,
        SamplingDuration = TimeSpan.FromSeconds(30),
        BreakDuration = TimeSpan.FromSeconds(15)
    })
    .Build();

var reply = await breaker.ExecuteAsync(
    async token => await chat.CompleteChatAsync(messages, cancellationToken: token),
    ct);
FailureWhat to do
401 or 403Check the key and the Authorization header; do not retry.
404Check the base URL and model ID; a duplicated path is the usual cause.
429Back off, reduce concurrency, and check the plan's requests-per-minute limit.
5xxRetry with jitter, then open the circuit breaker.
Stream stallsApply an idle timeout; cancel and report a partial answer.

6. Test without spending tokens

Split the code into a pure prompt builder and a thin client wrapper. The builder is easy to unit test: assert the system message, the tool schema and the token budget without a network call. For the wrapper, the SDK marks client methods virtual and provides model factories, so you can mock ChatClient with Moq or substitute an HttpMessageHandler through HttpClientPipelineTransport.

[Fact]
public void Prompt_includes_repo_and_branch()
{
    var messages = PromptBuilder.ForReview("plugsky/api", "main");
    Assert.Contains(messages, m => m is SystemChatMessage);
    Assert.Contains("main", messages.OfType<UserChatMessage>().Single().Content[0].Text);
}

Keep one integration test that runs only when PLUGSKY_API_KEY is present, and mark it as a separate category so CI does not call a paid endpoint on every pull request. In production, log the model ID, endpoint, latency and token usage for every request. The SDK supports experimental OpenTelemetry tracing and metrics; even a simple structured log makes it possible to distinguish a provider outage from a prompt regression. Never log the API key or the full prompt if it contains customer data.

For the raw HTTP shape, see the OpenAI-compatible API guide; for a first request in another language, use the quickstart; for plan limits, see pricing.

FAQ

Does the OpenAI .NET SDK work with a non-OpenAI endpoint?

Yes. Pass an ApiKeyCredential and set OpenAIClientOptions.Endpoint to the provider's base URL, such as https://api.plugsky.com/v1. The SDK appends the resource paths, so do not include /chat/completions in the endpoint.

Which model ID should I use?

Use an ID from the provider's /v1/models response. On Plugsky, plugsky-coder is a 262,144-context coding model with tool support; plugsky-coder-fast trades output length for speed.

Is ChatClient thread-safe?

Yes. Register it as a singleton in ASP.NET Core and reuse it. Create separate clients only when you need different models or endpoints.

Does the SDK retry failed requests?

It retries 408, 429, 500, 502, 503 and 504 up to three additional times with exponential backoff. Add a Polly circuit breaker rather than a second retry policy.

How do I test without calling the API?

Unit-test the prompt builder, mock ChatClient or its transport, and gate one integration test behind an environment variable such as PLUGSKY_API_KEY.

Sources checked 20 November 2026: OpenAI .NET SDK README; Microsoft dependency injection; Polly circuit breaker. Product behavior, endpoint support and plan limits can change; re-check the primary documentation before production rollout.