.NET Aspire SQL Server Entity Framework Core entegrasyonu

Içerir: Barındırma tümleştirmesi —& Client tümleştirme

SQL Server, Microsoft tarafından geliştirilen ilişkisel bir veritabanı yönetim sistemidir. .NET Aspire SQL Server Entity Framework Core tümleştirmesi, SQL Serverile mevcut .NET örneklerine bağlanmanızı veya mcr.microsoft.com/mssql/server'den yeni örnekler oluşturmanızı sağlar.

Barındırma entegrasyonu

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 📦Aspire.Hosting.SqlServer NuGet paketini, uygulama konağı projesine ekleyin.

.NET CLI

dotnet add package Aspire.Hosting.SqlServer

PackageReference

<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ğını ve veritabanı kaynağını ekle

Uygulama ana bilgisayar projenizde AddSqlServer öğesini çağırıp bir SQL Server kaynak oluşturucu ekleyin ve döndürün. Döndürülen kaynak oluşturucusunun AddDatabase çağrısını, SQL Server veritabanı kaynağı eklemek için zincirleyin.

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();

Not

SQL Server kapsayıcısı yavaş başlatıldığından, gereksiz yeniden başlatmaları önlemek için kalıcı yaşam süresi kullanmak en iyisidir. Daha fazla bilgi için Kapsayıcı kaynak ömrünebakın.

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

Uygulama modeline bir veritabanı kaynağı eklenirken, veritabanı henüz mevcut değilse oluşturulur. Veritabanının oluşturulması, özellikle ResourceReadyEvent kullanır. Başka bir deyişle, kaynak sql olduğunda olay tetiklenir ve ardından veritabanı kaynağı oluşturulur.

SQL Server kaynağı, username'i sa ve password yöntemi kullanılarak oluşturulan rastgele bir CreateDefaultPasswordParameter ile beraber varsayılan kimlik bilgilerini içerir.

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

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

Parametrenin adı sql-password'dır, ancak aslında yalnızca kaynak adını -password sonekiyle biçimlendirmektir. Daha fazla bilgi için bkz. geliştirme aşamasında uygulama gizli bilgilerini güvenli şekilde depolama ve ASP.NET Core ve ekle SQL Server kaynağınıparametreleriyle.

WithReference yöntemi, ExampleProject içinde databaseadlı bir bağlantıyı yapılandırıyor.

Bahşiş

Mevcut bir SQL Serverbağlanmak isterseniz bunun yerine AddConnectionString'ı arayın. Daha fazla bilgi için bkz. Var olan kaynaklara başvurma.

SQL Server kaynağını veritabanı betikleriyle ekle

Varsayılan olarak, bir SqlServerDatabaseResourceeklediğinizde veritabanı oluşturmak için aşağıdaki SQL betiğine dayanır:

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

Varsayılan betiği değiştirmek için veritabanı kaynak oluşturucusunun WithCreationScript yöntemine bir çağrı zincirleyin:

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();

Yukarıdaki örnek, app_db adlı, tek bir todos tablo içeren bir veritabanı oluşturur. Veritabanı kaynağı oluşturulduğunda SQL betiği yürütülür. Betik, bir dize olarak yöntem WithCreationScript'a iletilir ve ardından kaynak SQL Server bağlamında yürütülür.

Veri hacmi ile SQL Server kaynağı ekle

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

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

builder.Build().Run();

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. Daha fazla bilgi almak ve bağlamalar yerine veri hacimlerini neden tercih ettiğimiz konusunda ayrıntılar için belgeler: Birimler'e bakın.

Uyarı

Parola, veri biriminde depolanır. Veri birimi kullanıyorsanız ve parola değişirse, siz birimi silene kadar veri birimi çalışmaz.

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

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

builder.Build().Run();

Önemli

Veri bağlama bağlamaları, daha iyi performans, taşınabilirlik ve güvenlik sunanbirimleriyle karşılaştırıldığında sınırlı işlevselliğe sahiptir ve bu da üretim ortamları için daha uygun olmasını sağlar. Ancak bağlama noktaları, gerçek zamanlı değişikliklerin gerekli olduğu geliştirme ve test süreçlerinde ideal olan konak sistemindeki dosyalara doğrudan erişim ve değişiklik yapma imkanı tanır.

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

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

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

builder.Build().Run();

Parametreleri sağlama hakkında daha fazla bilgi için bkz. harici 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.

SQL Server Yönetim Stüdyosu

