Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.

# Aurora DSQL-Konnektor für.NET Npgsql
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql"></a>

Der [Aurora DSQL Connector for .NET ist ein auf [Npgsql](https://www.npgsql.org/)](https://github.com/awslabs/aurora-dsql-connectors/tree/main/dotnet/npgsql) basierender .NET-Connector, der die IAM-Authentifizierung für die Verbindung von.NET-Anwendungen mit Amazon Aurora DSQL-Clustern integriert.

Der Connector kümmert sich um die Token-Generierung, die SSL-Konfiguration und das Verbindungspooling, sodass Sie sich auf Ihre Anwendungslogik konzentrieren können.

## Über den Konnektor
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-about"></a>

Amazon Aurora DSQL erfordert eine IAM-Authentifizierung mit zeitlich begrenzten Token, die vorhandene.NET-PostgreSQL-Treiber nicht nativ unterstützen. Der Aurora DSQL Connector for .NET fügt zusätzlich zu Npgsql eine Authentifizierungsebene hinzu, die die IAM-Token-Generierung übernimmt, sodass Sie eine Verbindung zu Aurora DSQL herstellen können, ohne Ihre bestehenden Npgsql-Workflows zu ändern.

### Was ist Aurora DSQL-Authentifizierung?
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-authentication"></a>

In Aurora DSQL umfasst die **Authentifizierung**:
+ **IAM-Authentifizierung**: alle Verbindungen verwenden eine IAM-basierte Authentifizierung mit zeitlich begrenzten Token
+ **Token-Generierung**: Der Connector generiert Authentifizierungstoken mithilfe von AWS Anmeldeinformationen, und diese Token haben eine konfigurierbare Lebensdauer

Der Aurora DSQL Connector for .NET versteht diese Anforderungen und generiert beim Verbindungsaufbau automatisch IAM-Authentifizierungstoken.

### Features
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-features"></a>
+ **Automatische IAM-Authentifizierung** — Übernimmt die Generierung und Aktualisierung von Aurora DSQL-Tokens
+ **Basiert auf Npgsql** — Umschließt den beliebten PostgreSQL-Treiber für.NET
+ **Nahtlose Integration** — Funktioniert mit bestehenden Npgsql-Workflows
+ **Verbindungspooling** — Integrierte Unterstützung `NpgsqlDataSource` mit maximaler Nutzungsdauer
+ **Automatische Erkennung von Regionen** — Extrahiert die AWS Region aus dem Hostnamen des Aurora DSQL-Clusters
+ **AWS Unterstützung für Anmeldeinformationen** — Unterstützt AWS Profile und Anbieter von benutzerdefinierten Anmeldeinformationen
+ **OCC-Wiederholung** — Opt-In für optimistische Parallelitätssteuerung mit exponentiellem Backoff
+ **SSL-Durchsetzung** — Verwendet immer SSL mit Modus und direkter TLS-Aushandlung `verify-full`

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

Ein vollständiges Beispiel finden Sie in der [Beispielanwendung](https://github.com/awslabs/aurora-dsql-connectors/tree/main/dotnet/npgsql/example) unter GitHub.

## Schnellstart-Anleitung
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-quick-start"></a>

### Voraussetzungen
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-requirements"></a>
+ .NET 8.0 oder höher
+ [Zugriff auf einen Aurora DSQL-Cluster](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/getting-started.html)
+ AWS konfigurierte Anmeldeinformationen (über AWS CLI, Umgebungsvariablen oder IAM-Rollen)

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

Fügen Sie das Paket zu Ihrem Projekt hinzu:

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

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

### Verbindung zum Pool
<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();
});
```

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

Für einfache Skripte oder wenn Sie kein Verbindungspooling benötigen:

```
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-Versuch wiederholen
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-occ-retry"></a>

Aurora DSQL verwendet Optimistic Concurrency Control (OCC). Wenn zwei Transaktionen dieselben Daten ändern, gewinnt die erste Transaktion, die einen Commit durchführt, und die zweite erhält einen OCC-Fehler.

Die OCC-Wiederholung ist optional. `OccMaxRetries`In der Konfiguration so eingestellt, dass automatische Wiederholungen mit exponentiellem Backoff und Jitter aktiviert werden. Für transaktionale Schreibvorgänge verwenden: `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();
});
```

Verwenden Sie für DDL- oder Einzelanweisungen: `ExecWithRetryAsync`

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

**Wichtig**  
`WithTransactionRetryAsync`verwaltet`BEGIN`/`COMMIT`/`ROLLBACK`intern und öffnet für jeden Versuch eine neue Verbindung. Ihr Rückruf sollte nur Datenbankoperationen enthalten und sicher sein, dass Sie es erneut versuchen können.

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

Der Konnektor akzeptiert auch `postgresql://` Verbindungszeichenfolgen mit `postgres://` `region` und `profile` Abfrageparametern.


| Feld | Typ | Standard | Description | 
| --- | --- | --- | --- | 
| Host | string | (erforderlich) | Cluster-Endpunkt oder Cluster-ID mit 26 Zeichen | 
| Region | string? | (automatisch erkannt) | AWS Region; erforderlich, wenn Host es sich um eine Cluster-ID handelt | 
| User | string | "admin" | Datenbankbenutzer | 
| Database | string | "postgres" | Datenbankname | 
| Port | int | 5432 | Datenbankport | 
| Profile | string? | null | AWS Profilname für Anmeldeinformationen | 
| CustomCredentialsProvider | AWSCredentials? | null | Anbieter AWS für benutzerdefinierte Anmeldeinformationen | 
| TokenDurationSecs | int? | null(SDK-Standard, 900s) | Gültigkeitsdauer des Tokens in Sekunden | 
| OccMaxRetries | int? | null(deaktiviert) | Standardmäßige maximale Anzahl an OCC-Wiederholungen für Wiederholungsmethoden in der Datenquelle | 
| OrmPrefix | string? | null | ORM-Präfix wird vorangestellt application\_name | 
| LoggerFactory | ILoggerFactory? | null | Logger-Fabrik für Wiederholungswarnungen und Diagnosen | 
| ConfigureConnectionString | Action<NpgsqlConnectionStringBuilder>? | null | Callback, um Pool-Einstellungen zu überschreiben oder zusätzliche Eigenschaften der Npgsql-Verbindungszeichenfolge festzulegen. SSL und Enlist sind Sicherheitsinvarianten und können nicht außer Kraft gesetzt werden. | 

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

Der Connector verarbeitet automatisch die Aurora-DSQL-Authentifizierung, indem er mithilfe von AWS Anmeldeinformationen Token generiert. Wenn Sie die AWS Region nicht angeben, analysiert der Connector sie anhand des Hostnamens.

Weitere Informationen zur Authentifizierung in Aurora DSQL finden Sie unter[Authentifizierung und Autorisierung für Aurora DSQL](authentication-authorization.md).

### Admin im Vergleich zu normalen Benutzern
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-admin-vs-regular"></a>
+ Benutzer mit dem Namen „admin“ verwenden automatisch Admin-Authentifizierungstoken
+ Alle anderen Benutzer verwenden reguläre Authentifizierungstoken
+ Der Connector generiert dynamisch Token für jede Verbindung