Partilhar via

.NET Aspire SQL Server integração

  • Artigo

Inclui:integração de hospedagem e integração Client

SQL Server é um sistema de gerenciamento de banco de dados relacional desenvolvido pela Microsoft. A integração .NET AspireSQL Server permite que você se conecte a instâncias de SQL Server existentes ou crie novas instâncias a partir de .NET com a imagem de contêiner mcr.microsoft.com/mssql/server.

Integração de hospedagem

A integração de hospedagem SQL Server modela o server como o tipo SqlServerServerResource e o banco de dados como o tipo SqlServerDatabaseResource. Para acessar esses tipos e APIs, adicione o 📦Aspire. Hosting.SqlServer pacote NuGet no aplicativo host projeto.

dotnet add package Aspire.Hosting.SqlServer

Para obter mais informações, consulte dotnet add package ou Gerir dependências de pacotes em aplicações .NET.

Adicionar o recurso SQL Server e o recurso de banco de dados

No seu projeto de host de aplicação, chame AddSqlServer para adicionar e retornar um construtor de recursos SQL Server. Encadeie uma chamada ao construtor de recursos retornado para AddDatabase, a fim de adicionar recurso de banco de dados 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...

Observação

O contêiner SQL Server é lento para iniciar, por isso é melhor usar uma vida útil persistente para evitar reinicializações desnecessárias. Para obter mais informações, consulte Tempo de vida do recurso de contêiner.

Quando .NET.NET Aspire adiciona uma imagem de contêiner ao host do aplicativo, como mostrado no exemplo anterior com a imagem mcr.microsoft.com/mssql/server, ele cria uma nova instância de SQL Server em sua máquina local. Uma referência ao seu SQL Server construtor de recursos (a variável sql) é usada para adicionar um banco de dados. O banco de dados é nomeado database e, em seguida, adicionado ao ExampleProject. O recurso SQL Server inclui credenciais padrão com um username de sa e um password aleatório gerado usando o método CreateDefaultPasswordParameter.

Quando o host da aplicação é executado, a palavra-passe é armazenada no armazenamento secreto do host da aplicação. Ele é adicionado à seção Parameters, por exemplo:

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

O nome do parâmetro é sql-password, mas na verdade é apenas formatar o nome do recurso com um sufixo -password. Para obter mais informações, consulte Armazenamento seguro de segredos de aplicativos em desenvolvimento no ASP.NET Core e Adicionar SQL Server recurso com parâmetros.

O método WithReference configura uma conexão no ExampleProject chamado database.

Dica

Se preferir ligar para um SQL Serverexistente, contacte AddConnectionString em vez disso. Para obter mais informações, consulte Consulte recursos existentes.

Adicionar recurso SQL Server com volume de dados

Para adicionar um volume de dados ao recurso SQL Server, chame o método WithDataVolume no recurso 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...

O volume de dados é usado para manter os dados SQL Server fora do ciclo de vida de seu contêiner. O volume de dados é montado no caminho /var/opt/mssql no contêiner SQL Server e, quando um parâmetro name não é fornecido, o nome é gerado aleatoriamente. Para obter mais informações sobre volumes de dados e detalhes sobre porque eles são preferidos em relação aos "bind mounts" , consulte os documentos Docker: Volumes.

Advertência

A senha é armazenada no volume de dados. Ao usar um volume de dados e se a senha for alterada, ela não funcionará até que você exclua o volume.

Adicionar SQL Server recurso com montagem de associação de dados

Para adicionar uma montagem de ligação de dados ao recurso SQL Server, chame o método 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...

Importante

Os suportes de ligação de de dados têm funcionalidade limitada em comparação com volumes, que oferecem melhor desempenho, portabilidade e segurança, tornando-os mais adequados para ambientes de produção. No entanto, as montagens bind permitem o acesso direto e a modificação de arquivos no sistema host, ideal para desenvolvimento e testes onde alterações em tempo real são necessárias.

As montagens de associação de dados dependem do sistema de arquivos da máquina anfitriã para manter os dados SQL Server nas reinicializações do contêiner. A montagem de associação de dados é montada no caminho C:\SqlServer\Data no Windows (ou /SqlServer/Data no Unix) na máquina host no contêiner SQL Server. Para obter mais informações sobre montagens de dados, consulte a documentação em Docker: Montagens de dados.

Adicionar SQL Server recurso com parâmetros

Quando quiser fornecer explicitamente a senha usada pela imagem do contêiner, você poderá fornecer essas credenciais como parâmetros. Considere o seguinte exemplo alternativo:

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

Para obter mais informações sobre como fornecer parâmetros, consulte Parâmetros externos.

Conectar-se a recursos de banco de dados

Quando o host da aplicação .NET Aspire é executado, os recursos da base de dados do serverpodem ser acedidos a partir de ferramentas externas, como o SQL Server Management Studio (SSMS) ou o Azure Data Studio. A cadeia de conexão para o recurso de banco de dados está disponível nas variáveis de ambiente de recursos dependentes e é acessada usando o dashboard .NET.NET Aspire: seção de Detalhes do recurso. A variável de ambiente é nomeada ConnectionStrings__{name} onde {name} é o nome do recurso de banco de dados, neste exemplo é database. Use a cadeia de conexão para se conectar ao recurso de banco de dados a partir de ferramentas externas. Imagine que você tem um banco de dados chamado todos com uma única tabela dbo.Todos.

Para se conectar ao recurso de banco de dados a partir do SQL Server Management Studio, siga estas etapas:

  1. Abra o SSMS.

  2. Na caixa de diálogo Conectar a Server, selecione a guia Parâmetros Adicionais de Conexão.

  3. Cole a cadeia de conexão no campo Parâmetros adicionais de conexão e selecione Conectar.

    SQL Server Management Studio: Conecte-se à janela de diálogo Server.

  4. Se você estiver conectado, poderá ver o recurso de banco de dados no Pesquisador de Objetos:

    SQL Server Management Studio: Conectado ao banco de dados.

