.NET Aspire SQL Server Entity Framework Core 통합

포함: 호스팅 통합 -&— Client 통합

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

호스팅 통합

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

dotnet add package Aspire.Hosting.SqlServer

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

자세한 내용은 dotnet add package 또는 응용프로그램에서 패키지 종속성 관리 .NET.

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>("exampleproject")
       .WithReference(db)
       .WaitFor(db);

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

builder.Build().Run();

.NET .NET Aspire mcr.microsoft.com/mssql/server 이미지와 함께 이전 예제와 같이 앱 호스트에 컨테이너 이미지를 추가하면 로컬 컴퓨터에 새 SQL Server 인스턴스가 만들어집니다. SQL Server 리소스 작성기(sql 변수)에 대한 참조는 데이터베이스를 추가하는 데 사용됩니다. 데이터베이스의 이름은 database이며, 그 후 ExampleProject에 추가됩니다.

앱 모델에 데이터베이스 리소스를 추가할 때 데이터베이스가 아직 없는 경우 만들어집니다. 데이터베이스 생성은 특히 앱 호스트 이벤트 API에 의존합니다 ResourceReadyEvent. 즉, 리소스가 sql준비되면 이벤트가 발생하고 데이터베이스 리소스가 만들어집니다.

SQL Server 리소스에는 username의 sa 및 password 방법을 사용하여 생성된 임의의 CreateDefaultPasswordParameter이 있는 기본 자격 증명이 포함되어 있습니다.

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

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

매개 변수의 이름은 sql-password, 실제로는 리소스 이름에 -password 접미사를 사용하여 서식을 지정하는 것입니다. 자세한 내용은 ASP.NET Core를 참조하시고, 를 참조하세요.

WithReference 메서드는 ExampleProject로 명명된 연결 database를 구성합니다.

데이터베이스 스크립트를 사용하여 리소스 추가 SQL Server

기본적으로 추가 SqlServerDatabaseResource하면 다음 SQL 스크립트를 사용하여 데이터베이스를 만듭니다.

IF
(
    NOT EXISTS
    (
        SELECT 1
        FROM sys.databases
        WHERE name = @DatabaseName
    )
)
CREATE DATABASE [<QUOTED_DATABASE_NAME>];

기본 스크립트를 변경하려면 데이터베이스 리소스 작성기에서 WithCreationScript 메서드에 대한 호출을 연결합니다.

var builder = DistributedApplication.CreateBuilder(args);

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

var databaseName = "app-db";
var creationScript = $$"""
    IF DB_ID('{{databaseName}}') IS NULL
        CREATE DATABASE [{{databaseName}}];
    GO

    -- Use the database
    USE [{{databaseName}}];
    GO

    -- Create the todos table
    CREATE TABLE todos (
        id INT PRIMARY KEY IDENTITY(1,1),        -- Unique ID for each todo
        title VARCHAR(255) NOT NULL,             -- Short description of the task
        description TEXT,                        -- Optional detailed description
        is_completed BIT DEFAULT 0,              -- Completion status
        due_date DATE,                           -- Optional due date
        created_at DATETIME DEFAULT GETDATE()    -- Creation timestamp
    );
    GO

    """;

var db = sql.AddDatabase(databaseName)
            .WithCreationScript(creationScript);

builder.AddProject<Projects.AspireApp_ExampleProject>("exampleproject")
       .WithReference(db)
       .WaitFor(db);

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

builder.Build().Run();

앞의 예제에서는 단일 app_db 테이블로 명명된 todos 데이터베이스를 만듭니다. SQL 스크립트는 데이터베이스 리소스를 만들 때 실행됩니다. 스크립트는 메서드에 WithCreationScript 문자열로 전달된 다음 리소스의 SQL Server 컨텍스트에서 실행됩니다.

데이터 볼륨을 사용하여 SQL Server 리소스 추가

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

var builder = DistributedApplication.CreateBuilder(args);

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

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

builder.AddProject<Projects.AspireApp_ExampleProject>("exampleproject")
       .WithReference(db)
       .WaitFor(db);

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

builder.Build().Run();

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

데이터 바인드 마운트를 사용하여 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.AspireApp_ExampleProject>("exampleproject")
       .WithReference(db)
       .WaitFor(db);

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

builder.Build().Run();

데이터 바인딩 탑재는 호스트 컴퓨터의 파일 시스템을 사용하여 컨테이너를 다시 시작하는 동안 SQL Server 데이터를 유지합니다. 데이터 바인드 마운트는 C:\SqlServer\Data 컨테이너의 호스트 컴퓨터에서 Windows의 /SqlServer/Data 경로(또는 Unix의 SQL Server 경로)에 마운트됩니다. 데이터 바인드 마운트에 대한 자세한 내용은 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.AspireApp_ExampleProject>("exampleproject")
       .WithReference(db)
       .WaitFor(db);

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

