.NET Aspire PostgreSQL entegrasyonu

Içerir: Barındırma tümleştirmesi ve Client tümleştirmesi

PostgreSQL, güvenilirlik, özellik sağlamlığı ve performans açısından güçlü bir üne sahip, uzun yıllara ait etkin geliştirme özelliklerine sahip güçlü, açık kaynaklı bir nesne ilişkisel veritabanı sistemidir. .NET Aspire PostgreSQL tümleştirmesi, mevcut PostgreSQL veritabanlarına bağlanmanın veya .NETile docker.io/library/postgres yeni örnekler oluşturmanın bir yolunu sağlar.

Barındırma entegrasyonu

PostgreSQL barındırma tümleştirmesi, çeşitli PostgreSQL kaynaklarını aşağıdaki türler olarak modeller.

• PostgresServerResource
• PostgresDatabaseResource
• PgAdminContainerResource
• PgWebContainerResource

Bu türlere ve API'lere erişmek ve bunları uygulama konağı projenizde kaynak olarak ifade etmek için 📦Aspire.Hosting.PostgreSQL NuGet paketini yükleyin.

dotnet add package Aspire.Hosting.PostgreSQL

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

Daha fazla bilgi için bkz. dotnet add package veya .NET uygulamalarında paket bağımlılıklarını yönetme.

PostgreSQL sunucu kaynağı ekleme

Uygulama ana bilgisayar projenizde, AddPostgres sunucu kaynağı eklemek için builder örneğindeki PostgreSQL çağırın ve ardından AddDatabase örneğinde postgres çağırarak aşağıdaki örnekte gösterildiği gibi bir veritabanı kaynağı ekleyin:

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...

.NET .NET Aspire, önceki örnekte docker.io/library/postgres görüntüde gösterildiği gibi uygulama konağına bir kapsayıcı görüntüsü eklediğinde, yerel makinenizde yeni bir PostgreSQL sunucu örneği oluşturur. PostgreSQL'ye bir bağımlılık eklemek için PostgreSQL sunucunuza ve postgresdb veritabanı örneğinize (ExampleProject değişkeni) referans verilir. PostgreSQL sunucu kaynağı, username"postgres" ile birlikte password yöntemi kullanılarak rastgele oluşturulan CreateDefaultPasswordParameter içeren varsayılan kimlik bilgilerini içerir.

WithReference yöntemi, ExampleProjectadlı "messaging" üzerinde bir bağlantı yapılandırıyor. Daha fazla bilgi için bkz. Kapsayıcı kaynak yaşam döngüsü.

PostgreSQL pgAdmin kaynağı ekleme

PostgreSQL yöntemiyle builder kaynaklarını AddPostgres'e eklerken, WithPgAdmin kapsayıcısını eklemek için çağrılarını zincir halinde kullanabilirsiniz. Bu kapsayıcı, web tabanlı bir yönetici panosu sunan PostgreSQL veritabanları için platformlar arası bir istemcidir. Aşağıdaki örneği göz önünde bulundurun:

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...

Yukarıdaki kod, docker.io/dpage/pgadmin4 görüntüsünü temel alan bir kapsayıcı ekler. Kapsayıcı, PostgreSQL sunucusu ve veritabanı kaynaklarını yönetmek için kullanılır. WithPgAdmin yöntemi, PostgreSQL veritabanları için web tabanlı bir yönetici panosu sunan bir kapsayıcı ekler.

pgAdmin ana bilgisayar bağlantı noktasını yapılandırma

pgAdmin kapsayıcısının konak bağlantı noktasını yapılandırmak için WithHostPort yöntemini PostgreSQL sunucu kaynağında çağırın. Aşağıdaki örnek, pgAdmin kapsayıcısı için ana bilgisayar bağlantı noktasını nasıl yapılandıracağınızı göstermektedir.

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...

Yukarıdaki kod, pgAdmin kapsayıcısına ana bilgisayar bağlantı noktasını ekler ve yapılandırır. Aksi halde ana bilgisayar bağlantı noktası rastgele atanır.

PostgreSQL pgWeb kaynağı ekle

PostgreSQL yöntemini kullanarak builder içine AddPostgres kaynakları eklediğinizde, çağrılarını WithPgWeb ile zincirleyerek sosedoff/pgweb kapsayıcısını ekleyebilirsiniz. Bu kapsayıcı, web tabanlı bir yönetici panosu sunan PostgreSQL veritabanları için platformlar arası bir istemcidir. Aşağıdaki örneği göz önünde bulundurun:

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...

Yukarıdaki kod, docker.io/sosedoff/pgweb görüntüsünü temel alan bir kapsayıcı ekler. Tüm kayıtlı PostgresDatabaseResource örnekleri, örnek başına bir yapılandırma dosyası oluşturmak için kullanılır ve her yapılandırma pgweb kapsayıcı yer işareti dizinine bağlıdır. Daha fazla bilgi için bkz. PgWeb belgeleri: Server bağlantı yer işaretleri.

