.NET Aspire SQL Server entegrasyonu

Şunları içerir:Barındırma tümleştirmesi ve Client tümleştirme

SQL Server, Microsoft tarafından geliştirilen ilişkisel bir veritabanı yönetim sistemidir. .NET Aspire SQL Server tümleştirmesi, SQL Serverile mevcut .NET örneklerine bağlanmanıza veya mcr.microsoft.com/mssql/server'dan yeni örnekler oluşturmanıza olanak tanır.

Barındırma tümleştirmesi

SQL Server barındırma tümleştirmesi, sunucuyu SqlServerServerResource türü ve veritabanını SqlServerDatabaseResource türü olarak modeller. Bu türlere ve API'lere erişmek için 📦AspireHosting.SqlServer NuGet paketini uygulama konağı projesine ekleyin.

dotnet add package Aspire.Hosting.SqlServer

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

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

SQL Server kaynağı ve veritabanı kaynağı ekle

Uygulama ana bilgisayar projenizde AddSqlServer çağırarak bir SQL Server kaynak oluşturucu ekleyin ve döndürin. AddDatabase veritabanı kaynağını eklemek için döndürülen kaynak oluşturucusuna bir çağrı yaparak SQL Server'a zincirleyin.

var builder = DistributedApplication.CreateBuilder(args);

var sql = builder.AddSqlServer("sql")
                 .WithLifetime(ContainerLifetime.Persistent);

var db = sql.AddDatabase("database");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(db)
       .WaitFor(db);

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

.NET .NET Aspire, önceki örnekte mcr.microsoft.com/mssql/server görüntüsüyle gösterildiği gibi uygulama konağına bir kapsayıcı görüntüsü eklediğinde, yerel makinenizde yeni bir SQL Server örneği oluşturur. Veritabanı eklemek için SQL Server kaynak oluşturucunuza (sql değişkeni) başvuru kullanılır. Veritabanı database olarak adlandırılır ve ardından ExampleProject'e eklenir. SQL Server kaynağı, username'i sa ve password yöntemi kullanılarak oluşturulan rastgele bir CreateDefaultPasswordParameter ile varsayılan kimlik bilgilerini içerir.

Uygulama ana bilgisayarı çalıştırıldığında, parola uygulama ana bilgisayarının gizli saklama alanında depolanır. Parameters bölümüne eklenir, örneğin:

{
  "Parameters:sql-password": "<THE_GENERATED_PASSWORD>"
}

Bu parametrenin adı sql-password, ancak gerçekte yalnızca kaynak adını -password sonekiyle biçimlendirmiş oluyor. Daha fazla bilgi için bkz. geliştirme aşamasında uygulama gizli dizilerinin güvenli depolanması ve parametreleriyle kaynağı ekleme.

WithReference yöntemi, ExampleProject'deki databaseadlı bağlantıyı yapılandırır.

Veri birimiyle SQL Server kaynağı ekleme

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

var builder = DistributedApplication.CreateBuilder(args);

var sql = builder.AddSqlServer("sql")
                 .WithDataVolume();

var db = sql.AddDatabase("database");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(db)
       .WaitFor(db);

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

Veri hacmi, SQL Server 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/opt/mssql kapsayıcısının SQL Server yoluna bağlanır ve name parametresi sağlanmazsa ad rastgele oluşturulur. Veri hacimleri hakkında daha fazla bilgi edinmek ve bağlamalarıneden tercih edildiklerine ilişkin ayrıntılar için bkz. Docker belgeler: Hacimler.

Veri bağlama ile SQL Server kaynağı ekleme

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

var builder = DistributedApplication.CreateBuilder(args);

var sql = builder.AddSqlServer("sql")
                 .WithDataBindMount(source: @"C:\SqlServer\Data");

var db = sql.AddDatabase("database");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(db)
       .WaitFor(db);

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

Veri bağlaması, kapsayıcı yeniden başlatmaları sırasında SQL Server verilerini korumak için konak makinenin dosya sistemine dayanır. Veri bağlama, C:\SqlServer\Data kapsayıcısında, konak makinedeki Windows üzerindeki /SqlServer/Data (veya Unixüzerindeki SQL Server) yoluna monte edilir. Veri bağlama noktaları hakkında daha fazla bilgi için Docker belgelerine bakın: Bağlama noktaları.

Parametrelerle SQL Server kaynağı ekleme

Kapsayıcı görüntüsü tarafından kullanılan 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 password = builder.AddParameter("password", secret: true);

var sql = builder.AddSqlServer("sql", password);
var db = sql.AddDatabase("database");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(db)
       .WaitFor(db);

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

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

Veritabanı kaynaklarına bağlanma

.NET .NET Aspire uygulama konağı çalıştırıldığında, sunucunun veritabanı kaynaklarına SQL Server Management Studio (SSMS) veya Visual Studio Codeiçin MSSQLgibi dış araçlardan erişilebilir. Veritabanı kaynağının bağlantı dizesi bağımlı kaynak ortam değişkenlerinde bulunur ve .NET.NET Aspire panosu kullanılarak erişilir: Kaynak ayrıntıları bölmesi. Ortam değişkeni ConnectionStrings__{name} olarak adlandırılır; burada {name} veritabanı kaynağının adıdır ve bu örnekte database. Dış araçlardan veritabanı kaynağına bağlanmak için bağlantı dizesini kullanın. Tek bir todos tablosuna sahip dbo.Todos adlı bir veritabanınız olduğunu düşünün.

