# 使用 .NET 连接器连接到 Aurora DSQL 集群
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql"></a>

[Amazon 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 要求使用 IAM 身份验证以及限时令牌，而现有 .NET PostgreSQL 驱动程序并不原生支持这种方法。适用于 .NET 的 Aurora DSQL 连接器在 Npgsql 之上添加一个身份验证层来处理 IAM 令牌生成，使您无需更改现有 Npgsql 工作流程即可连接到 Aurora DSQL。

### 什么是 Aurora DSQL 身份验证？
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-authentication"></a>

在 Aurora DSQL 中，**身份验证**包括：
+ **IAM 身份验证**：所有连接都使用基于 IAM 的身份验证和限时令牌
+ **令牌生成**：连接器使用 AWS 凭证生成身份验证令牌，并且这些令牌具有可配置的生命周期

适用于 .NET 的 Aurora DSQL 连接器了解这些要求，并在建立连接时自动生成 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 强制执行**：始终在 `verify-full` 模式和直接 TLS 协商中使用 SSL

## 示例应用程序
<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
```

## 用法
<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>

连接器还通过 `region` 和 `profile` 查询参数接受 `postgres://` 和 `postgresql://` 连接字符串。


| 字段 | 类型 | 默认值 | 说明 | 
| --- | --- | --- | --- | 
| Host | string | （必需） | 集群端点或 26 个字符集群 ID | 
| Region | string? | （自动检测） | AWS 区域；如果 Host 是集群 ID，则为必需 | 
| User | string | "admin" | 数据库用户 | 
| Database | string | "postgres" | 数据库名称 | 
| Port | int | 5432 | 数据库端口 | 
| Profile | string? | null | 凭证的 AWS 配置文件名称 | 
| CustomCredentialsProvider | AWSCredentials? | null | 自定义 AWS 凭证提供商 | 
| TokenDurationSecs | int? | null（SDK 默认值，900 秒） | 令牌有效期，以秒为单位 | 
| OccMaxRetries | int? | null（已禁用） | 数据来源上重试方法的默认最大 OCC 重试次数 | 
| OrmPrefix | string? | null | 附加在 application\$1name 之前的 ORM 前缀 | 
| LoggerFactory | ILoggerFactory? | null | 用于重试警告和诊断的记录器工厂 | 
| ConfigureConnectionString | Action<NpgsqlConnectionStringBuilder>? | null | 回调以覆盖池设置，或设置其它 Npgsql 连接字符串属性。SSL 和 Enlist 是安全不变量，不能被覆盖。 | 

## 身份验证
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-auth"></a>

该连接器通过使用 AWS 凭证生成令牌来自动处理 Aurora DSQL 身份验证。如果您未提供 AWS 区域，则连接器会从主机名中解析该区域。

有关 Aurora DSQL 中的身份验证的更多信息，请参阅 [Aurora DSQL 的身份验证和授权](authentication-authorization.md)。

### 管理员用户与普通用户
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-admin-vs-regular"></a>
+ 名为“admin”的用户会自动使用管理员身份验证令牌
+ 所有其他用户都使用普通身份验证令牌
+ 该连接器为每个连接动态生成令牌