pgWeb ana bilgisayar bağlantı noktasını yapılandırma

pgWeb kapsayıcısının ana makine bağlantı noktasını yapılandırmak için WithHostPort sunucu kaynağında PostgreSQL yöntemini çalıştırın. Aşağıdaki örnek, pgAdmin kapsayıcısı için host portunun nasıl yapılandırılacağını gösterir.

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...

Önceki kod, pgWeb kapsayıcısı için konak bağlantı noktasını ekler ve yapılandırır. Aksi halde ana bilgisayar bağlantı noktası rastgele atanır.

Veri hacmiyle PostgreSQL sunucu kaynağını ekle

PostgreSQL sunucu kaynağına veri birimi eklemek için WithDataVolume sunucu kaynağında PostgreSQL yöntemini çağırın:

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...

Veri hacmi, PostgreSQL sunucu verilerini kapsayıcısının yaşam döngüsü dışında kalıcı hale getirmek için kullanılır. Veri birimi, /var/lib/postgresql/data sunucu kapsayıcısında PostgreSQL yoluna bağlanır ve name parametresi sağlanmazsa ad rastgele oluşturulur. Veri birimleri ve bağlamalar yerine neden tercih edildiklerine ilişkin ayrıntılar hakkında daha fazla bilgi için belgeler: Birimler'e bakın.

Veri bağlama mount'u ile PostgreSQL sunucu kaynağı ekle

PostgreSQL sunucu kaynağına veri bağlaması eklemek için WithDataBindMount yöntemini çağırın:

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...

Veri bağlamaları, kapsayıcı yeniden başlatıldığında PostgreSQL sunucu verilerinin kalıcı olmasını sağlamak için konak makinenin dosya sisteminden yararlanır. Veri bağlama montesi, C:\PostgreSQL\Data sunucu kapsayıcısındaki konak makinede Windows üzerindeki /PostgreSQL/Data yoluna (veya Unixüzerinde PostgreSQL) monte edilmiştir. Veri bağlama yuvaları hakkında daha fazla bilgi için Docker belgelerine bakın: Bağlama yuvaları.

init bağlama ile PostgreSQL sunucu kaynağı ekleme

PostgreSQL sunucu kaynağına bir "init bind mount" eklemek için WithInitBindMount yöntemini çağırın.

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...

Host makinenin dosya sistemine dayanan init bind mount, PostgreSQL sunucu veritabanını kapsayıcılar içerisindeki init klasörüyle başlatmak için kullanılır. Bu klasör, postgres-data klasörü oluşturulduktan sonra yürütülebilir kabuk betiklerini veya .sql komut dosyalarını çalıştırarak başlatma için kullanılır. Init bağlaması, C:\PostgreSQL\Init sunucu kapsayıcısında, konak makinedeki Windows üzerinde /PostgreSQL/Init yoluna (veya Unixüzerinde PostgreSQL yoluna) bağlanmış durumda.

Parametrelerle PostgreSQL sunucu kaynağı ekleme

Kapsayıcı görüntüsü tarafından kullanılan kullanıcı adını ve parolayı açıkça sağlamak istediğinizde, bu kimlik bilgilerini parametre olarak sağlayabilirsiniz. Aşağıdaki alternatif örneği göz önünde bulundurun:

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...

Parametreleri sağlama hakkında daha fazla bilgi için bkz. dış parametreler.

Barındırma entegrasyon sağlık denetimleri

PostgreSQL barındırma tümleştirmesi, PostgreSQL sunucu kaynağı için otomatik olarak bir sistem durumu denetimi ekler. Sistem durumu denetimi, PostgreSQL sunucusunun çalıştığını ve bu sunucuyla bağlantı kurulabileceğini doğrular.

Barındırma tümleştirmesi, 📦 AspNetCore.HealthChecks.Npgsql NuGet paketine dayanır.

Client entegrasyonu

.NET Aspire PostgreSQL istemci entegrasyonuna başlamak için, 📦Aspire.Npgsql NuGet paketini, yani 📦 istemcisini kullanan uygulamanın projesi olan istemci tüketici projeye yükleyin. PostgreSQL istemci tümleştirmesi, ile etkileşimde bulunurken kullanabileceğiniz bir PostgreSQL örneği kaydeder.

dotnet add package Aspire.Npgsql

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

Npgsql istemcisi ekleme

İstemciyi kullanan projenizin Program.cs dosyasında, bir NpgsqlDataSource kaydetmek için herhangi bir IHostApplicationBuilder üzerinde AddNpgsqlDataSource uzantı yöntemini çağırın; bu kayıt, bağımlı ekleme kapsayıcısında kullanılabilir hale gelecektir. yöntemi bir bağlantı adı parametresi alır.

builder.AddNpgsqlDataSource(connectionName: "postgresdb");

Oluşturucuya NpgsqlDataSource ekledikten sonra bağımlılık ekleme kullanarak NpgsqlDataSource örneğini alabilirsiniz. Örneğin, örnek bir hizmetten veri kaynağı nesnenizi almak için bunu bir oluşturucu parametresi olarak tanımlayın ve ExampleService sınıfının bağımlılık ekleme kapsayıcısına kayıtlı olduğundan emin olun:

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

