Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

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

Konektor [Aurora DSQL untuk .NET adalah konektor.NET](https://github.com/awslabs/aurora-dsql-connectors/tree/main/dotnet/npgsql) yang dibangun di atas [Npgsql yang mengintegrasikan otentikasi IAM untuk menghubungkan aplikasi.NET ke cluster Amazon Aurora DSQL](https://www.npgsql.org/).

Konektor menangani pembuatan token, konfigurasi SSL, dan penyatuan koneksi sehingga Anda dapat fokus pada logika aplikasi Anda.

## Tentang konektornya
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-about"></a>

Amazon Aurora DSQL memerlukan otentikasi IAM dengan token terbatas waktu yang tidak didukung oleh driver.NET PostgreSQL yang ada. Konektor Aurora DSQL untuk.NET menambahkan lapisan otentikasi di atas Npgsql yang menangani pembuatan token IAM, memungkinkan Anda untuk terhubung ke Aurora DSQL tanpa mengubah alur kerja Npgsql yang ada.

### Apa itu otentikasi Aurora DSQL?
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-authentication"></a>

**Dalam Aurora DSQL, otentikasi melibatkan:**
+ **Otentikasi IAM**: Semua koneksi menggunakan otentikasi berbasis IAM dengan token terbatas waktu
+ **Generasi Token**: Konektor menghasilkan token otentikasi menggunakan AWS kredensyal, dan token ini memiliki masa pakai yang dapat dikonfigurasi

Konektor Aurora DSQL untuk.NET memahami persyaratan ini dan secara otomatis menghasilkan token otentikasi IAM saat membuat koneksi.

### Fitur
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-features"></a>
+ **Otentikasi IAM otomatis** - Menangani pembuatan dan penyegaran token Aurora DSQL
+ **Dibangun di Npgsql - Membungkus driver PostgreSQL** populer untuk.NET
+ **Integrasi mulus** - Bekerja dengan alur kerja Npgsql yang ada
+ **Penggabungan koneksi** - Dukungan bawaan melalui `NpgsqlDataSource` dengan penegakan seumur hidup maksimal
+ **Deteksi otomatis wilayah** - Ekstrak AWS wilayah dari nama host cluster Aurora DSQL
+ AWS dukungan **kredensyal - Mendukung** AWS profil dan penyedia kredensyal khusus
+ Coba lagi **OCC - Coba lagi kontrol** konkurensi optimis dengan backoff eksponensial
+ **Penegakan SSL** - Selalu menggunakan SSL dengan `verify-full` mode dan negosiasi TLS langsung

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

Untuk contoh lengkap, lihat [contoh aplikasi](https://github.com/awslabs/aurora-dsql-connectors/tree/main/dotnet/npgsql/example) di GitHub.

## Panduan memulai cepat
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-quick-start"></a>

### Persyaratan
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-requirements"></a>
+ .NET 8.0 atau yang lebih baru
+ [Akses ke cluster Aurora DSQL](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/getting-started.html)
+ AWS kredensyal yang dikonfigurasi (melalui AWS CLI, variabel lingkungan, atau peran IAM)

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

Tambahkan paket ke proyek Anda:

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

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

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

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

Untuk skrip sederhana atau saat Anda tidak memerlukan penyatuan koneksi:

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

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

Aurora DSQL menggunakan kontrol konkurensi optimis (OCC). Ketika dua transaksi memodifikasi data yang sama, yang pertama melakukan kemenangan dan yang kedua menerima kesalahan OCC.

Coba lagi OCC adalah opt-in. Setel `OccMaxRetries` dalam konfigurasi untuk mengaktifkan percobaan ulang otomatis dengan backoff eksponensial dan jitter. Gunakan `WithTransactionRetryAsync` untuk penulisan transaksional:

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

Untuk pernyataan DDL atau tunggal, gunakan`ExecWithRetryAsync`:

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

**penting**  
`WithTransactionRetryAsync`mengelola`BEGIN`/`COMMIT`/`ROLLBACK`secara internal dan membuka koneksi baru untuk setiap upaya. Callback Anda seharusnya hanya berisi operasi database dan aman untuk dicoba lagi.

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

Konektor juga menerima `postgres://` dan `postgresql://` menghubungkan string dengan `region` dan `profile` parameter kueri.


| Bidang | Tipe | Default | Deskripsi | 
| --- | --- | --- | --- | 
| Host | string | (wajib) | Titik akhir cluster atau ID cluster 26-char | 
| Region | string? | (terdeteksi secara otomatis) | AWS wilayah; diperlukan jika Host adalah ID cluster | 
| User | string | "admin" | Pengguna basis data | 
| Database | string | "postgres" | Nama basis data | 
| Port | int | 5432 | Port basis data | 
| Profile | string? | null | AWS nama profil untuk kredensyal | 
| CustomCredentialsProvider | AWSCredentials? | null | Penyedia AWS kredensyal kustom | 
| TokenDurationSecs | int? | null(SDK default, 900-an) | Durasi validitas token dalam hitungan detik | 
| OccMaxRetries | int? | null(dinonaktifkan) | Percobaan ulang OCC maks default untuk metode coba lagi pada sumber data | 
| OrmPrefix | string? | null | Awalan ORM diawali application\_name | 
| LoggerFactory | ILoggerFactory? | null | Pabrik logger untuk peringatan dan diagnostik coba lagi | 
| ConfigureConnectionString | Action<NpgsqlConnectionStringBuilder>? | null | Callback untuk mengganti pengaturan pool atau mengatur properti string koneksi Npgsql tambahan. SSL dan Enlist merupakan invarian keamanan dan tidak dapat diganti. | 

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

Konektor secara otomatis menangani otentikasi Aurora DSQL dengan menghasilkan token menggunakan kredensyal. AWS Jika Anda tidak menyediakan AWS wilayah, konektor menguraikannya dari nama host.

Untuk informasi lebih lanjut tentang otentikasi di Aurora DSQL, lihat. [Otentikasi dan otorisasi untuk Aurora DSQL](authentication-authorization.md)

### Admin vs pengguna biasa
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-admin-vs-regular"></a>
+ Pengguna bernama “admin” secara otomatis menggunakan token otentikasi admin
+ Semua pengguna lain menggunakan token otentikasi reguler
+ Konektor menghasilkan token secara dinamis untuk setiap koneksi