integrasi .NET AspirePostgreSQL

Meliputi: integrasi hosting dan integrasi Client

PostgreSQL adalah sistem database relasional objek sumber terbuka yang kuat dengan bertahun-tahun pengembangan aktif yang telah memberinya reputasi yang kuat untuk keandalan, ketahanan fitur, dan performa. Integrasi .NET AspirePostgreSQL menyediakan cara untuk terhubung ke database PostgreSQL yang ada, atau membuat instans baru dari .NET dengan gambar kontainer docker.io/library/postgres.

Integrasi hosting

Integrasi hosting PostgreSQL memodelkan berbagai sumber daya PostgreSQL sebagai jenis berikut.

• PostgresServerResource
• PostgresDatabaseResource
• PgAdminContainerResource
• PgWebContainerResource

Untuk mengakses jenis dan API ini untuk mengekspresikannya sebagai sumber daya di proyek host aplikasi Anda, instal paket NuGet 📦Aspire.Hosting.PostgreSQL:

dotnet add package Aspire.Hosting.PostgreSQL

<PackageReference Include="Aspire.Hosting.PostgreSQL"
                  Version="*" />

Untuk informasi selengkapnya, lihat dotnet menambahkan paket atau Mengelola dependensi paket di aplikasi .NET.

Menambahkan sumber daya server PostgreSQL

Di proyek host aplikasi Anda, panggil AddPostgres pada instans builder untuk menambahkan sumber daya server PostgreSQL lalu panggil AddDatabase pada instans postgres untuk menambahkan sumber daya database seperti yang ditunjukkan dalam contoh berikut:

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres");
var postgresdb = postgres.AddDatabase("postgresdb");

var exampleProject = builder.AddProject<Projects.ExampleProject>()
                            .WithReference(postgresdb);

// After adding all resources, run the app...

Saat .NET.NET Aspire menambahkan gambar kontainer ke host aplikasi, seperti yang ditunjukkan dalam contoh sebelumnya dengan gambar docker.io/library/postgres, gambar tersebut membuat instans server PostgreSQL baru di komputer lokal Anda. Referensi ke server PostgreSQL dan instans database PostgreSQL Anda (variabel postgresdb) digunakan untuk menambahkan dependensi ke ExampleProject. Sumber daya server PostgreSQL mencakup kredensial default dengan username"postgres" dan password yang dihasilkan secara acak menggunakan metode CreateDefaultPasswordParameter.

Metode WithReference mengonfigurasi koneksi di ExampleProject bernama "messaging". Untuk informasi selengkapnya, lihat siklus hidup sumber daya Kontainer.

Menambahkan sumber daya pgAdmin PostgreSQL

Saat menambahkan sumber daya PostgreSQL ke builder dengan metode AddPostgres, Anda dapat menautkan panggilan ke WithPgAdmin untuk menambahkan kontainer dpage/pgadmin4. Kontainer ini adalah klien lintas platform untuk database PostgreSQL, yang melayani dasbor admin berbasis web. Pertimbangkan contoh berikut:

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres")
                      .WithPgAdmin();

var postgresdb = postgres.AddDatabase("postgresdb");

var exampleProject = builder.AddProject<Projects.ExampleProject>()
                            .WithReference(postgresdb);

// After adding all resources, run the app...

Kode sebelumnya menambahkan kontainer berdasarkan gambar docker.io/dpage/pgadmin4. Kontainer digunakan untuk mengelola server PostgreSQL dan sumber daya database. Metode WithPgAdmin menambahkan kontainer yang melayani dasbor admin berbasis web untuk database PostgreSQL.

Mengonfigurasi port tuan rumah pgAdmin

Untuk mengonfigurasi port host untuk kontainer pgAdmin, panggil metode WithHostPort pada sumber daya server PostgreSQL. Contoh berikut menunjukkan cara mengonfigurasi port host untuk kontainer pgAdmin:

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres")
                      .WithPgAdmin(pgAdmin => pgAdmin.WithHostPort(5050));

var postgresdb = postgres.AddDatabase("postgresdb");

var exampleProject = builder.AddProject<Projects.ExampleProject>()
                            .WithReference(postgresdb);

// After adding all resources, run the app...

Kode sebelumnya menambahkan dan mengonfigurasi port host untuk kontainer pgAdmin. Port host ditetapkan secara acak.

Menambahkan sumber daya pgWeb PostgreSQL