builder.Build().Run();

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

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

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

호스트 통합 시스템 상태 점검

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

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

Client 통합

.NET Aspire SQL Server Entity Framework Core 통합을 시작하려면, 📦Aspire를 설치하십시오. 이는 Microsoft.EntityFrameworkCore.SqlServer NuGet 패키지를, 즉 SQL ServerEntity Framework Core 클라이언트를 사용하는 애플리케이션의 프로젝트인 클라이언트 사용 프로젝트에 설치하는 것입니다.

dotnet add package Aspire.Microsoft.EntityFrameworkCore.SqlServer

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

자세한 내용은 dotnet add package 또는 응용프로그램에서 패키지 종속성 관리 .NET.

SQL Server 데이터베이스 컨텍스트 추가

클라이언트 사용 프로젝트의 Program.cs 파일에서 모든 AddSqlServerDbContext에 대해 IHostApplicationBuilder 확장 메서드를 호출하여 종속성 주입 컨테이너를 통해 사용할 수 있도록 DbContext을 등록하십시오. 메서드는 연결 이름 매개 변수를 사용합니다.

builder.AddSqlServerDbContext<ExampleDbContext>(connectionName: "database");

서비스에서 ExampleDbContext 개체를 검색하려면 다음을 수행합니다.

public class ExampleService(ExampleDbContext context)
{
    // Use context...
}

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

SQL Server 데이터베이스 컨텍스트 보강

표준 Entity Framework 메서드를 사용하여 데이터베이스 컨텍스트를 가져오고 종속성 주입 컨테이너에 추가하는 것이 좋습니다.

builder.Services.AddDbContext<ExampleDbContext>(options =>
    options.UseSqlServer(builder.Configuration.GetConnectionString("database")
        ?? throw new InvalidOperationException("Connection string 'database' not found.")));

이러한 방식으로 데이터베이스 컨텍스트를 만들 때 유연성이 더 높습니다. 예를 들면 다음과 같습니다.

• .NET .NET Aspire위해 다시 작성하지 않고 데이터베이스 컨텍스트에 기존 구성 코드를 다시 사용할 수 있습니다.
• Entity Framework Core 인터셉터를 사용하여 데이터베이스 작업을 수정할 수 있습니다.
• 상황에 따라 더 나은 성능을 발휘할 수 있는 Entity Framework Core 컨텍스트 풀링을 사용하지 않도록 선택할 수 있습니다.

이 메서드를 사용하는 경우 .NET 메서드를 호출하여 .NET AspireEnrichSqlServerDbContext스타일 재시도, 상태 검사, 로깅 및 원격 분석 기능을 사용하여 데이터베이스 컨텍스트를 향상시킬 수 있습니다.

builder.EnrichSqlServerDbContext<ExampleDbContext>(
    configureSettings: settings =>
    {
        settings.DisableRetry = false;
        settings.CommandTimeout = 30; // seconds
    });

settings 매개 변수는 MicrosoftEntityFrameworkCoreSqlServerSettings 클래스의 인스턴스입니다.

구성

.NET Aspire SQL Server Entity Framework Core 통합은 프로젝트의 요구 사항 및 규칙을 충족하는 여러 구성 접근 방식과 옵션을 제공합니다.

연결 문자열 사용

ConnectionStrings 구성 섹션에서 연결 문자열을 사용하는 경우 builder.AddSqlServerDbContext<TContext>()호출할 때 연결 문자열의 이름을 제공합니다.

builder.AddSqlServerDbContext<ExampleDbContext>("sql");

연결 문자열은 ConnectionStrings 구성 섹션에서 검색됩니다.

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

EnrichSqlServerDbContext 호출되는 시점에 ConnectionStrings 등록될 것으로 예상하기 때문에 DbContext 구성 섹션을 사용하지 않습니다.

자세한 내용은 ConnectionString참조하세요.

구성 공급자 사용

.NET Aspire SQL Server Entity Framework Core 통합은 Microsoft.Extensions.Configuration지원합니다. MicrosoftEntityFrameworkCoreSqlServerSettings 키를 사용하여 appsettings.json 같은 구성 파일에서 Aspire:Microsoft:EntityFrameworkCore:SqlServer 로드합니다. Aspire:Microsoft:EntityFrameworkCore:SqlServer 섹션에서 구성을 설정한 경우 매개 변수를 전달하지 않고 메서드를 호출할 수 있습니다.

다음은 사용 가능한 옵션 중 일부를 구성하는 appsettings.json 파일의 예입니다.

{
  "Aspire": {
    "Microsoft": {
      "EntityFrameworkCore": {
        "SqlServer": {
          "ConnectionString": "YOUR_CONNECTIONSTRING",
          "DbContextPooling": true,
          "DisableHealthChecks": true,
          "DisableTracing": true,
          "DisableMetrics": false
        }
      }
    }
  }
}

