integração .NET AspireSQL Server
Inclui:
integração de hospedagem e integraçãoClient
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 de .NET com a imagem de contêiner mcr.microsoft.com/mssql/server.
Integração de hospedagem
A integração de hospedagem do 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 pacote NuGet 📦Aspire.Hosting.SqlServer no projeto do host do aplicativo .
dotnet add package Aspire.Hosting.SqlServer
Para obter mais informações, consulte dotnet add package ou Gerenciar dependências de pacotes em aplicações .NET.
Adicionar recurso SQL Server e recurso de banco de dados
No projeto de host do aplicativo, chame AddSqlServer para adicionar e retornar um gerador de recursos SQL Server. Encadear uma chamada ao construtor do recurso retornado para AddDatabase, a fim de adicionar o 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...
Nota
O contêiner
Quando .NET.NET Aspire adiciona uma imagem de contêiner ao host do aplicativo, conforme mostrado no exemplo anterior com a imagem mcr.microsoft.com/mssql/server, ele cria uma nova instância de SQL Server em seu computador local. Uma referência ao construtor de recursos SQL Server (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 do aplicativo é executado, a senha é armazenada no repositório secreto do host do aplicativo. 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 do aplicativo no desenvolvimento em ASP.NET Core e Adicionar SQL Server recurso com parâmetros.
O método WithReference configura uma conexão no ExampleProject denominado database.
Dica
Se você preferir se conectar a um SQL Serverexistente, chame AddConnectionString em vez disso. Para obter mais informações, consulte Recursos existentes de referência.
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 armazenar permanentemente os dados de 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 por que eles são preferenciais em vez de associar montagens, consulte Docker documentos: Volumes.
Aviso
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 recurso SQL Server com montagem de vinculação de dados
Para adicionar uma montagem de vinculaçã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 de dados associam montagens 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 de vínculo permitem acesso direto e modificação de arquivos no sistema host, ideal para desenvolvimento e teste quando são necessárias alterações em tempo real.
As montagens de associação de dados dependem do sistema de arquivos do computador host para persistir os dados SQL Server entre reinicializações de contêiner. A montagem de dados é feita no caminho C:\SqlServer\Data no Windows (ou /SqlServer/Data no Unix) no computador host dentro do contêiner SQL Server. Para obter mais informações sobre montagens de ligação de dados, consulte a documentação Docker: Montagens de ligação.
Adicionar SQL Server recurso com parâmetros
Quando quiser fornecer explicitamente a senha usada pela imagem de contêiner, você pode 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 aos recursos do banco de dados
Quando o host do aplicativo .NET Aspire é executado, os recursos de banco de dados do serverpodem ser acessados 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 dos recursos dependentes e pode ser acessada usando o painel .NET.NET Aspire: painel Detalhes do Recurso. A variável de ambiente é nomeada ConnectionStrings__{name} em que {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ê tenha um banco de dados chamado todos com uma única tabela de dbo.Todos.
-
do
Management Studio - Azure Data Studio
Para se conectar ao recurso de banco de dados do SQL Server Management Studio, siga estas etapas:
Abra o SSMS.
Na caixa de diálogo Conectar ao Server, selecione a guia Parâmetros de Conexão Adicionais.
Cole a cadeia de conexão no campo Parâmetros de Conexão Adicionais e selecione Conectar.
Se estiver conectado, você poderá ver o recurso de banco de dados nodo Pesquisador de Objetos do
: 
Para obter mais informações, consulte SQL Server Management Studio: Conectar-se a um server.
Verificações de integridade de integração de hospedagem
A integração de hospedagem SQL Server adiciona automaticamente uma verificação de integridade para o recurso de 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 NuGet 📦 AspNetCore.HealthChecks.SqlServer.
integração Client
Para começar a usar a integração .NET AspireSQL Serverclient, instale o 📦Aspire. Microsoft.Data.SqlClient pacote NuGet no projeto que consome client, ou seja, o projeto para o aplicativo que usa o SQL Serverclient. A integração SQL Serverclient registra uma instância de SqlConnection que você pode usar para interagir com SQL Server.
- .NET CLI
-
PackageReference
dotnet add package Aspire.Microsoft.Data.SqlClient
Adicionar SQL Serverclient
No arquivo Program.cs do seu projeto que consome client, chame o método de extensão AddSqlServerClient em qualquer IHostApplicationBuilder para registrar um SqlConnection para uso por meio do contêiner 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 de 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 adicionar o recurso SQL Server e o recurso de banco de dados.
Em seguida, você pode usar a injeção de dependência para recuperar a instância de SqlConnection. 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 injeção de dependência, consulte .NET injeção de dependência.
Adicionar SQL Serverclient com chave
Pode haver situações em que você deseja registrar várias instâncias de SqlConnection com nomes de conexão diferentes. Para registrar clientes chaveados de SQL Server, 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 de 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 de SqlConnection usando 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 conexão
Ao usar uma cadeia de conexão da seção de configuração 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 a ConnectionString .
Usar provedores de configuração
A integração .NET AspireSQL Server dá suporte a Microsoft.Extensions.Configuration. Ele carrega a MicrosoftDataSqlClientSettings da configuração usando a chave Aspire:Microsoft:Data:SqlClient. O snippet 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 o esquema de integração SQL ServerclientJSON completo, consulte Aspire. Microsoft.Data.SqlClient/ConfigurationSchema.json.
Usar delegados embutidos
Além disso, você pode passar o delegado Action<MicrosoftDataSqlClientSettings> configureSettings para configurar algumas ou todas as opções embutidas, por exemplo, para desabilitar verificações de integridade do código:
builder.AddSqlServerClient(
"database",
static settings => settings.DisableHealthChecks = true);
Client verificações de integridade 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 de 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 ao endpoint HTTP
/health, que especifica que todas as verificações de saúde registradas devem ser aprovadas para que o aplicativo seja considerado pronto para aceitar tráfego.
Observabilidade e telemetria
.NET .NET Aspire integrações configuram automaticamente configurações de Log, Rastreamento e Métricas, que às vezes são conhecidas como os pilares da observabilidade. Para obter mais informações sobre a observabilidade e a telemetria de integração, consulte .NET.NET Aspire visão geral das integrações. Dependendo do serviço de backup, algumas integrações só podem dar suporte a alguns desses recursos. Por exemplo, algumas integrações dão suporte a registro em log e rastreamento, mas não a métricas. Os recursos de telemetria também podem ser desabilitados usando as técnicas apresentadas na seção Configuration.
Registro de Logs
A integração .NET AspireSQL Server atualmente não habilita o registro em log por padrão devido a limitações do Microsoft.Data.SqlClient.
Rastreamento
A integração .NET AspireSQL Server emite as seguintes atividades de rastreamento usando 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-connectionshard-connectshard-disconnectsactive-soft-connectssoft-connectssoft-disconnectsnumber-of-non-pooled-connectionsnumber-of-pooled-connectionsnumber-of-active-connection-pool-groupsnumber-of-inactive-connection-pool-groupsnumber-of-active-connection-poolsnumber-of-inactive-connection-poolsnumber-of-active-connectionsnumber-of-free-connectionsnumber-of-stasis-connectionsnumber-of-reclaimed-connections