Saat menambahkan sumber daya PostgreSQL ke builder dengan metode AddPostgres, Anda dapat merangkai pemanggilan ke WithPgWeb untuk menambahkan kontainer sosedoff/pgweb. Kontainer ini adalah klien lintas platform untuk database PostgreSQL, yang melayani dasbor admin berbasis web. Pertimbangkan contoh berikut:

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres")
                      .WithPgWeb();

var postgresdb = postgres.AddDatabase("postgresdb");

var exampleProject = builder.AddProject<Projects.ExampleProject>()
                            .WithReference(postgresdb);

// After adding all resources, run the app...

Kode sebelumnya menambahkan kontainer berdasarkan gambar docker.io/sosedoff/pgweb. Semua instans PostgresDatabaseResource terdaftar digunakan untuk membuat file konfigurasi per instans, dan setiap konfigurasi terikat ke pgweb direktori bookmark kontainer. Untuk informasi selengkapnya, lihat dokumen PgWeb: Server penanda koneksi.

Konfigurasikan port host pgWeb

Untuk mengonfigurasi port host untuk kontainer pgWeb, panggil metode WithHostPort pada sumber daya server PostgreSQL. Contoh berikut menunjukkan cara mengonfigurasi port host untuk kontainer pgAdmin:

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres")
                      .WithPgWeb(pgWeb => pgWeb.WithHostPort(5050));

var postgresdb = postgres.AddDatabase("postgresdb");

var exampleProject = builder.AddProject<Projects.ExampleProject>()
                            .WithReference(postgresdb);

// After adding all resources, run the app...

Kode sebelumnya menambahkan dan mengonfigurasi port host untuk kontainer pgWeb. Port host sebaliknya ditetapkan secara acak.

Tambahkan sumber daya server PostgreSQL dengan volume data.

Untuk menambahkan volume data ke sumber daya server PostgreSQL, panggil metode WithDataVolume pada sumber daya server PostgreSQL:

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres")
                      .WithDataVolume(isReadOnly: false);

var postgresdb = postgres.AddDatabase("postgresdb");

var exampleProject = builder.AddProject<Projects.ExampleProject>()
                            .WithReference(postgresdb);

// After adding all resources, run the app...

Volume data digunakan untuk mempertahankan data server PostgreSQL di luar siklus hidup kontainernya. Volume data dipasang di jalur /var/lib/postgresql/data di kontainer server PostgreSQL dan ketika parameter name tidak disediakan, nama dihasilkan secara acak. Untuk informasi lebih lanjut tentang volume data dan detail mengapa volume data lebih disukai dibandingkan dengan bind mounts , lihat dokumen Docker: Volume.

Menambahkan sumber daya server PostgreSQL dengan pemasangan ikatan data

Untuk menambahkan pemasangan ikatan data ke sumber daya server PostgreSQL, panggil metode WithDataBindMount:

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres")
                      .WithDataBindMount(
                          source: @"C:\PostgreSQL\Data",
                          isReadOnly: false);

var postgresdb = postgres.AddDatabase("postgresdb");

var exampleProject = builder.AddProject<Projects.ExampleProject>()
                            .WithReference(postgresdb);

// After adding all resources, run the app...

Pemasangan bind mount data mengandalkan sistem file dari komputer host untuk menjaga data server PostgreSQL tetap ada setiap kali kontainer dimulai ulang. Mount data bind dipasang di C:\PostgreSQL\Data pada jalur Windows (atau /PostgreSQL/Data di Unix) pada mesin host di kontainer server PostgreSQL. Untuk informasi selengkapnya tentang data bind mounts, lihat dokumen Docker: Bind mounts.

Tambahkan sumber daya server PostgreSQL dengan init untuk bind mount

Untuk menambahkan ikatan mount init ke sumber daya server PostgreSQL, panggil metode WithInitBindMount.

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres")
                      .WithInitBindMount(@"C:\PostgreSQL\Init");

var postgresdb = postgres.AddDatabase("postgresdb");

var exampleProject = builder.AddProject<Projects.ExampleProject>()
                            .WithReference(postgresdb);

// After adding all resources, run the app...

