# Conector do Aurora DSQL para .NET Npgsql
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql"></a>

O [Conector do Aurora DSQL para .NET](https://github.com/awslabs/aurora-dsql-connectors/tree/main/dotnet/npgsql) é um conector .NET baseado em [Npgsql](https://www.npgsql.org/) que integra a autenticação do IAM para conectar aplicações .NET a clusters do Amazon Aurora DSQL.

O conector gerencia a geração de tokens, a configuração SSL e o agrupamento de conexões para que você se concentre na lógica da aplicação.

## Sobre o conector
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-about"></a>

O Amazon Aurora DSQL exige autenticação do IAM com tokens de tempo limitado para os quais os drivers PostgreSQL do .NET existentes não oferecem suporte nativo. O conector do Aurora DSQL para .NET adiciona uma camada de autenticação sobre o Npgsql que gerencia a geração de tokens do IAM, permitindo que você se conecte ao Aurora DSQL sem alterar seus fluxos de trabalho existentes do Npgsql.

### O que é a autenticação do Aurora DSQL?
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-authentication"></a>

Na autenticação do Aurora DSQL, a **autenticação** envolve:
+ **Autenticação do IAM**: todas as conexões usam autenticação baseada no IAM com tokens de tempo limitado.
+ **Geração de token**: o conector gera tokens de autenticação usando credenciais da AWS, e esses tokens têm vida útil configurável

O conector do Aurora DSQL para .NET entende esses requisitos e gera tokens de autenticação do IAM automaticamente ao estabelecer conexões.

### Recursos
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-features"></a>
+ **Autenticação automática do IAM:** lida com a geração e atualização de tokens do Aurora DSQL
+ **Desenvolvido em Npgsql:** agrupa o popular driver PostgreSQL para.NET
+ **Integração perfeita:** funciona com fluxos de trabalho de Npgsql existentes
+ **Agrupamento de conexões:** suporte integrado por meio do `NpgsqlDataSource` com aplicação de vida útil máxima
+ **Detecção automática de região:** extrai a região da AWS do nome de host do cluster do Aurora DSQL
+ **Suporte a credenciais da AWS:** aceita perfis e provedores de credenciais personalizados da AWS
+ **Nova tentativa de OCC:** opte por uma nova tentativa de controle de simultaneidade otimista com recuo exponencial
+ **Aplicação de SSL:** sempre usa SSL com o modo `verify-full` e negociação direta de TLS

## Aplicativo de exemplo
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-example-application"></a>

Para ver um exemplo completo, consulte a [aplicação de exemplo](https://github.com/awslabs/aurora-dsql-connectors/tree/main/dotnet/npgsql/example) no GitHub.

## Guia de início rápido
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-quick-start"></a>

### Requisitos
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-requirements"></a>
+ .NET 8.0 ou posterior
+ [Acesso a um cluster do Aurora DSQL](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/getting-started.html)
+ Credenciais da AWS configuradas (por meio da CLI da AWS, de variáveis de ambiente ou perfis do IAM)

## Instalação
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-installation"></a>

Adicione o pacote ao seu projeto:

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

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

### Conexão do grupo
<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();
});
```

### Conexão única
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-single-connection"></a>

Para scripts simples ou quando você não tem o agrupamento de conexões:

```
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();
```

### Nova tentativa de OCC
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-occ-retry"></a>

O Aurora DSQL usa o controle de simultaneidade otimista (OCC). Quando duas transações modificam os mesmos dados, a primeira a confirmar vence e a segunda recebe um erro de OCC.

A nova tentativa do OCC é opcional. Defina `OccMaxRetries` na configuração para ativar a nova tentativa automática com recuo exponencial e variação aleatória. Use `WithTransactionRetryAsync` para gravações transacionais:

```
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();
});
```

Para declarações DDL ou únicas, use `ExecWithRetryAsync`:

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

**Importante**  
`WithTransactionRetryAsync` gerencia `BEGIN`/`COMMIT`/`ROLLBACK` internamente e abre uma nova conexão para cada tentativa. Seu retorno de chamada deve conter somente operações de banco de dados e ser seguro tentar novamente.

## Opções de configuração
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-configuration"></a>

O conector também aceita strings de conexão `postgres://` e `postgresql://` com os parâmetros de consulta `region` e `profile`.


| Campo | Tipo | Padrão | Descrição | 
| --- | --- | --- | --- | 
| Host | string | (obrigatório) | Endpoint do cluster ou ID do cluster de 26 caracteres | 
| Region | string? | (detectado automaticamente) | Região da AWS; obrigatória se o Host for um ID de cluster | 
| User | string | "admin" | Usuário do banco de dados | 
| Database | string | "postgres" | Nome do banco de dados | 
| Port | int | 5432 | Porta do banco de dados | 
| Profile | string? | null | Nome do perfil da AWS para credenciais | 
| CustomCredentialsProvider | AWSCredentials? | null | Provedor de credenciais da AWS personalizadas | 
| TokenDurationSecs | int? | null (SDK padrão, 900s) | Duração da validade do token em segundos | 
| OccMaxRetries | int? | null (desabilitado) | Máximo padrão de novas tentativas de OCC para métodos de nova tentativa na fonte de dados | 
| OrmPrefix | string? | null | Prefixo ORM prefixado a application\_name | 
| LoggerFactory | ILoggerFactory? | null | Fábrica de loggers para novas tentativas, avisos e diagnósticos | 
| ConfigureConnectionString | Action<NpgsqlConnectionStringBuilder>? | null | Retorno de chamada para substituir as configurações do agrupamento ou definir propriedades adicionais da string de conexão Npgsql. SSL e Enlist são invariantes de segurança e não podem ser substituídos. | 

## Autenticação
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-auth"></a>

O conector gerencia automaticamente a autenticação do Aurora DSQL gerando tokens com o uso de credenciais da AWS. Se você não fornecer a região da AWS, o conector a analisará a partir do nome do host.

Para obter mais informações sobre autenticação no Aurora DSQL, consulte [Autenticação e autorização para o Aurora DSQL](authentication-authorization.md).

### Admin versus usuários regulares
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-admin-vs-regular"></a>
+ Usuários chamados “admin” utilizam automaticamente tokens de autenticação de admin.
+ Todos os outros usuários utilizam tokens de autenticação regulares.
+ O conector gera tokens dinamicamente para cada conexão