Barındırma tümleştirme durumu denetimleri

SQL Server barındırma tümleştirmesi, SQL Server kaynağı için otomatik olarak bir sistem durumu denetimi ekler. Sağlık kontrolü, SQL Server'ın çalıştığını ve bağlantı kurulabileceğini doğrular.

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

Client entegrasyonu

.NET Aspire SQL Server istemci tümleştirmesine başlamak için, 📦Aspire.Microsoft.Data.SqlClient NuGet paketini, SQL Server istemcisini kullanan uygulama için olan projeye yükleyin. SQL Server istemci tümleştirmesi, SqlConnectionile etkileşime geçmek için kullanabileceğiniz bir SQL Server örneği kaydeder.

dotnet add package Aspire.Microsoft.Data.SqlClient

<PackageReference Include="Aspire.Microsoft.Data.SqlClient"
                  Version="*" />

"SQL Server istemcisi ekle"

İstemci kullanan projenizin Program.cs dosyasında, herhangi bir AddSqlServerClient üzerinde IHostApplicationBuilder uzantı metodunu çağırarak bağımlılık enjeksiyonu konteyneri aracılığıyla kullanılmak üzere bir SqlConnection kaydedin. yöntemi bir bağlantı adı parametresi alır.

builder.AddSqlServerClient(connectionName: "database");

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

public class ExampleService(SqlConnection connection)
{
    // Use connection...
}

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

Anahtarlı SQL Server istemcisi ekleme

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

builder.AddKeyedSqlServerClient(name: "mainDb");
builder.AddKeyedSqlServerClient(name: "loggingDb");

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

public class ExampleService(
    [FromKeyedServices("mainDb")] SqlConnection mainDbConnection,
    [FromKeyedServices("loggingDb")] SqlConnection loggingDbConnection)
{
    // Use connections...
}

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

Konfigürasyon

.NET Aspire SQL Server tümleştirmesi, projenizin gereksinimlerine ve kurallarına göre bağlantıyı yapılandırmak için birden çok seçenek sağlar.

Bağlantı dizesi kullanma

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

builder.AddSqlServerClient(connectionName: "sql");

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

{
  "ConnectionStrings": {
    "database": "Data Source=myserver;Initial Catalog=master"
  }
}

Bu bağlantı dizesini biçimlendirme hakkında daha fazla bilgi için bkz. ConnectionString.

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

.NET Aspire SQL Server tümleştirmesi Microsoft.Extensions.Configurationdestekler. Yapılandırmadan MicrosoftDataSqlClientSettings'ı, Aspire:Microsoft:Data:SqlClient anahtarını kullanarak yükler. Aşağıdaki kod parçacığı, bazı seçenekleri yapılandıran bir appsettings.json dosyası örneğidir:

{
  "Aspire": {
    "Microsoft": {
      "Data": {
        "SqlClient": {
          "ConnectionString": "YOUR_CONNECTIONSTRING",
          "DisableHealthChecks": false,
          "DisableMetrics": true
        }
      }
    }
  }
}

tam SQL Server istemci tümleştirmesi JSON şeması için bkz. Aspire.Microsoft.Data.SqlClient/ConfigurationSchema.json.

Satır içi temsilcileri kullanın

Ayrıca Action<MicrosoftDataSqlClientSettings> configureSettings temsilcisini geçirerek satır içi seçeneklerin bazılarını veya tümünü ayarlayabilirsiniz; örneğin, koddan sistem durumu denetimlerini devre dışı bırakmak için:

builder.AddSqlServerClient(
    "database",
    static settings => settings.DisableHealthChecks = true);

Client tümleştirme sağlık kontrolleri

Varsayılan olarak, .NET.NET Aspire tümleştirmeleri tüm hizmetler için sağlık kontrollerini etkinleştirir. Daha fazla bilgi için bkz. .NET.NET Aspire tümleştirmelere genel bakış.

.NET Aspire SQL Server tümleştirmesi:

• MicrosoftDataSqlClientSettings.DisableHealthChecks falseolduğunda sağlık kontrolünü ekler ve SQL Serverbağlanmaya çalışır.
• 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

tümleştirmeleri, bazen gözlemlenebilirlikolarak 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ı entegrasyonlar günlüğe kaydetmeyi ve izlemeyi 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 SQL Server tümleştirmesi, Microsoft.Data.SqlClientsınırlamaları nedeniyle şu anda günlüğe kaydetmeyi varsayılan olarak etkinleştirmemektedir.

Izleme

.NET Aspire SQL Server entegrasyonu, OpenTelemetrykullanarak aşağıdaki izleme etkinliklerini yayar:

• OpenTelemetry.Instrumentation.SqlClient

Ölçüm

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

• Microsoft.Data.SqlClient.EventSource
  • active-hard-connections
  • hard-connects
  • hard-disconnects
  • active-soft-connects
  • soft-connects
  • soft-disconnects
  • number-of-non-pooled-connections
  • number-of-pooled-connections
  • number-of-active-connection-pool-groups
  • number-of-inactive-connection-pool-groups
  • number-of-active-connection-pools
  • number-of-inactive-connection-pools
  • number-of-active-connections
  • number-of-free-connections
  • number-of-stasis-connections
  • number-of-reclaimed-connections

Ayrıca bkz.

• Azure SQL Veritabanı
• SQL Server
• .NET .NET Aspire veritabanı kapsayıcıları örneği
• .NET .NET Aspire tümleştirmeleri
• .NET Aspire GitHub depo