Bind mount init bergantung pada sistem berkas mesin host untuk menginisialisasi database server dengan folder init dari kontainer PostgreSQL. Folder ini digunakan untuk inisialisasi, menjalankan skrip shell yang dapat dieksekusi atau file perintah .sql setelah direktori postgres-data dibuat. Pemasangan bind mount init dipasang di lokasi C:\PostgreSQL\Init pada Windows (atau /PostgreSQL/Init di Unix) pada komputer host dalam kontainer server PostgreSQL.

Menambahkan sumber daya server PostgreSQL dengan parameter

Saat Anda ingin secara eksplisit memberikan nama pengguna dan kata sandi yang digunakan oleh gambar kontainer, Anda dapat memberikan kredensial ini sebagai parameter. Pertimbangkan contoh alternatif berikut:

var builder = DistributedApplication.CreateBuilder(args);

var username = builder.AddParameter("username", secret: true);
var password = builder.AddParameter("password", secret: true);

var postgres = builder.AddPostgres("postgres", username, password);
var postgresdb = postgres.AddDatabase("postgresdb");

var exampleProject = builder.AddProject<Projects.ExampleProject>()
                            .WithReference(postgresdb);

// After adding all resources, run the app...

Untuk informasi selengkapnya tentang menyediakan parameter, lihat Parameter eksternal.

Pengecekan kesehatan integrasi hosting

Integrasi hosting PostgreSQL secara otomatis menambahkan pemeriksaan kesehatan untuk sumber daya server PostgreSQL. Pemeriksaan kesehatan memverifikasi bahwa server PostgreSQL sedang berjalan dan bahwa koneksi dapat dibuat untuknya.

Integrasi hosting bergantung pada paket 📦 AspNetCore.HealthChecks.Npgsql NuGet.

Client integrasi

Untuk memulai integrasi klien .NET AspirePostgreSQL, instal paket 📦Aspire.Npgsql NuGet dalam proyek yang menggunakan klien, yaitu proyek untuk aplikasi yang menggunakan klien PostgreSQL. Integrasi klien mendaftarkan instans NpgsqlDataSource yang dapat Anda gunakan untuk berinteraksi dengan .

dotnet add package Aspire.Npgsql

<PackageReference Include="Aspire.Npgsql" Version="*" />

Menambahkan klien Npgsql

Dalam file Program.cs proyek yang menggunakan klien Anda, panggil metode ekstensi AddNpgsqlDataSource pada IHostApplicationBuilder mana pun untuk mendaftarkan NpgsqlDataSource agar dapat digunakan melalui kontainer injeksi dependensi. Metode ini mengambil parameter nama koneksi.

builder.AddNpgsqlDataSource(connectionName: "postgresdb");

Setelah menambahkan NpgsqlDataSource ke builder, Anda bisa mendapatkan instans NpgsqlDataSource dengan menggunakan injeksi dependensi. Misalnya, untuk mengambil objek sumber data Anda dari contoh layanan, tentukan sebagai parameter konstruktor dan pastikan kelas ExampleService terdaftar dengan kontainer injeksi dependensi:

public class ExampleService(NpgsqlDataSource dataSource)
{
    // Use dataSource...
}

Untuk informasi selengkapnya tentang injeksi dependensi, lihat .NET injeksi dependensi.

Menambahkan klien Npgsql yang berkunci

Mungkin ada situasi di mana Anda ingin mendaftarkan beberapa instans NpgsqlDataSource dengan nama koneksi yang berbeda. Untuk mendaftarkan klien Npgsql yang berkunci, panggil metode AddKeyedNpgsqlDataSource.

builder.AddKeyedNpgsqlDataSource(name: "chat");
builder.AddKeyedNpgsqlDataSource(name: "queue");

Kemudian Anda dapat mengambil instans NpgsqlDataSource menggunakan injeksi dependensi. Misalnya, untuk mengambil koneksi dari layanan contoh:

public class ExampleService(
    [FromKeyedServices("chat")] NpgsqlDataSource chatDataSource,
    [FromKeyedServices("queue")] NpgsqlDataSource queueDataSource)
{
    // Use data sources...
}

Untuk informasi selengkapnya tentang layanan terikat, lihat .NET injeksi dependensi: Layanan terikat.

Konfigurasi

Integrasi .NET AspirePostgreSQL menyediakan beberapa pendekatan dan opsi konfigurasi untuk memenuhi persyaratan dan konvensi proyek Anda.

Menggunakan string koneksi

Saat menggunakan string koneksi dari bagian konfigurasi ConnectionStrings, Anda dapat memberikan nama string koneksi saat memanggil metode AddNpgsqlDataSource:

builder.AddNpgsqlDataSource("postgresdb");

Kemudian string koneksi akan diambil dari bagian konfigurasi ConnectionStrings:

{
  "ConnectionStrings": {
    "postgresdb": "Host=myserver;Database=postgresdb"
  }
}

Untuk informasi selengkapnya, lihat ConnectionString.

Menggunakan penyedia konfigurasi

Integrasi .NET AspirePostgreSQL mendukung Microsoft.Extensions.Configuration. Ini memuat NpgsqlSettings dari appsettings.json atau file konfigurasi lainnya dengan menggunakan kunci Aspire:Npgsql. Contoh appsettings.json yang mengonfigurasi beberapa opsi:

Contoh berikut menunjukkan file appsettings.json yang mengonfigurasi beberapa opsi yang tersedia:

{
  "Aspire": {
    "Npgsql": {
      "ConnectionString": "Host=myserver;Database=postgresdb",
      "DisableHealthChecks": false,
      "DisableTracing": true,
      "DisableMetrics": false
    }
  }
}

Untuk skema PostgreSQL integrasi klien JSON lengkap, lihat Aspire. Npgsql/ConfigurationSchema.json.

Menggunakan delegasi sebaris

Anda juga dapat meneruskan delegasi Action<NpgsqlSettings> configureSettings untuk menyiapkan beberapa atau semua opsi secara langsung, misalnya untuk menonaktifkan cek kesehatan:

builder.AddNpgsqlDataSource(
    "postgresdb",
     static settings => settings.DisableHealthChecks = true);

Client pemeriksaan kesehatan integrasi

Secara default, integrasi klien .NET.NET Aspire memiliki pemeriksaan kesehatan yang diaktifkan untuk semua layanan. Demikian pula, banyak integrasi hosting .NET.NET Aspire juga mengaktifkan titik akhir pemeriksaan kesehatan. Untuk informasi selengkapnya, lihat:

• .NET pemeriksaan kesehatan aplikasi di C#
• Pemeriksaan kesehatan di

• Menambahkan NpgSqlHealthCheck, yang memverifikasi bahwa perintah dapat berhasil dijalankan terhadap database Postgres yang mendasar.
• Terintegrasi dengan titik akhir HTTP /health, yang menentukan semua pemeriksaan kesehatan terdaftar harus lulus agar aplikasi dianggap siap menerima lalu lintas

Pengamatan dan telemetri

.NET .NET Aspire integrasi secara otomatis menyiapkan konfigurasi Pengelogan, Pelacakan, dan Metrik, yang terkadang dikenal sebagai pilar pengamatan. Untuk informasi selengkapnya tentang pengamatan integrasi dan telemetri, lihat gambaran umum integrasi .NET.NET Aspire. Bergantung pada layanan pendukung, beberapa integrasi mungkin hanya mendukung beberapa fitur ini. Misalnya, beberapa integrasi mendukung pengelogan dan pelacakan, tetapi bukan metrik. Fitur telemetri juga dapat dinonaktifkan menggunakan teknik yang disajikan di bagian Konfigurasi .

Pencatatan

Integrasi .NET AspirePostgreSQL menggunakan kategori log berikut:

• Npgsql.Connection
• Npgsql.Command
• Npgsql.Transaction
• Npgsql.Copy
• Npgsql.Replication
• Npgsql.Exception

Menelusuri

Integrasi .NET AspirePostgreSQL akan memancarkan aktivitas pelacakan berikut menggunakan OpenTelemetry:

• Npgsql

Metrik

Integrasi .NET AspirePostgreSQL akan memancarkan metrik berikut menggunakan OpenTelemetry:

• Npgsql:
  • ec_Npgsql_bytes_written_per_second
  • ec_Npgsql_bytes_read_per_second
  • ec_Npgsql_commands_per_second
  • ec_Npgsql_total_commands
  • ec_Npgsql_current_commands
  • ec_Npgsql_failed_commands
  • ec_Npgsql_prepared_commands_ratio
  • ec_Npgsql_connection_pools
  • ec_Npgsql_multiplexing_average_commands_per_batch
  • ec_Npgsql_multiplexing_average_write_time_per_batch

Lihat juga

• PostgreSQL dokumen
• .NET Aspire Azure PostgreSQL integrasi
• .NET .NET Aspire integrasi
• .NET Aspire GitHub repo