SQL Server Management Studio'dan veritabanı kaynağına bağlanmak için şu adımları izleyin:

1. SSMS'i açın.

2. Server dialog kutusunda, Ek Bağlantı Parametreleri sekmesini seçin.

3. Bağlantı dizesini Ek Bağlantı Parametreleri alanına yapıştırın ve Bağlanseçeneğini belirleyin.

   

4. Bağlıysanız, veritabanı kaynağını Nesne Gezginigörebilirsiniz:

   

Daha fazla bilgi için bkz. SQL Server Management Studio:sunucuya bağlanma.

MSSQL için Visual Studio Code

Visual Studio Codeiçin MSSQL'den veritabanı kaynağına bağlanmak için şu adımları izleyin:

1. SQL SERVER uzantısını açın.

2. CONNECTIONSaltındaki Bağlantı Ekle seçeneğini belirleyin.

   Visual Studio Codeiçin MSSQL

3. Giriş türüBağlantı dizesi olarak değiştirin ve bağlantı dizesini Bağlantı dizesi alanına yapıştırın.

4. seçin,bağlan'ı.

   MSSQL için Visual Studio Code: Bağlantı dizesi giriş ayrıntıları.

5. Bağlandıktan sonra, etkin sekmede veritabanı kaynağını görebilir ve buna yönelik sorgular çalıştırabilirsiniz:

   Visual Studio Codeiçin MSSQL

Daha fazla bilgi için MSSQL için Visual Studio Codebakın.

Barındırma entegrasyonu sağlık kontrolü

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

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

Client tümleştirmesi

.NET Aspire SQL Server Entity Framework Core tümleştirmesini kullanmaya başlamak için, 📦Aspireyükleyin. Microsoft.EntityFrameworkCore.SqlServer NuGet paketini, istemciyi kullanan projede yani SQL ServerEntity Framework Core istemcisini kullanan uygulamanın projesinde.

.NET CLI

dotnet add package Aspire.Microsoft.EntityFrameworkCore.SqlServer

PackageReference

<PackageReference Include="Aspire.Microsoft.EntityFrameworkCore.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 veritabanı bağlamını ekleme

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

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

Bahşiş

connectionName parametresi, uygulama ana bilgisayar projesine SQL Server veritabanı kaynağı eklenirken kullanılan adla eşleşmelidir. Başka bir deyişle, AddDatabase'ı çağırdığınızda ve database olarak bir ad sağladığınızda, aynı adın AddSqlServerDbContextçağrılırken de kullanılması gerekir. Daha fazla bilgi için bkz. SQL Server kaynağını ekleyin ve veritabanı kaynağı.

Bir hizmetten ExampleDbContext nesnesi almak için:

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

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

Bir SQL Server veritabanı bağlamını zenginleştir.

Veritabanı bağlamını almak ve bunu bağımlılık ekleme kapsayıcısına eklemek için standart Entity Framework yöntemini kullanmayı tercih edebilirsiniz:

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

Not

GetConnectionString yöntemine geçirdiğiniz bağlantı dizesi adı, uygulama ana bilgisayar projesine SQL server kaynağı eklenirken kullanılan adla eşleşmelidir. Daha fazla bilgi için bkz. SQL Server kaynağını ekleyin ve veritabanı kaynağı.

Veritabanı bağlamını bu şekilde oluştururken daha fazla esnekliğe sahip olursunuz, örneğin:

• var olan yapılandırma kodunu .NET.NET Aspireiçin yeniden yazmadan veritabanı bağlamı için yeniden kullanabilirsiniz.
• Veritabanı işlemlerini değiştirmek için Entity Framework Core önleyiciler kullanabilirsiniz.
• Bazı durumlarda daha iyi performans gösterebilecek Entity Framework Core bağlam havuzu kullanmamayı seçebilirsiniz.

Bu yöntemi kullanırsanız, .NET yöntemini çağırarak veritabanı bağlamını .NET AspireEnrichSqlServerDbContextstili yeniden denemeler, sistem durumu denetimleri, günlüğe kaydetme ve telemetri özellikleriyle geliştirebilirsiniz:

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

settings parametresi, MicrosoftEntityFrameworkCoreSqlServerSettings sınıfının bir örneğidir.

Konfigürasyon

.NET Aspire SQL Server Entity Framework Core 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ı dizesini kullanma