인라인 구성 사용

Action<MicrosoftEntityFrameworkCoreSqlServerSettings> 대리자를 전달하여 일부 또는 모든 옵션을 인라인으로 설정할 수도 있습니다. 예를 들어 메트릭을 해제할 수 있습니다.

builder.AddSqlServerDbContext<YourDbContext>(
    "sql",
    static settings =>
        settings.DisableMetrics = true);

여러 DbContext 연결 구성

서로 다른 구성으로 둘 이상의 DbContext 등록하려는 경우 $"Aspire.Microsoft.EntityFrameworkCore.SqlServer:{typeof(TContext).Name}" 구성 섹션 이름을 사용할 수 있습니다. json 구성은 다음과 같습니다.

{
  "Aspire": {
    "Microsoft": {
      "EntityFrameworkCore": {
          "SqlServer": {
            "ConnectionString": "YOUR_CONNECTIONSTRING",
            "DbContextPooling": true,
            "DisableHealthChecks": true,
            "DisableTracing": true,
            "DisableMetrics": false,
          "AnotherDbContext": {
            "ConnectionString": "AnotherDbContext_CONNECTIONSTRING",
            "DisableTracing": false
          }
        }
      }
    }
  }
}

그런 다음 AddSqlServerDbContext 형식 매개 변수를 사용하여 AnotherDbContext 메서드를 호출하면 Aspire:Microsoft:EntityFrameworkCore:SqlServer:AnotherDbContext 섹션에서 설정이 로드됩니다.

builder.AddSqlServerDbContext<AnotherDbContext>("another-sql");

구성 옵션

해당 기본값을 사용하여 구성할 수 있는 옵션은 다음과 같습니다.

Client 통합 상태 검사

기본적으로 .NET.NET Aspire클라이언트 통합에는 모든 서비스에 대해 상태 검사 사용하도록 설정될 있습니다. 마찬가지로, 많은 .NET.NET Aspire호스팅 통합도 상태 검사 엔드포인트를 활성화합니다. 자세한 내용은 다음을 참조하세요.

• .NET C# 애플리케이션 상태 검사
• ASP.NET Core 의 상태 검사

기본적으로 .NET Aspire Sql ServerEntity Framework Core 통합은 다음을 처리합니다.

• DbContextHealthCheck을 추가하여 EF Core의 CanConnectAsync 메서드를 호출합니다. 상태 검사의 이름은 TContext 형식의 이름에서 유래한 것입니다.
• 등록된 모든 상태 검사를 통과해야 트래픽을 허용할 준비가 된 것으로 간주되도록 지정하는 /health HTTP 엔드포인트와 통합됩니다.

관찰 가능성 및 원격 분석

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

로깅

.NET Aspire SQL Server Entity Framework Core 통합에서는 다음 로그 범주를 사용합니다.

• Microsoft.EntityFrameworkCore.ChangeTracking
• Microsoft.EntityFrameworkCore.Database.Command
• Microsoft.EntityFrameworkCore.Database.Connection
• Microsoft.EntityFrameworkCore.Database.Transaction
• Microsoft.EntityFrameworkCore.Infrastructure
• Microsoft.EntityFrameworkCore.Migrations
• Microsoft.EntityFrameworkCore.Model
• Microsoft.EntityFrameworkCore.Model.Validation
• Microsoft.EntityFrameworkCore.Query
• Microsoft.EntityFrameworkCore.Update

추적

.NET Aspire SQL Server Entity Framework Core 통합은 OpenTelemetry사용하여 다음 추적 작업을 내보낸다.

• "OpenTelemetry. Instrumentation.EntityFrameworkCore"

지표

.NET Aspire SQL Server Entity Framework Core 통합은 OpenTelemetry사용하여 다음 메트릭을 내보낸다.

• Microsoft.EntityFrameworkCore:
  • ec_Microsoft_EntityFrameworkCore_active_db_contexts
  • ec_Microsoft_EntityFrameworkCore_total_queries
  • ec_Microsoft_EntityFrameworkCore_queries_per_second
  • ec_Microsoft_EntityFrameworkCore_total_save_changes
  • ec_Microsoft_EntityFrameworkCore_save_changes_per_second
  • ec_Microsoft_EntityFrameworkCore_compiled_query_cache_hit_rate
  • ec_Microsoft_Entity_total_execution_strategy_operation_failures
  • ec_Microsoft_E_execution_strategy_operation_failures_per_second
  • ec_Microsoft_EntityFramew_total_optimistic_concurrency_failures
  • ec_Microsoft_EntityF_optimistic_concurrency_failures_per_second

참고하기

• Azure SQL Database 설명서
• .NET .NET Aspire 통합
• .NET Aspire GitHub 리포지토리