.NET Aspire SQL Server 통합

포함:호스팅 통합 및 Client 통합

SQL Server Microsoft에서 개발한 관계형 데이터베이스 관리 시스템입니다. .NET Aspire SQL Server 통합을 사용하면 기존 SQL Server 인스턴스에 연결하거나 mcr.microsoft.com/mssql/server 컨테이너 이미지사용하여 .NET 새 인스턴스를 만들 수 있습니다.

호스팅 통합

SQL Server 호스팅 통합은 serverSqlServerServerResource 형식으로, 데이터베이스를 SqlServerDatabaseResource 형식으로 모델화합니다. 이러한 형식 및 API에 액세스하려면 📦Aspire.Hosting.SqlServer NuGet 패키지를 앱 호스트 프로젝트에 추가합니다.

dotnet add package Aspire.Hosting.SqlServer

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

자세한 내용은 dotnet add package 또는 manage package dependencies in .NET applications.

SQL Server 리소스 및 데이터베이스 리소스 추가

앱 호스트 프로젝트에서 AddSqlServer을 호출하여 SQL Server 리소스 빌더를 추가하고 반환합니다. 반환된 리소스 작성기에 호출을 체인으로 연결하여 AddDatabase에 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...

.NET .NET Aspire mcr.microsoft.com/mssql/server 이미지와 함께 이전 예제와 같이 앱 호스트에 컨테이너 이미지를 추가하면 로컬 컴퓨터에 새 SQL Server 인스턴스가 만들어집니다. SQL Server 리소스 작성기(sql 변수)에 대한 참조는 데이터베이스를 추가하는 데 사용됩니다. 데이터베이스가 database으로 명명된 후 ExampleProject에 추가됩니다. SQL Server 리소스에는 username이 sa이고 CreateDefaultPasswordParameter 메서드를 사용하여 생성된 임의의 password가 있는 기본 자격 증명이 포함되어 있습니다.

앱 호스트가 실행되면 암호가 앱 호스트의 비밀 저장소에 저장됩니다. 예를 들어, Parameters 섹션에 추가되고 있습니다.

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

매개 변수의 이름은 sql-password, 실제로는 리소스 이름에 -password 접미사를 사용하여 서식을 지정하는 것입니다. 자세한 내용은 개발 시 앱 비밀의 안전한 스토리지를 참조하고 매개 변수 리소스 추가를 참조하세요.

WithReference 메서드는 database라는 이름의 ExampleProject에서 연결을 구성합니다.

데이터 볼륨이 있는 SQL Server 리소스 추가

SQL Server 리소스에 데이터 볼륨을 추가하려면 SQL Server 리소스에서 WithDataVolume 메서드를 호출합니다.

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

데이터 볼륨은 컨테이너의 수명 주기 외부에서 SQL Server 데이터를 유지하는 데 사용됩니다. 데이터 볼륨은 SQL Server 컨테이너의 /var/opt/mssql 경로에 탑재되고 name 매개 변수가 제공되지 않으면 이름이 임의로 생성됩니다. 데이터 볼륨에 대한 자세한 내용 및바인딩 탑재보다 선호하는 이유에 대한 자세한 내용은 문서: 볼륨참조하세요.

데이터 바인드 마운트를 사용하여 SQL Server 리소스 추가

SQL Server 리소스에 데이터 바인딩 탑재를 추가하려면 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...

데이터 바인드 마운트는 호스트 컴퓨터의 파일 시스템을 사용하여 컨테이너 재시작 시 SQL Server 데이터를 지속적으로 유지합니다. 데이터 바인딩 탑재는 SQL Server 컨테이너의 호스트 컴퓨터에서 Windows의 C:\SqlServer\Data(또는 Unix경로의 /SqlServer/Data)에 탑재됩니다. 데이터 바인드 마운트에 대한 자세한 내용은 Docker 문서: 바인드 마운트를 참조하세요.

매개 변수를 사용하여 SQL Server 리소스 추가

컨테이너 이미지에서 사용하는 암호를 명시적으로 제공하려는 경우 이러한 자격 증명을 매개 변수로 제공할 수 있습니다. 다음 대체 예제를 고려합니다.

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

매개 변수를 제공하는 방법에 대한 자세한 내용은 외부 매개 변수참조하세요.

데이터베이스 리소스에 연결

.NET Aspire 앱 호스트가 실행되면 SSMS(SQL Server Management Studio) 또는 Azure Data Studio같은 외부 도구에서 server데이터베이스 리소스에 액세스할 수 있습니다. 데이터베이스 리소스에 대한 연결 문자열은 종속 리소스 환경 변수에서 사용할 수 있으며 .NET.NET Aspire 대시보드: 리소스 세부 정보 창을 사용하여 액세스됩니다. 환경 변수의 이름은 ConnectionStrings__{name} 이름이 지정됩니다. 여기서 {name} 데이터베이스 리소스의 이름이고, 이 예제에서는 database. 연결 문자열을 사용하여 외부 도구에서 데이터베이스 리소스에 연결합니다. 단일 dbo.Todos 테이블로 구성된 todos 데이터베이스를 상상해 보세요.

통합 건강 상태 검사 호스팅

SQL Server 호스팅 통합은 SQL Server 리소스에 대한 상태 검사를 자동으로 추가합니다. 상태 검사는 SQL Server이 실행 중인지, 그리고 연결이 설정될 수 있는지를 확인합니다.

