本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 適用於 .NET Npgsql 的 Aurora DSQL 連接器
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql"></a>

[Aurora DSQL Connector for .NET](https://github.com/awslabs/aurora-dsql-connectors/tree/main/dotnet/npgsql) 是建置在 [Npgsql](https://www.npgsql.org/) 上的 .NET 連接器，整合 IAM 身分驗證以將 .NET 應用程式連線至 Amazon Aurora DSQL 叢集。

連接器會處理字符產生、SSL 組態和連線集區，讓您可以專注於應用程式邏輯。

## 關於連接器
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-about"></a>

Amazon Aurora DSQL 需要使用現有 .NET PostgreSQL 驅動程式原生不支援的時間限制權杖進行 IAM 身分驗證。Aurora DSQL Connector for .NET 在處理 IAM 字符產生的 Npgsql 上新增了身分驗證層，可讓您連線到 Aurora DSQL，而無需變更現有的 Npgsql 工作流程。

### 什麼是 Aurora DSQL 身分驗證？
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-authentication"></a>

在 Aurora DSQL 中，**身分驗證**涉及：
+ **IAM 身分驗證**：所有連線都使用具有時間限制權杖的 IAM 型身分驗證
+ **權杖產生**：連接器使用 AWS 登入資料產生身分驗證權杖，這些權杖具有可設定的生命週期

Aurora DSQL Connector for .NET 了解這些需求，並在建立連線時自動產生 IAM 身分驗證字符。

### 功能
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-features"></a>
+ **自動 IAM 身分驗證** - 處理 Aurora DSQL 字符產生和重新整理
+ **以 Npgsql 為基礎** - 包裝適用於 .NET 的熱門 PostgreSQL 驅動程式
+ **無縫整合** - 適用於現有的 Npgsql 工作流程
+ **連線集區** - 透過 的內建支援`NpgsqlDataSource`與最長生命週期強制執行
+ **區域自動偵測** - 從 Aurora DSQL 叢集主機名稱擷取 AWS 區域
+ **AWS 憑證支援** - 支援 AWS 設定檔和自訂憑證提供者
+ **OCC 重試** - 選擇加入具有指數退避的樂觀並行控制重試
+ **SSL 強制執行** - 一律使用 SSL 搭配 `verify-full` 模式和直接 TLS 交涉

## 範例應用程式
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-example-application"></a>

如需完整範例，請參閱 GitHub 上的[範例應用程式](https://github.com/awslabs/aurora-dsql-connectors/tree/main/dotnet/npgsql/example)。

## 快速入門指南
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-quick-start"></a>

### 要求
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-requirements"></a>
+ .NET 8.0 或更新版本
+ [存取 Aurora DSQL 叢集](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/getting-started.html)
+ AWS 設定的登入資料 （透過 AWS CLI、環境變數或 IAM 角色）

## 安裝
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-installation"></a>

將套件新增至您的專案：

```
dotnet add package Amazon.AuroraDsql.Npgsql
```

## Usage
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-usage"></a>

### 集區連線
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-pool-connection"></a>

```
using Amazon.AuroraDsql.Npgsql;

// Create a connection pool
await using var ds = await AuroraDsql.CreateDataSourceAsync(new DsqlConfig
{
    Host = "your-cluster.dsql.us-east-1.on.aws",
    OccMaxRetries = 3
});

// Read
await using (var conn = await ds.OpenConnectionAsync())
{
    await using var cmd = conn.CreateCommand();
    cmd.CommandText = "SELECT 'Hello, DSQL!'";
    var greeting = await cmd.ExecuteScalarAsync();
    Console.WriteLine(greeting);
}

// Transactional write with OCC retry
await ds.WithTransactionRetryAsync(async conn =>
{
    await using var cmd = conn.CreateCommand();
    cmd.CommandText = "INSERT INTO users (id, name) VALUES (gen_random_uuid(), @name)";
    cmd.Parameters.AddWithValue("name", "Alice");
    await cmd.ExecuteNonQueryAsync();
});
```

### 單一連接
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-single-connection"></a>

對於簡單的指令碼或當您不需要連線集區時：

```
await using var conn = await AuroraDsql.ConnectAsync(new DsqlConfig
{
    Host = "your-cluster.dsql.us-east-1.on.aws"
});

await using var cmd = conn.CreateCommand("SELECT 1");
await cmd.ExecuteScalarAsync();
```

### OCC 重試
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-occ-retry"></a>

Aurora DSQL 使用樂觀並行控制 (OCC)。當兩個交易修改相同的資料時，第一個遞交獲勝，第二個收到 OCC 錯誤。

OCC 重試是選擇加入。在組態`OccMaxRetries`中設定 ，以啟用具有指數退避和抖動的自動重試。`WithTransactionRetryAsync` 用於交易寫入：

```
await ds.WithTransactionRetryAsync(async conn =>
{
    await using var cmd = conn.CreateCommand();

    cmd.CommandText = "UPDATE accounts SET balance = balance - 100 WHERE id = @from";
    cmd.Parameters.AddWithValue("from", fromId);
    await cmd.ExecuteNonQueryAsync();

    cmd.CommandText = "UPDATE accounts SET balance = balance + 100 WHERE id = @to";
    cmd.Parameters.Clear();
    cmd.Parameters.AddWithValue("to", toId);
    await cmd.ExecuteNonQueryAsync();
});
```

對於 DDL 或單一陳述式，請使用 `ExecWithRetryAsync`：

```
await ds.ExecWithRetryAsync("CREATE TABLE IF NOT EXISTS users (id UUID PRIMARY KEY, name TEXT)");
```

**重要**  
`WithTransactionRetryAsync` 會在內部管理 `BEGIN`/`COMMIT`/`ROLLBACK`，並在每次嘗試時開啟新的連線。您的回呼應僅包含資料庫操作，並且可以安全地重試。

## 組態選項
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-configuration"></a>

連接器也接受具有 `postgres://`和 `profile`查詢參數的 `region`和 `postgresql://`連線字串。


| 欄位 | Type | 預設 | Description | 
| --- | --- | --- | --- | 
| Host | string | （必要） | 叢集端點或 26 個字元的叢集 ID | 
| Region | string? | （自動偵測） | AWS region；如果 Host 是叢集 ID，則為必要 | 
| User | string | "admin" | 資料庫使用者 | 
| Database | string | "postgres" | 資料庫名稱 | 
| Port | int | 5432 | Database port (資料庫連線埠) | 
| Profile | string? | null | AWS 登入資料的設定檔名稱 | 
| CustomCredentialsProvider | AWSCredentials? | null | 自訂 AWS 登入資料提供者 | 
| TokenDurationSecs | int? | null (SDK 預設，900s) | 字符有效性持續時間，以秒為單位 | 
| OccMaxRetries | int? | null （已停用） | 資料來源上重試方法的預設 OCC 重試上限 | 
| OrmPrefix | string? | null | 前綴於 的 ORM 字首 application\_name | 
| LoggerFactory | ILoggerFactory? | null | 用於重試警告和診斷的記錄器工廠 | 
| ConfigureConnectionString | Action<NpgsqlConnectionStringBuilder>? | null | 回呼以覆寫集區設定或設定其他 Npgsql 連線字串屬性。SSL 和 Enlist是安全性變異，無法覆寫。 | 

## 身分驗證
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-auth"></a>

連接器會自動處理 Aurora DSQL 身分驗證，方法是使用 AWS 登入資料產生字符。如果您未提供區域，連接器會從主機名稱剖析該 AWS 區域。

如需 Aurora DSQL 中身分驗證的詳細資訊，請參閱 [Aurora DSQL 的身分驗證和授權](authentication-authorization.md)。

### 管理員與一般使用者
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-admin-vs-regular"></a>
+ 名為「admin」的使用者會自動使用管理員身分驗證字符
+ 所有其他使用者都使用一般身分驗證字符
+ 連接器會為每個連線動態產生字符