integrasi .NET AspireSQL Server

Meliputi:integrasi Hosting dan Client integrasi

SQL Server adalah sistem manajemen database relasional yang dikembangkan oleh Microsoft. Integrasi .NET AspireSQL Server memungkinkan Anda terhubung ke instans SQL Server yang ada atau membuat instans baru dari .NET dengan gambar kontainer mcr.microsoft.com/mssql/server.

Integrasi hosting

Integrasi hosting SQL Server memodelkan server sebagai jenis SqlServerServerResource dan database sebagai jenis SqlServerDatabaseResource. Untuk mengakses jenis dan API ini, tambahkan paket NuGet 📦Aspire.Hosting.SqlServer dalam proyek host aplikasi .

dotnet add package Aspire.Hosting.SqlServer

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

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

Menambahkan sumber daya SQL Server dan sumber daya database

Di proyek host aplikasi Anda, panggil AddSqlServer untuk menambahkan dan mengembalikan pembangun sumber daya SQL Server. Rantai panggilan ke pembangun sumber daya yang dikembalikan ke AddDatabase, untuk menambahkan sumber daya database SQL Server.

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

Saat .NET.NET Aspire menambahkan gambar kontainer ke host aplikasi, seperti yang ditunjukkan dalam contoh sebelumnya dengan gambar mcr.microsoft.com/mssql/server, gambar tersebut membuat instans SQL Server baru di komputer lokal Anda. Referensi ke penyusun sumber daya SQL Server Anda (variabel sql) digunakan untuk menambahkan database. Database diberi nama database lalu ditambahkan ke ExampleProject. Sumber daya SQL Server mencakup kredensial default dengan username dari sa dan password yang dihasilkan secara acak menggunakan metode CreateDefaultPasswordParameter.

Saat host aplikasi berjalan, kata sandi disimpan di penyimpanan rahasia host aplikasi. Ini ditambahkan ke bagian Parameters, misalnya:

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

Nama parameter adalah sql-password, namun sebenarnya hanya memformat nama sumber dengan akhiran -password. Untuk informasi selengkapnya, lihat penyimpanan rahasia aplikasi secara aman selama pengembangan di ASP.NET Core dan tambahkan sumber daya SQL Server dengan parameter.

Metode WithReference mengonfigurasi koneksi di ExampleProject bernama database.

Tambahkan sumber daya SQL Server dengan volume data

Untuk menambahkan volume data ke sumber daya SQL Server, panggil metode WithDataVolume pada sumber daya SQL Server:

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

Volume data digunakan untuk mempertahankan data SQL Server di luar siklus hidup kontainernya. Volume data dipasang di jalur /var/opt/mssql di kontainer SQL Server dan ketika parameter name tidak disediakan, nama dihasilkan secara acak. Untuk informasi selengkapnya tentang volume data dan detail tentang mengapa mereka lebih disukai daripada pemasangan ikat , lihat dokumen Docker: Volume.

Menambahkan sumber daya SQL Server dengan pemasangan ikatan data

Untuk menambahkan pemasangan ikatan data ke sumber daya SQL Server, panggil metode WithDataBindMount:

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

Mount bind data mengandalkan sistem file pada mesin host untuk mempertahankan data SQL Server selama restart kontainer. Pemasangan ikatan data dipasang di C:\SqlServer\Data pada jalur Windows (atau /SqlServer/Data pada Unix) pada komputer host di kontainer SQL Server. Untuk informasi lebih lanjut tentang data bind mounts, merujuk pada dokumen Docker: Bind mounts.

Tambahkan sumber daya SQL Server dengan parameter

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

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

Untuk informasi selengkapnya tentang menyediakan parameter, lihat Parameter eksternal.

Menyambungkan ke sumber daya database

Saat host aplikasi .NET.NET Aspire berjalan, sumber daya database server dapat diakses dari alat eksternal, seperti SQL Server Management Studio (SSMS) atau Azure Data Studio. String koneksi untuk sumber daya database tersedia di variabel lingkungan sumber daya yang bergantung dan diakses menggunakan papan kendali .NET.NET Aspire: Jendela detail sumber daya. Variabel lingkungan diberi nama ConnectionStrings__{name} di mana {name} adalah nama sumber daya database, dalam contoh ini database. Gunakan string koneksi untuk menyambungkan ke sumber daya database dari alat eksternal. Bayangkan Anda memiliki database bernama todos dengan satu tabel dbo.Todos.