Para obter mais informações, consulte SQL Server Management Studio: Conectar-se a um server.

Verificações de integridade da integração de hospedagem

A integração de hospedagem SQL Server adiciona automaticamente uma verificação de integridade para o recurso SQL Server. A verificação de integridade verifica se o SQL Server está em execução e se uma conexão pode ser estabelecida com ele.

A integração de hospedagem depende do 📦 pacote AspNetCore.HealthChecks.SqlServer NuGet.

Client integração

Para começar com a integração .NET AspireSQL Serverclient, instale o pacote NuGet 📦Aspire.Microsoft.Data.SqlClient no projeto consumidor client, isto é, o projeto para a aplicação que usa o SQL Serverclient. A integração SQL Serverclient registra uma instância SqlConnection que você pode usar para interagir com SQL Server.

dotnet add package Aspire.Microsoft.Data.SqlClient

Adicionar SQL Serverclient

No arquivo de Program.cs do seu projeto consumidor de client, chame o método de extensão AddSqlServerClient em qualquer IHostApplicationBuilder para registar um SqlConnection para uso por meio do contentor de injeção de dependência. O método usa um parâmetro de nome de conexão.

builder.AddSqlServerClient(connectionName: "database");

Dica

O parâmetro connectionName deve corresponder ao nome usado ao adicionar o recurso de banco de dados SQL Server no projeto host do aplicativo. Em outras palavras, quando você chama AddDatabase e fornece um nome de database esse mesmo nome deve ser usado ao chamar AddSqlServerClient. Para obter mais informações, consulte Adicione os recursos SQL Server e de banco de dados.

Em seguida, você pode recuperar a instância SqlConnection usando a injeção de dependência. Por exemplo, para recuperar a conexão de um serviço de exemplo:

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

Para obter mais informações sobre a injeção de dependência, consulte .NET injeção de dependência.

Adicionar SQL Serverclient com chave

Pode haver situações em que você queira registrar várias instâncias de SqlConnection com nomes de conexão diferentes. Para registrar clientes SQL Server chaveados, chame o método AddKeyedSqlServerClient:

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

Importante

Ao usar serviços com chave, espera-se que seu recurso SQL Server configure dois bancos de dados nomeados, um para o mainDb e outro para o loggingDb.

Em seguida, você pode recuperar as instâncias SqlConnection usando a injeção de dependência. Por exemplo, para recuperar a conexão de um serviço de exemplo:

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

Para obter mais informações sobre serviços com chave, consulte .NET injeção de dependência: Serviços com chave.

Configuração

A integração .NET AspireSQL Server fornece várias opções para configurar a conexão com base nos requisitos e convenções do seu projeto.

Usar uma cadeia de ligação

Ao usar uma cadeia de conexão da seção de configuração de ConnectionStrings, você pode fornecer o nome da cadeia de conexão ao chamar o método AddSqlServerClient:

builder.AddSqlServerClient(connectionName: "sql");

Em seguida, a cadeia de conexão é recuperada da seção de configuração ConnectionStrings:

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

Para obter mais informações sobre como formatar essa cadeia de conexão, consulte o ConnectionString.

Usar provedores de configuração

A integração .NET AspireSQL Server suporta Microsoft.Extensions.Configuration. Ele carrega o MicrosoftDataSqlClientSettings da configuração usando a chave Aspire:Microsoft:Data:SqlClient. O trecho a seguir é um exemplo de um arquivo de appsettings.json que configura algumas das opções:

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

Para obter a SQL Serverclient completa integração JSON esquema, consulte Aspire. Microsoft.Data.SqlClient/ConfigurationSchema.json.

Usar delegados em linha

Além disso, você pode passar o Action<MicrosoftDataSqlClientSettings> configureSettings delegado para configurar algumas ou todas as opções embutidas, por exemplo, para desativar as verificações de integridade do código:

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

Client verificação de estado de integração

Por padrão, as integrações .NET.NET Aspire habilitam verificações de integridade para todos os serviços. Para obter mais informações, consulte .NET.NET Aspire visão geral das integrações.

A integração .NET AspireSQL Server:

  • Adiciona a verificação de integridade quando MicrosoftDataSqlClientSettings.DisableHealthChecks é false, que tenta se conectar ao SQL Server.
  • Integra-se com o ponto de extremidade HTTP /health, que especifica que todas as verificações de saúde registadas devem ser bem-sucedidas para que a aplicação seja considerada pronta para aceitar tráfego.

Observabilidade e telemetria

.NET .NET Aspire integrações configuram automaticamente o Registo, Rastreio e Métricas, que são às vezes conhecidos como os pilares da observabilidade. Para obter mais informações sobre observabilidade e telemetria de integração, consulte Visão geral de integrações .NET.NET Aspire. Dependendo do serviço de suporte, algumas integrações podem suportar apenas alguns desses recursos. Por exemplo, algumas integrações suportam registro em log e rastreamento, mas não métricas. Os recursos de telemetria também podem ser desativados usando as técnicas apresentadas na secção Configuração.

Registo

A integração .NET AspireSQL Server atualmente não permite o registro em log por padrão devido a limitações do Microsoft.Data.SqlClient.

Rastreio

A integração .NET AspireSQL Server emite as seguintes atividades de rastreio utilizando OpenTelemetry:

  • OpenTelemetry.Instrumentation.SqlClient

Métricas

A integração .NET AspireSQL Server emitirá as seguintes métricas usando 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

Ver também