Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

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

L'[Aurora DSQL Connector for .NET è un connettore.NET](https://github.com/awslabs/aurora-dsql-connectors/tree/main/dotnet/npgsql) basato su [Npgsql](https://www.npgsql.org/) che integra l'autenticazione IAM per connettere applicazioni.NET ai cluster DSQL di Amazon Aurora.

Il connettore gestisce la generazione di token, la configurazione SSL e il pool di connessioni in modo da poterti concentrare sulla logica dell'applicazione.

## Informazioni sul connettore
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-about"></a>

Amazon Aurora DSQL richiede l'autenticazione IAM con token a tempo limitato che i driver.NET PostgreSQL esistenti non supportano nativamente. L'Aurora DSQL Connector for .NET aggiunge un livello di autenticazione a Npgsql che gestisce la generazione di token IAM, consentendoti di connetterti ad Aurora DSQL senza modificare i flussi di lavoro Npgsql esistenti.

### Cos'è l'autenticazione Aurora SQL?
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-authentication"></a>

In Aurora DSQL, l’**autenticazione** prevede:
+ **Autenticazione IAM:** tutte le connessioni utilizzano l’autenticazione basata su IAM con token a tempo limitato
+ **Generazione di token**: il connettore genera token di autenticazione utilizzando AWS credenziali e questi token hanno una durata configurabile

L'Aurora DSQL Connector for .NET comprende questi requisiti e genera automaticamente token di autenticazione IAM quando si stabiliscono connessioni.

### Funzionalità
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-features"></a>
+ **Autenticazione IAM automatica**: gestisce la generazione e l'aggiornamento dei token Aurora DSQL
+ **Basato su Npgsql**: racchiude il popolare driver PostgreSQL per.NET
+ **Integrazione perfetta: funziona con i flussi di lavoro Npgsql esistenti**
+ **Connessione in pool - Supporto integrato tramite With** Max Lifetime Enforcement `NpgsqlDataSource`
+ **Rilevamento automatico della regione**: estrae la AWS regione dal nome host del cluster Aurora DSQL
+ AWS supporto per **le credenziali: supporta profili** e fornitori di credenziali personalizzate AWS 
+ **Riprova OCC: attiva un nuovo tentativo** ottimistico di controllo della concorrenza con backoff esponenziale
+ **Applicazione SSL: utilizza sempre SSL** con negoziazione TLS modale e diretta `verify-full`

## Applicazione di esempio
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-example-application"></a>

Per un esempio completo, vedi l'[applicazione di esempio](https://github.com/awslabs/aurora-dsql-connectors/tree/main/dotnet/npgsql/example) su GitHub.

## Guida rapida di avvio
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-quick-start"></a>

### Requisiti
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-requirements"></a>
+ .NET 8.0 o versione successiva
+ [Accesso a un cluster Aurora DSQL](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/getting-started.html)
+ AWS credenziali configurate (tramite AWS CLI, variabili di ambiente o ruoli IAM)

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

Aggiungi il pacchetto al tuo progetto:

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

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

### Connessione alla piscina
<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();
});
```

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

Per script semplici o quando non è necessario il pool di connessioni:

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

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

Aurora DSQL utilizza il controllo ottimistico della concorrenza (OCC). Quando due transazioni modificano gli stessi dati, la prima che esegue il commit vince e la seconda riceve un errore OCC.

Il nuovo tentativo OCC è facoltativo. Impostato `OccMaxRetries` nella configurazione per abilitare il nuovo tentativo automatico con backoff e jitter esponenziali. `WithTransactionRetryAsync`Uso per le scritture transazionali:

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

Per le istruzioni DDL o singole, usa: `ExecWithRetryAsync`

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

**Importante**  
`WithTransactionRetryAsync`gestisce`BEGIN`/`COMMIT`/`ROLLBACK`internamente e apre una nuova connessione per ogni tentativo. Il callback deve contenere solo le operazioni del database ed essere sicuro da riprovare.

## Opzioni di configurazione
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-configuration"></a>

Il connettore accetta anche stringhe `postgres://` di `postgresql://` connessione con `region` parametri di interrogazione. `profile`


| Campo | Tipo | Predefinita | Description | 
| --- | --- | --- | --- | 
| Host | string | (obbligatorio) | Endpoint del cluster o ID del cluster a 26 caratteri | 
| Region | string? | (rilevato automaticamente) | AWS regione; obbligatorio se Host è un ID del cluster | 
| User | string | "admin" | Utente del database | 
| Database | string | "postgres" | Nome del database | 
| Port | int | 5432 | Database port (Porta del database) | 
| Profile | string? | null | AWS nome del profilo per le credenziali | 
| CustomCredentialsProvider | AWSCredentials? | null | fornitore di AWS credenziali personalizzate | 
| TokenDurationSecs | int? | null(SDK predefinito, 900s) | Durata della validità del token in secondi | 
| OccMaxRetries | int? | null(disabilitato) | Numero massimo di tentativi OCC predefinito per i metodi di ripetizione sull'origine dati | 
| OrmPrefix | string? | null | Prefisso ORM preceduto da application\_name | 
| LoggerFactory | ILoggerFactory? | null | Logger Factory per avvisi e diagnosi di nuovi tentativi | 
| ConfigureConnectionString | Action<NpgsqlConnectionStringBuilder>? | null | Richiamata per sovrascrivere le impostazioni del pool o impostare proprietà aggiuntive della stringa di connessione Npgsql. SSL e Enlist sono invarianti di sicurezza e non possono essere sovrascritti. | 

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

Il connettore gestisce automaticamente l'autenticazione Aurora DSQL generando token utilizzando credenziali. AWS Se non fornite la AWS regione, il connettore la analizza a partire dal nome host.

Per ulteriori informazioni sull'autenticazione in Aurora DSQL, vedere. [Autenticazione e autorizzazione per Aurora DSQL](authentication-authorization.md)

### Amministratore e utenti normali
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-admin-vs-regular"></a>
+ Gli utenti denominati «admin» utilizzano automaticamente i token di autenticazione dell'amministratore
+ Tutti gli altri utenti utilizzano token di autenticazione regolari
+ Il connettore genera i token in modo dinamico per ogni connessione