ConnectionStrings yapılandırma bölümünden bir bağlantı dizesi kullanırken, builder.AddSqlServerDbContext<TContext>()çağırırken bağlantı dizesinin adını sağlarsınız:

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

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

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

EnrichSqlServerDbContext, ConnectionStrings'nin çağrıldığı anda kaydedilmesini beklediğinden DbContext yapılandırma bölümünden yararlanmaz.

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

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

Bu .NET AspireSQL ServerEntity Framework Core tümleştirmesi Microsoft.Extensions.Configurationdestekliyor. MicrosoftEntityFrameworkCoreSqlServerSettings anahtarını kullanarak appsettings.json gibi yapılandırma dosyalarından Aspire:Microsoft:EntityFrameworkCore:SqlServer yükler. yapılandırmalarınızı Aspire:Microsoft:EntityFrameworkCore:SqlServer bölümünde ayarladıysanız herhangi bir parametre geçirmeden yöntemini çağırabilirsiniz.

Aşağıda, kullanılabilir seçeneklerden bazılarını yapılandıran bir appsettings.json dosyası örneği verilmiştir:

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

Satır içi yapılandırmaları kullanma

Ayrıca Action<MicrosoftEntityFrameworkCoreSqlServerSettings> temsilcisini geçirerek satır içi seçeneklerin bazılarını veya tümünü ayarlayabilirsiniz; örneğin ölçümleri kapatabilirsiniz:

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

Birden çok DbContext bağlantısı yapılandırma

Farklı yapılandırmaya sahip birden fazla DbContext kaydetmek istiyorsanız, $"Aspire.Microsoft.EntityFrameworkCore.SqlServer:{typeof(TContext).Name}" yapılandırma bölümü adını kullanabilirsiniz. Json yapılandırması şöyle görünür:

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

Ardından AddSqlServerDbContext yönteminin AnotherDbContext tür parametresiyle çağrılması, ayarları Aspire:Microsoft:EntityFrameworkCore:SqlServer:AnotherDbContext bölümden yükler.

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

Yapılandırma seçenekleri

buna karşılık gelen varsayılan değerlere sahip yapılandırılabilir seçenekler şunlardır:

İsim	Açıklama
ConnectionString	Bağlanacak SQL Server veritabanının bağlantı dizesi.
DbContextPooling	Her istenildiğinde veritabanı bağlamının havuza alınıp alınmayacağını veya her seferinde özel olarak oluşturulup oluşturulmayacağını gösteren bir boole değeri.
MaxRetryCount	Yeniden deneme denemesi sayısı üst sınırı. Varsayılan değer 6'dır, yeniden deneme mekanizmasını devre dışı bırakmak için 0 olarak ayarlayın.
DisableHealthChecks	Veritabanı sistem durumu denetiminin devre dışı bırakılıp bırakılmadığını gösteren boole değeri.
DisableTracing	OpenTelemetry izlemesinin devre dışı bırakılıp bırakılmadığını gösteren bir Boolean değeri.
DisableMetrics	OpenTelemetry ölçümlerinin devre dışı bırakılıp bırakılmadığını gösteren boole değeri.
Timeout	Komutun yürütülmesini beklemek için saniye cinsinden süre.

Client entegrasyon sağlık kontrolleri

Varsayılan olarak, .NET.NET Aspireistemci entegrasyonları, tüm hizmetler için sağlık kontrolleri etkin olacak şekilde yapılandırılmıştır. 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

Varsayılan olarak, .NET Aspire Sql ServerEntity Framework Core tümleştirmesi aşağıdakileri işler:

• DbContextHealthCheckekleyen, EF Core'in CanConnectAsync yöntemini çağırır. Sağlık kontrolünün adı, TContext türünün adıdı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

.NET .NET Aspire tümleştirmeleri, genellikle gözlemlenebilirliğin dayanakları olarak bilinen Günlük, İzleme ve Metrik 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 günlük kaydını ve izlemeyi destekler, ancak metrikleri 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 Entity Framework Core entegrasyonu aşağıdaki log kategorilerini kullanır:

• 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

İz Sürme

.NET Aspire SQL Server Entity Framework Core tümleştirmesi, OpenTelemetrykullanarak aşağıdaki İzleme aktivitelerini yayar:

• "OpenTelemetry. Instrumentation.EntityFrameworkCore"

Ölçüm

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

• 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

Ayrıca bkz.

• SQL Veritabanı belgeleri
• .NET .NET Aspire tümleştirmeleri
• .NET Aspire GitHub Repo