Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

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

Le [connecteur Aurora DSQL pour .NET](https://github.com/awslabs/aurora-dsql-connectors/tree/main/dotnet/npgsql) est un connecteur .NET basé sur [Npgsql](https://www.npgsql.org/) qui intègre l'authentification IAM pour connecter les applications .NET aux clusters Amazon Aurora DSQL.

Le connecteur gère la génération de jetons, la configuration SSL et le regroupement des connexions afin que vous puissiez vous concentrer sur la logique de votre application.

## À propos du connecteur
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-about"></a>

Amazon Aurora DSQL nécessite une authentification IAM avec des jetons à durée limitée que les pilotes .NET PostgreSQL existants ne prennent pas en charge de manière native. Le connecteur Aurora DSQL pour .NET ajoute une couche d'authentification au-dessus de Npgsql qui gère la génération de jetons IAM, vous permettant de vous connecter à Aurora DSQL sans modifier vos flux de travail Npgsql existants.

### Qu'est-ce que l'authentification SQL Aurora ?
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-authentication"></a>

Dans Aurora DSQL, **l’authentification** implique :
+ **Authentification IAM** : toutes les connexions utilisent l’authentification basée sur IAM avec des jetons à durée limitée
+ **Génération de jetons** : le connecteur génère des jetons d'authentification à l'aide AWS d'informations d'identification, et ces jetons ont une durée de vie configurable

Le connecteur Aurora DSQL pour .NET comprend ces exigences et génère automatiquement des jetons d'authentification IAM lors de l'établissement de connexions.

### Caractéristiques
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-features"></a>
+ **Authentification IAM automatique** : gère la génération et l'actualisation des jetons Aurora DSQL
+ **Construit sur Npgsql : intègre** le célèbre pilote PostgreSQL pour .NET
+ **Intégration fluide** - Fonctionne avec les flux de travail Npgsql existants
+ **Regroupement de connexions** - Support intégré via `NpgsqlDataSource` avec application de la durée de vie maximale
+ **Détection automatique des régions** : extrait AWS la région du nom d'hôte du cluster Aurora DSQL
+ **AWS support des identifiants** - Supporte les AWS profils et les fournisseurs d'identifiants personnalisés
+ **Nouvelle tentative OCC - Optez pour une nouvelle** tentative de contrôle de simultanéité optimiste avec un recul exponentiel
+ **Application du protocole SSL** : utilise toujours le protocole SSL avec `verify-full` mode et négociation directe du protocole TLS

## Exemple d'application
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-example-application"></a>

Pour un exemple complet, consultez l'[exemple d'application](https://github.com/awslabs/aurora-dsql-connectors/tree/main/dotnet/npgsql/example) sur GitHub.

## Guide de démarrage rapide
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-quick-start"></a>

### Exigences
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-requirements"></a>
+ .NET 8.0 ou version ultérieure
+ [Accès à un cluster SQL Aurora](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/getting-started.html)
+ AWS informations d'identification configurées (via la AWS CLI, les variables d'environnement ou les rôles IAM)

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

Ajoutez le package à votre projet :

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

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

### Connexion à la piscine
<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();
});
```

### Connexion simple
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-single-connection"></a>

Pour les scripts simples ou lorsque vous n'avez pas besoin d'un regroupement de connexions :

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

### Réessayer OCC
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-occ-retry"></a>

Aurora DSQL utilise un contrôle de simultanéité optimiste (OCC). Lorsque deux transactions modifient les mêmes données, la première à valider gagne et la seconde reçoit une erreur OCC.

Une nouvelle tentative d'OCC est facultative. Définissez `OccMaxRetries` la configuration pour activer la nouvelle tentative automatique avec un recul et une instabilité exponentiels. Utilisation `WithTransactionRetryAsync` pour les écritures transactionnelles :

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

Pour les instructions DDL ou uniques, utilisez `ExecWithRetryAsync` :

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

**Important**  
`WithTransactionRetryAsync`gère`BEGIN`/`COMMIT`/`ROLLBACK`en interne et ouvre une nouvelle connexion à chaque tentative. Votre rappel ne doit contenir que des opérations de base de données et vous pouvez réessayer en toute sécurité.

## Options de configuration
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-configuration"></a>

Le connecteur accepte `postgres://` et `postgresql://` connecte également des chaînes avec `region` des paramètres de `profile` requête.


| Champ | Type | Par défaut | Description | 
| --- | --- | --- | --- | 
| Host | string | (obligatoire) | Point de terminaison du cluster ou ID de cluster à 26 caractères | 
| Region | string? | (détecté automatiquement) | AWS région ; obligatoire s'il s'Hostagit d'un ID de cluster | 
| User | string | "admin" | Utilisateur de la base de donnée | 
| Database | string | "postgres" | Nom de la base de données | 
| Port | int | 5432 | Port de la base de données | 
| Profile | string? | null | AWS nom de profil pour les informations d'identification | 
| CustomCredentialsProvider | AWSCredentials? | null | Fournisseur AWS d'identifiants personnalisés | 
| TokenDurationSecs | int? | null(SDK par défaut, 900s) | Durée de validité du jeton en secondes | 
| OccMaxRetries | int? | null(handicapé) | Nombre maximal de tentatives OCC par défaut pour les méthodes de nouvelle tentative sur la source de données | 
| OrmPrefix | string? | null | préfixe ORM préfixé à application\_name | 
| LoggerFactory | ILoggerFactory? | null | Logger Factory pour les nouvelles tentatives, les avertissements et les diagnostics | 
| ConfigureConnectionString | Action<NpgsqlConnectionStringBuilder>? | null | Rappel pour annuler les paramètres du pool ou définir des propriétés de chaîne de connexion Npgsql supplémentaires. Les protocoles SSL Enlist sont des invariants de sécurité et ne peuvent pas être remplacés. | 

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

Le connecteur gère automatiquement l'authentification Aurora DSQL en générant des jetons à l'aide d' AWS informations d'identification. Si vous ne fournissez pas la AWS région, le connecteur l'analyse à partir du nom d'hôte.

Pour plus d'informations sur l'authentification dans Aurora DSQL, consultez[Authentification et autorisation pour Aurora DSQL](authentication-authorization.md).

### Administrateur et utilisateurs réguliers
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-admin-vs-regular"></a>
+ Les utilisateurs nommés « admin » utilisent automatiquement des jetons d'authentification d'administrateur
+ Tous les autres utilisateurs utilisent des jetons d'authentification ordinaires
+ Le connecteur génère des jetons de manière dynamique pour chaque connexion.