---
title: C# SDK
url: https://platform.claude.com/docs/zh-TW/cli-sdks-libraries/sdks/csharp
description: 安裝並設定 Anthropic C# SDK，以用於具備 IChatClient 整合的 .NET 應用程式
---

Anthropic C# SDK 讓以 C# 撰寫的應用程式能夠便利地存取 Claude API。

<Info>
  如需附有程式碼範例的 API 功能文件，請參閱 [API 參考](https://platform.claude.com/docs/zh-TW/api/overview)。本頁涵蓋 C# 專屬的 SDK 功能與設定。
</Info>

<Warning>
  自版本 10+ 起，`Anthropic` 套件現已成為 Anthropic 官方的 C# SDK。套件版本 3.X 及以下先前用於 tryAGI 社群建置的 SDK，該 SDK 已移至 [`tryAGI.Anthropic`](https://www.nuget.org/packages/tryagi.Anthropic/)。如果您需要在專案中繼續使用先前的用戶端，請將您的套件參考更新為 `tryAGI.Anthropic`。
</Warning>

## 安裝

從 [NuGet](https://www.nuget.org/packages/Anthropic) 安裝套件：

```bash
dotnet add package Anthropic
```

## 需求

此函式庫需要 .NET Standard 2.0 或更新版本。

## 使用方式

```csharp
using System;
using Anthropic;
using Anthropic.Models.Messages;

AnthropicClient client = new();

MessageCreateParams parameters = new()
{
    MaxTokens = 1024,
    Messages =
    [
        new()
        {
            Role = Role.User,
            Content = "Hello, Claude",
        },
    ],
    Model = Model.ClaudeOpus5_5,
};

var message = await client.Messages.Create(parameters);

foreach (var block in message.Content)
{
    if (block.TryPickText(out var textBlock))
    {
        Console.WriteLine(textBlock.Text);
    }
}
```

如需了解包括 Workload Identity Federation（工作負載身分聯合）在內的驗證選項，請參閱[驗證](https://platform.claude.com/docs/zh-TW/manage-claude/authentication)。如果您的 API 金鑰是可存取多個工作區的[個人或服務帳戶金鑰](https://platform.claude.com/docs/zh-TW/manage-claude/authentication#key-types)，請在 `anthropic-workspace-id` 請求標頭中設定工作區 ID；[選擇工作區](https://platform.claude.com/docs/zh-TW/manage-claude/authentication#select-a-workspace)說明了此 SDK 的逐請求選項。

## 用戶端設定

使用環境變數設定用戶端：

```csharp
using Anthropic;

// 使用 ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN 與 ANTHROPIC_BASE_URL 環境變數進行設定
AnthropicClient client = new();
```

或手動設定：

```csharp
using Anthropic;

AnthropicClient client = new() { ApiKey = "my-anthropic-api-key" };
```

或結合使用這兩種方式。

可用選項請參閱下表：

| 屬性          | 環境變數                   | 必填    | 預設值                           |
| ----------- | ---------------------- | ----- | ----------------------------- |
| `ApiKey`    | `ANTHROPIC_API_KEY`    | false | -                             |
| `AuthToken` | `ANTHROPIC_AUTH_TOKEN` | false | -                             |
| `BaseUrl`   | `ANTHROPIC_BASE_URL`   | true  | `"https://api.anthropic.com"` |

### 修改設定

若要暫時使用修改過的用戶端設定，同時重複使用相同的連線與執行緒集區，請在任何用戶端或服務上呼叫 `WithOptions`：

```csharp
using System;

var message = await client
    .WithOptions(options =>
        options with
        {
            BaseUrl = "https://example.com",
            Timeout = TimeSpan.FromSeconds(42),
        }
    )
    .Messages.Create(parameters);

Console.WriteLine(message);
```

使用 [`with` 運算式](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/operators/with-expression)可以輕鬆建構修改後的選項。

`WithOptions` 方法不會影響原始的用戶端或服務。

## 串流

SDK 定義了會回傳回應「區塊」（chunk）串流的方法，每個區塊一抵達即可個別處理，而不必等待完整回應。「Streaming」（串流）方法通常對應於 [SSE](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) 或 [JSONL](https://jsonlines.org) 回應。

串流方法的名稱一律帶有 `Streaming` 後綴，即使它沒有非串流的變體也是如此。

這些串流方法會回傳 [`IAsyncEnumerable`](https://learn.microsoft.com/en-us/dotnet/api/system.collections.generic.iasyncenumerable-1)：

```csharp
using System;
using Anthropic.Models.Messages;

MessageCreateParams parameters = new()
{
    MaxTokens = 1024,
    Messages =
    [
        new()
        {
            Role = Role.User,
            Content = "Hello, Claude",
        },
    ],
    Model = Model.ClaudeOpus5_5,
};

await foreach (var message in client.Messages.CreateStreaming(parameters))
{
    Console.WriteLine(message);
}
```

## 錯誤處理

SDK 會擲出自訂的非受檢（unchecked）例外類型：

* `AnthropicApiException`：API 錯誤的基底類別。各 HTTP 狀態碼所擲出的例外子類別請參閱下表：

| 狀態碼 | 例外                                       |
| --- | ---------------------------------------- |
| 400 | `AnthropicBadRequestException`           |
| 401 | `AnthropicUnauthorizedException`         |
| 403 | `AnthropicForbiddenException`            |
| 404 | `AnthropicNotFoundException`             |
| 422 | `AnthropicUnprocessableEntityException`  |
| 429 | `AnthropicRateLimitException`            |
| 5xx | `Anthropic5xxException`                  |
| 其他  | `AnthropicUnexpectedStatusCodeException` |

此外，所有 4xx 錯誤皆繼承自 `Anthropic4xxException`。

* `AnthropicSseException`：在初始 HTTP 回應成功之後，於 SSE 串流期間遇到錯誤時擲出。

* `AnthropicIOException`：I/O 網路錯誤。

* `AnthropicInvalidDataException`：無法解讀已成功剖析的資料。例如，存取一個應為必填的屬性，但 API 卻意外地在回應中省略了它。

* `AnthropicException`：所有例外的基底類別。

## 重試

SDK 預設會自動重試 2 次，並在請求之間採用短暫的指數退避（exponential backoff）。

僅會重試下列錯誤類型：

* 連線錯誤（例如因網路連線問題所致）
* 408 Request Timeout
* 409 Conflict
* 429 Rate Limit
* 5xx 內部錯誤

API 也可能明確指示 SDK 重試或不重試某個請求。

若要設定自訂的重試次數，請使用 `MaxRetries` 屬性設定用戶端：

```csharp
using Anthropic;

AnthropicClient client = new() { MaxRetries = 3 };
```

或使用 `WithOptions` 設定單一方法呼叫：

```csharp
using System;

var message = await client
    .WithOptions(options =>
        options with { MaxRetries = 3 }
    )
    .Messages.Create(parameters);

Console.WriteLine(message);
```

## 逾時

請求預設在 10 分鐘後逾時。

若要設定自訂逾時，請使用 `Timeout` 選項設定用戶端：

```csharp
using System;
using Anthropic;

AnthropicClient client = new() { Timeout = TimeSpan.FromSeconds(42) };
```

或使用 `WithOptions` 設定單一方法呼叫：

```csharp
using System;

var message = await client
    .WithOptions(options =>
        options with { Timeout = TimeSpan.FromSeconds(42) }
    )
    .Messages.Create(parameters);

Console.WriteLine(message);
```

## 分頁

SDK 定義了會回傳分頁結果清單的方法。它提供便利的方式，讓您可以一次存取一頁結果，或跨所有頁面逐項存取結果。

### 自動分頁

若要遍歷所有頁面的全部結果，請使用 `Paginate` 方法，它會視需要自動擷取更多頁面。此方法會回傳 [`IAsyncEnumerable`](https://learn.microsoft.com/en-us/dotnet/api/system.collections.generic.iasyncenumerable-1)：

```csharp
using System;

var page = await client.Messages.Batches.List(parameters);
await foreach (var item in page.Paginate())
{
    Console.WriteLine(item);
}
```

### 手動分頁

若要存取個別頁面的項目並手動請求下一頁，請使用 `Items` 屬性，以及 `HasNext` 與 `Next` 方法：

```csharp
var page = await client.Messages.Batches.List();
while (true)
{
    foreach (var item in page.Items)
    {
        Console.WriteLine(item);
    }
    if (!page.HasNext())
    {
        break;
    }
    page = await page.Next();
}
```

## 回應驗證

在極少數情況下，API 可能會回傳與預期類型不符的回應。預設情況下，SDK 在此情況下不會擲出例外。只有在您直接存取該屬性時，它才會擲出 `AnthropicInvalidDataException`。

如果您希望事先檢查回應是否完全符合類型，可以呼叫 `Validate`：

```csharp
var message = await client.Messages.Create(parameters);
message.Validate();
```

或使用 `ResponseValidation` 選項設定用戶端：

```csharp
using Anthropic;

AnthropicClient client = new() { ResponseValidation = true };
```

或使用 `WithOptions` 設定單一方法呼叫：

```csharp
using System;

var message = await client
    .WithOptions(options =>
        options with { ResponseValidation = true }
    )
    .Messages.Create(parameters);

Console.WriteLine(message);
```

## IChatClient 整合

SDK 提供了 `Microsoft.Extensions.AI.Abstractions` 函式庫中 `IChatClient` 介面的實作。這使得 `AnthropicClient`（以及 `Anthropic.Services.IBetaService`）能夠與其他整合這些核心抽象的函式庫搭配使用。例如，MCP C# SDK（`ModelContextProtocol`）函式庫中的工具可以直接與透過 `IChatClient` 公開的 `AnthropicClient` 搭配使用。

```csharp
using Anthropic;
using Microsoft.Extensions.AI;
using ModelContextProtocol.Client;

// 使用 ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN 與 ANTHROPIC_BASE_URL 環境變數進行設定
AnthropicClient client = new();

IChatClient chatClient = client.AsIChatClient("claude-opus-5-5")
    .AsBuilder()
    .UseFunctionInvocation()
    .Build();

// 使用 MCP C# SDK 中的 McpClient
McpClient learningServer = await McpClient.CreateAsync(
    new HttpClientTransport(new() { Endpoint = new("https://learn.microsoft.com/api/mcp") }));

ChatOptions options = new() { Tools = [.. await learningServer.ListToolsAsync()] };

Console.WriteLine(await chatClient.GetResponseAsync("Tell me about IChatClient", options));
```

## 請求與回應

若要向 Claude API 傳送請求，請建構一個 `Params` 類別的實例，並將其傳遞給對應的用戶端方法。收到回應後，它會被反序列化為 C# 類別的實例。

例如，`client.Messages.Create` 應以 `MessageCreateParams` 的實例呼叫，並會回傳 `Task<Message>` 的實例。

## 進階用法

### 二進位回應

SDK 定義了會回傳二進位回應的方法，用於不一定需要剖析的 API 回應，例如非 JSON 資料。

這些方法會回傳 `HttpResponse`：

```csharp
using System;
using Anthropic.Models.Files;

FileDownloadParams parameters = new() { FileID = "file_id" };

var response = await client.Files.Download(parameters);

Console.WriteLine(response);
```

若要將回應內容儲存至檔案或任何 [`Stream`](https://learn.microsoft.com/en-us/dotnet/api/system.io.stream)，請使用 [`CopyToAsync`](https://learn.microsoft.com/en-us/dotnet/api/system.io.stream.copytoasync) 方法：

```csharp
using System.IO;

using var response = await client.Files.Download(parameters);
using var contentStream = await response.ReadAsStream();
using var fileStream = File.Open(path, FileMode.OpenOrCreate);
await contentStream.CopyToAsync(fileStream); // Or any other Stream
```

### 原始回應

SDK 定義了會將回應反序列化為 C# 類別實例的方法。若要存取回應標頭、狀態碼或原始回應主體，請在用戶端或服務上的任何 HTTP 方法呼叫前加上 `WithRawResponse`：

```csharp
var response = await client.WithRawResponse.Messages.Create(parameters);
var statusCode = response.StatusCode;
var headers = response.Headers;
```

原始的 `HttpResponseMessage` 也可以透過 `RawMessage` 屬性存取。

對於非串流回應，您可以視需要將回應反序列化為 C# 類別的實例：

```csharp
using System;
using Anthropic.Models.Messages;

var response = await client.WithRawResponse.Messages.Create(parameters);
Message deserialized = await response.Deserialize();
Console.WriteLine(deserialized);
```

對於串流回應，您可以視需要將回應反序列化為 `IAsyncEnumerable`：

```csharp
using System;

var response = await client.WithRawResponse.Messages.CreateStreaming(parameters);
await foreach (var item in response.Enumerate())
{
    Console.WriteLine(item);
}
```

### 日誌記錄

<Warning>
  所有日誌訊息僅供除錯使用。日誌訊息的格式與內容可能會在不同版本之間有所變更。
</Warning>

透過設定環境變數來啟用除錯日誌記錄：

```bash
export ANTHROPIC_LOG=debug
```

### 未記載的 API 功能

SDK 具備型別定義，以便於使用已記載的 API。不過，它也支援使用 API 中未記載或尚未支援的部分。

## 平台整合

<Note>
  如需附有程式碼範例的詳細平台設定指南，請參閱：

  * [Amazon Bedrock](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-in-amazon-bedrock)
  * [Amazon Bedrock（Opus 4.6 及更早版本）](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-on-amazon-bedrock-legacy)
  * [Claude Platform on AWS](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-platform-on-aws)
  * [Google Cloud](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-on-vertex-ai)
  * [Microsoft Foundry](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-in-microsoft-foundry)
</Note>

C# SDK 透過個別的 NuGet 套件支援下列平台：

* **Agent Platform：** `Anthropic.Vertex`。用戶端設定請參閱 [Google Cloud 上的 Claude](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-on-vertex-ai)。
* **Bedrock：** `Anthropic.Bedrock`。針對 Messages-API Bedrock 端點請使用 `AnthropicBedrockMantleClient`，或使用 `AnthropicBedrockClient`（`bedrock-runtime` 路徑）。`AnthropicBedrockMantleClient` 接受一個選用的 `MantleAwsClientOptions` 設定物件；`AnthropicBedrockClient` 接受 `AnthropicBedrockCredentialsHelper.FromEnv()` 或明確的憑證。
* **Claude Platform on AWS：** `Anthropic.Aws`。請使用 `AnthropicAwsClient`；在用戶端上設定 `WorkspaceId`，或設定 `ANTHROPIC_AWS_WORKSPACE_ID` 環境變數（請參閱[工作區](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-platform-on-aws#workspaces)）。目前以 beta 形式提供。
* **Foundry：** `Anthropic.Foundry`。請搭配 `DefaultAnthropicFoundryCredentials.FromEnv()` 或明確的憑證使用 `AnthropicFoundryClient`。

新專案請使用 `AnthropicBedrockMantleClient`；`AnthropicBedrockClient` 則保留給使用 Bedrock `InvokeModel` API 的既有應用程式。

## 語意化版本

此套件大致遵循 [SemVer](https://semver.org/spec/v2.0.0.html) 慣例，但某些不向後相容的變更可能會以次要版本發布：

1. 對函式庫內部的變更，這些內部在技術上是公開的，但並非預期供外部使用，也未針對外部使用加以記載。
2. 預期在實務上不會影響絕大多數使用者的變更。

我們非常重視向後相容性，以確保您能仰賴順暢的升級體驗。

## 其他資源

* [GitHub 儲存庫](https://github.com/anthropics/anthropic-sdk-csharp)
* [NuGet 套件](https://www.nuget.org/packages/Anthropic)
* [API 參考](https://platform.claude.com/docs/zh-TW/api/overview)
* [串流訊息](https://platform.claude.com/docs/zh-TW/build-with-claude/streaming)