Melakukan pemeriksaan kesehatan integrasi

Integrasi hosting SQL Server secara otomatis menambahkan pemeriksaan kesehatan untuk sumber daya SQL Server. Pemeriksaan kesehatan memverifikasi bahwa SQL Server berfungsi dan bahwa koneksi dapat dilakukan ke sana.

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

Client integrasi

Untuk mulai menggunakan integrasi klien .NET AspireSQL Server, instal paket NuGet 📦Aspire.Microsoft.Data.SqlClient dalam proyek yang menggunakan klien, yaitu proyek aplikasi yang menggunakan klien SQL Server. Integrasi klien SQL Server mendaftarkan instans SqlConnection yang dapat Anda gunakan untuk berinteraksi dengan SQL Server.

dotnet add package Aspire.Microsoft.Data.SqlClient

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

Menambahkan klien SQL Server

Dalam file Program.cs proyek yang menggunakan klien Anda, panggil metode ekstensi AddSqlServerClient pada IHostApplicationBuilder apa pun untuk mendaftarkan SqlConnection untuk digunakan melalui wadah injeksi dependensi. Metode ini mengambil parameter nama koneksi.

builder.AddSqlServerClient(connectionName: "database");

Anda kemudian dapat mengambil instans SqlConnection melalui penerapan injeksi dependensi. Misalnya, untuk mengambil koneksi dari layanan contoh:

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

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

Menambahkan klien SQL Server yang berbasis kunci

Mungkin ada situasi di mana Anda ingin mendaftarkan beberapa instans SqlConnection dengan nama koneksi yang berbeda. Untuk mendaftarkan klien kunci SQL Server, panggil metode AddKeyedSqlServerClient.

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

Kemudian Anda dapat mengambil instance SqlConnection dengan menggunakan injeksi dependensi. Misalnya, untuk mengambil koneksi dari layanan contoh:

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

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

Konfigurasi

Integrasi .NET AspireSQL Server menyediakan beberapa opsi untuk mengonfigurasi koneksi berdasarkan 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 AddSqlServerClient:

builder.AddSqlServerClient(connectionName: "sql");

Kemudian string koneksi diambil dari bagian konfigurasi ConnectionStrings:

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

Untuk informasi selengkapnya tentang cara memformat string koneksi ini, lihat ConnectionString.

Menggunakan penyedia konfigurasi

Integrasi .NET AspireSQL Server mendukung Microsoft.Extensions.Configuration. Ini memuat MicrosoftDataSqlClientSettings dari konfigurasi dengan menggunakan kunci Aspire:Microsoft:Data:SqlClient. Cuplikan berikut adalah contoh file appsettings.json yang mengonfigurasi beberapa opsi:

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

Untuk skema JSON integrasi klien SQL Server lengkap, lihat Aspire. Microsoft.Data.SqlClient/ConfigurationSchema.json.

Menggunakan delegasi sebaris

Anda juga dapat meneruskan delegate Action<MicrosoftDataSqlClientSettings> configureSettings untuk menyiapkan beberapa atau semua opsi inline, misalnya untuk menonaktifkan pemeriksaan status dari kode:

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

Client pemeriksaan kesehatan integrasi

Secara default, integrasi .NET.NET Aspire memungkinkan pemeriksaan kesehatan untuk semua layanan. Untuk informasi selengkapnya, lihat gambaran umum integrasi .NET.NET Aspire.

Integrasi .NET AspireSQL Server:

• Menambahkan pemeriksaan kesehatan ketika MicrosoftDataSqlClientSettings.DisableHealthChecks adalah false, yang mana mencoba menyambungkan ke SQL Server.
• Terintegrasi dengan endpoint HTTP /health, yang menentukan semua pemeriksaan kesehatan yang 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 .

Penebangan

Integrasi .NET AspireSQL Server saat ini tidak mengaktifkan pengelogan secara default karena keterbatasan Microsoft.Data.SqlClient.

Menelusuri

Integrasi .NET AspireSQL Server memancarkan aktivitas pelacakan berikut menggunakan OpenTelemetry:

• OpenTelemetry.Instrumentation.SqlClient

Metode pengukuran

Integrasi .NET AspireSQL Server akan memancarkan metrik berikut menggunakan OpenTelemetry:

• 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

Lihat juga

• Azure SQL Database
• SQL Server
• .NET .NET Aspire sampel kontainer database
• .NET .NET Aspire integrasi
• .NET Aspire GitHub repositori