Bağımlılık ekleme hakkında daha fazla bilgi için bkz. .NET bağımlılık ekleme.

Anahtarlı Npgsql istemcisi ekleme

Farklı bağlantı adlarına sahip birden çok NpgsqlDataSource örneğini kaydetmek istediğiniz durumlar olabilir. Anahtarlı Npgsql istemcilerini kaydetmek için AddKeyedNpgsqlDataSource yöntemini çağırın:

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

Daha sonra bağımlılık ekleme kullanarak NpgsqlDataSource örneklerini alabilirsiniz. Örneğin, bağlantıyı örnek bir hizmetten almak için:

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

Anahtarlı hizmetler hakkında daha fazla bilgi için bkz. .NET bağımlılık ekleme: Anahtarlı hizmetler.

Konfigürasyon

.NET Aspire PostgreSQL tümleştirmesi, projenizin gereksinimlerini ve kurallarını karşılamak için birden çok yapılandırma yaklaşımı ve seçeneği sağlar.

Bağlantı dizesi kullanma

ConnectionStrings yapılandırma bölümünden bir bağlantı dizesi kullanırken, AddNpgsqlDataSource yöntemini çağırırken bağlantı dizesinin adını sağlayabilirsiniz:

builder.AddNpgsqlDataSource("postgresdb");

Ardından bağlantı dizesi ConnectionStrings yapılandırma bölümünden alınır:

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

Daha fazla bilgi için ConnectionStringbölümüne bakın.

Yapılandırma sağlayıcılarını kullanma

.NET Aspire PostgreSQL tümleştirmesi Microsoft.Extensions.Configurationdesteklemektedir. NpgsqlSettings anahtarını kullanarak appsettings.json veya diğer yapılandırma dosyalarından Aspire:Npgsql yükler. Bazı seçenekleri yapılandıran örnek appsettings.json:

Aşağıdaki örnekte, kullanılabilir seçeneklerden bazılarını yapılandıran bir appsettings.json dosyası gösterilmektedir:

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

Tam PostgreSQL istemci tümleştirmesi JSON şeması için bkz. AspireNpgsql/ConfigurationSchema.json.

Satır içi temsilcileri kullanın

Ayrıca, sağlık kontrollerini devre dışı bırakmak gibi, bazı veya tüm seçenekleri satır içi olarak ayarlamak için Action<NpgsqlSettings> configureSettings temsilcisini de geçirebilirsiniz.

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

Client entegrasyon sağlık kontrolleri

Varsayılan olarak, .NET.NET Aspireistemci entegrasyonları, tüm hizmetler için sistem durumu denetimleri etkinleştirilmiştir. Benzer şekilde, birçok .NET.NET Aspirebarındırma entegrasyonu sağlık kontrol uç noktalarını da etkinleştirir. Daha fazla bilgi için bkz:

• C#'de .NET uygulama sağlık kontrolleri
• ASP.NET Core 'da sağlık denetimleri

• komutların temel alınan NpgSqlHealthCheck veritabanında başarıyla yürütülebileceğini doğrulayan Postgresekler.
• Uygulamanın trafiği kabul etmeye hazır olarak kabul edilmesi için tüm kayıtlı sistem durumu denetimlerinin geçmesi gerektiğini belirten /health HTTP uç noktasıyla tümleşir

Gözlemlenebilirlik ve telemetri

.NET .NET Aspire tümleştirmeleri, bazen gözlemlenebilirliğin sütunları olarak bilinen Günlük, İzleme ve Ölçüm yapılandırmalarını otomatik olarak ayarlar. Tümleştirme gözlemlenebilirliği ve telemetri hakkında daha fazla bilgi için bkz. tümleştirmelere genel bakış. Yedekleme hizmetine bağlı olarak, bazı tümleştirmeler bu özelliklerden yalnızca bazılarını destekleyemeyebilir. Örneğin, bazı tümleştirmeler, izleme ve günlüğe kaydetme işlemlerini destekler, ancak ölçümleri desteklemez. Telemetri özellikleri, Yapılandırma bölümünde sunulan teknikler kullanılarak da devre dışı bırakılabilir.

Kayıt tutma

.NET Aspire PostgreSQL tümleştirmesi aşağıdaki günlük kategorilerini kullanır:

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

İzleme

.NET Aspire PostgreSQL tümleştirmesi, OpenTelemetrykullanarak aşağıdaki izleme etkinliklerini üretecek.

• Npgsql

Ölçüm

.NET Aspire PostgreSQL tümleştirmesi, OpenTelemetrykullanarak aşağıdaki ölçümleri yayar:

• 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

Ayrıca bkz.

• PostgreSQL belgeler
• .NET Aspire Azure PostgreSQL entegrasyon
• .NET .NET Aspire tümleştirmeleri
• .NET Aspire GitHub repo