호스팅 통합은 📦 AspNetCore.HealthChecks.SqlServer NuGet 패키지에 의존합니다.

Client 통합

.NET Aspire SQL Server client 통합을 시작하려면 📦Aspire설치합니다. Microsoft.Data.SqlClient는 client-consuming 프로젝트, 즉 SQL Serverclient사용하는 애플리케이션에 대한 프로젝트의 NuGet 패키지를. SQL Server client 통합은 SqlConnection 인스턴스를 등록합니다. 이 인스턴스는 SQL Server과 상호 작용하는 데 사용할 수 있습니다.

dotnet add package Aspire.Microsoft.Data.SqlClient

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

SQL Server client 추가

client을 사용하는 프로젝트의 Program.cs 파일에서 IHostApplicationBuilder 개체에 대해 AddSqlServerClient 확장 메서드를 호출하여 종속성 주입 컨테이너를 통해 사용할 SqlConnection를 등록합니다. 메서드는 연결 이름 매개 변수를 사용합니다.

builder.AddSqlServerClient(connectionName: "database");

그런 다음 종속성 주입을 사용하여 SqlConnection 인스턴스를 검색할 수 있습니다. 예를 들어 예제 서비스에서 연결을 검색하려면 다음을 수행합니다.

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

종속성 주입에 대한 자세한 내용은 .NET 종속성 주입참조하세요.

키 입력 SQL Serverclient 추가

여러 SqlConnection 인스턴스를 서로 다른 연결 이름으로 등록하려는 경우가 있을 수 있습니다. 키 SQL Server 클라이언트를 등록하려면 AddKeyedSqlServerClient 메서드를 호출합니다.

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

그런 다음 종속성 주입을 사용하여 SqlConnection 인스턴스를 검색할 수 있습니다. 예를 들어 예제 서비스에서 연결을 검색하려면 다음을 수행합니다.

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

키가 지정된 서비스에 대한 자세한 내용은 .NET 종속성 주입: 키가 지정된 서비스를 참조하세요.

구성

.NET Aspire SQL Server 통합은 프로젝트의 요구 사항 및 규칙에 따라 연결을 구성하는 여러 옵션을 제공합니다.

연결 문자열 사용

ConnectionStrings 구성 섹션에서 연결 문자열을 사용하는 경우 AddSqlServerClient 메서드를 호출할 때 연결 문자열의 이름을 제공할 수 있습니다.

builder.AddSqlServerClient(connectionName: "sql");

그런 다음 ConnectionStrings 구성 섹션에서 연결 문자열을 검색합니다.

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

이 연결 문자열의 서식을 지정하는 방법에 대한 자세한 내용은 ConnectionString참조하세요.

구성 공급자 사용

.NET Aspire SQL Server 통합은 Microsoft.Extensions.Configuration지원합니다. 구성에서 Aspire:Microsoft:Data:SqlClient 키를 사용하여 MicrosoftDataSqlClientSettings을(를) 불러옵니다. 다음 코드 조각은 일부 옵션을 구성하는 appsettings.json 파일의 예입니다.

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

전체 SQL Serverclient 통합 JSON 스키마는 Aspire참조하세요. Microsoft.Data.SqlClient/ConfigurationSchema.json.

인라인 대리자 사용

또한 Action<MicrosoftDataSqlClientSettings> configureSettings 대리자를 전달하여 코드에서 상태 검사를 사용하지 않도록 설정하는 등 일부 또는 모든 옵션을 인라인으로 설정할 수 있습니다.

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

Client 통합 상태 검사

기본적으로 .NET.NET Aspire 통합은 모든 서비스에 대해 상태 검사를 수행할 수 있도록 합니다. 자세한 내용은 .NET.NET Aspire 통합 개요참조하세요.

.NET Aspire SQL Server의 통합:

• MicrosoftDataSqlClientSettings.DisableHealthChecks이 false일 때 SQL Server에 연결을 시도하는 상태 검사를 추가합니다.
• /health HTTP 엔드포인트와 통합되어 있으며, 이 엔드포인트는 등록된 모든 상태 검사가 통과해야 앱이 트래픽 수용 준비가 된 것으로 간주됩니다.

관찰 가능성 및 원격 분석

통합은 로깅, 추적 및 메트릭 구성을 자동으로 설정하며, 이를 관찰성핵심 요소라고도 . 통합 관찰 가능성 및 원격 분석에 대한 자세한 내용은 .NET.NET Aspire 통합 개요참조하세요. 지원 서비스에 따라 일부 통합은 이러한 기능 중 일부만 지원할 수 있습니다. 예를 들어 일부 통합은 로깅 및 추적을 지원하지만 메트릭은 지원하지 않습니다. 구성 섹션에 제시된 기술을 사용하여 원격 분석 기능을 사용하지 않도록 설정할 수도 있습니다.

로깅

.NET Aspire SQL Server 통합은 현재 Microsoft.Data.SqlClient의 제한 때문에 기본 설정으로 로깅을 활성화하지 않습니다.

추적

.NET Aspire SQL Server 통합은 OpenTelemetry를 사용하여 다음과 같은 추적 활동을 방출한다.

• OpenTelemetry.Instrumentation.SqlClient

측정지표

.NET Aspire SQL Server 통합은 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

참고

• Azure SQL Database
• SQL Server
• .NET .NET Aspire 데이터베이스 컨테이너 샘플
• .NET .NET Aspire 통합
• .NET Aspire GitHub 리포지토리