Хранение данных в базах данных, совместимых с SQL
Стек .NET Aspire предназначен для повышения производительности и создания надежных, масштабируемых и безопасных веб-приложений. Структурированные реляционные данные можно хранить быстро, добавив один из поддерживаемых компонентов Aspire.
Текущие компоненты базы данных, совместимые с SQL, являются следующими:
- Базы данных PostgreSQL
- Базы данных SQL
- Базы данных Oracle
- Базы данных MySQL
Заметка
Корпорация Майкрософт может добавить поддержку других систем баз данных и сторонних производителей, поэтому этот список может расшириться.
В этом уроке вы узнаете о трех этих компонентах, о том, какие базы данных поддерживают Entity Framework Core, а также о том, как использовать их для хранения и извлечения данных.
Добавление компонента базы данных в проект
Независимо от выбранной базы данных подход к добавлению компонента базы данных .NET Aspire в проект совпадает.
В проекте хоста приложения:
- Установите компонент хостинга .NET Aspire в проект хоста приложения.
- Зарегистрируйте базу данных и создайте для него контейнер в узле приложения решения.
- Передайте ссылку на проекты, которым требуется доступ к созданному контейнеру, в котором размещена база данных.
В проектах, использующих базу данных:
- Добавьте компонент .NET Aspire с пакетом NuGet в проекты, для которых требуется доступ к данным. При желании, если имеется компонент .NET Core Entity Framework (EF), его можно использовать.
- Зарегистрируйте источник данных или контекст базы данных для EF в файле Program.cs проекта.
- Используйте внедрение зависимостей, чтобы интегрировать источник данных в ваши службы.
Давайте рассмотрим особенности выполнения этих действий для каждой из поддерживаемых баз данных.
Использование компонентов .NET Aspire PostgreSQL
Для компонентов .NET Aspire PostgreSQL требуются изменения как в проекте узла приложения, так и в любых микрослужбах, использующих базы данных.
Настройка узла приложения
Начните с установки соответствующего компонента размещения на узле приложения:
dotnet add package Aspire.Hosting.PostgreSQL --prerelease
Затем, чтобы зарегистрировать базу данных и создать для него контейнер, добавьте этот код в файл Program.cs узла приложения:
var postgres = builder.AddPostgres("postgres");
var postgresdb = postgres.AddDatabase("postgresdb");
Кроме того, необходимо передать ссылку на службу базы данных любым проектам, которые его используют:
var northernTradersCatalogAPI = builder.AddProject<Projects.NorthernTraders_CatalogAPI>()
.WithReference(postgresdb);
Настройка проектов-потребителей
Чтобы установить компонент .NET Aspire PostgreSQL, используйте следующую команду в проектах .NET Aspire:
dotnet add package Aspire.Npgsql --prerelease
Кроме того, чтобы использовать компонент .NET Aspire PostgreSQL Entity Framework Core, используйте следующую команду:
dotnet add package Aspire.Npgsql.EntityFrameworkCore.PostgreSQL --prerelease
В качестве альтернативного метода, для установки компонента из диспетчера пакетов NuGet, можно использовать сочетание клавиш Add > .NET Aspire Component в Visual Studio:
Код в файле Program.cs проекта *.AppHost создает базу данных и передает ее в проекты, которые хотят использовать её.
var postgres = builder.AddPostgres("pg")
.AddDatabase("postgresdb");
var exampleProject = builder.AddProject<Projects.SampleProject>()
.WithReference(postgres);
Некоторые компоненты базы данных .NET Aspire также позволяют создавать контейнер для средств управления базами данных. Чтобы добавить PgAdmin в решение для управления базой данных PostgreSQL, используйте следующий код:
var postgresdb = builder.AddPostgres("pg")
.AddDatabase("postgresdb")
.WithPgAdmin();
Преимущество передачи создания контейнера программе .NET Aspire состоит в том, что вам не нужно выполнять какую-либо настройку для подключения PgAdmin к базе данных PostgreSQL — все происходит автоматически.
Использование базы данных PostgreSQL
В любом проекте, где вы хотите использовать базу данных, добавьте источник данных для представления подключения к PostgreSQL. В файле Program.cs этот код регистрирует базу данных:
builder.AddNpgsqlDataSource("postgresdb");
Чтобы использовать компонент Entity Framework Core, зарегистрируйте контекст базы данных:
builder.AddNpgsqlDbContext<YourDbContext>("postgresdb");
После регистрации базы данных в потребляемом проекте вы можете взаимодействовать с источником данных в любое время, используя внедрение зависимостей:
public class YourService(NpgsqlDataSource dataSource)
{
public async Task<IEnumerable<Catalog>> GetCatalog()
{
const string query = "SELECT * FROM catalog";
using var dbConnection = dataSource.OpenConnection();
var results = await dbConnection.QueryAsync<Catalog>(command);
return queryResult.ToArray();
}
}
Кроме того, можно получить контекст базы данных YourDbContext для взаимодействия с базой данных:
public class YourService(YourDbContext context)
{
public async Task<IEnumerable<Catalog>> GetCatalog()
{
var items = await context.ObjectItems;
if (item is null)
{
return Results.NotFound();
}
else
{
return items;
}
}
}
Настройка компонента PostgreSQL
Стек .NET Aspire пытается уменьшить количество настроек, которые необходимо выполнить. С помощью внедрения зависимостей и обнаружения служб вы можете получить доступ к базе данных без необходимости настраивать строки подключения в проектах.
Использование проекта узла приложения для создания контейнера базы данных и передачи его в качестве ссылки на проекты позволяет получающим проектам получать доступ к расположению базы данных, строкам подключения и портам. Нет необходимости управлять переменными среды или appsettings.json файлами.
Но если вы хотите, или вам потребуется больше контроля над настройкой базы данных, есть дополнительные параметры.
Использование строки подключения
В проекте, который требует базы данных, используется строка подключения для подключения к базе данных. Этот подход полезен, если необходимо подключиться к базе данных, которая не зарегистрирована в узле приложения.
builder.AddNpgsqlDataSource("NpgsqlConnectionString");
Затем в файле конфигурации можно добавить строку подключения:
{
"ConnectionStrings": {
"NpgsqlConnectionString": "Host=myserver;Database=postgresdb;User id=myuser;Password=mypassword"
}
}
Использование поставщиков конфигураций
.NET Aspire имеет набор функций компонентов, которые позволяют им поддерживать Microsoft.Extensions.Configuration. Компонент PostgreSQL поддерживает эту функцию и по умолчанию ищет параметры с помощью ключа Aspire:Npgsql. В проектах с помощью appsettings.jsonпример конфигурации может выглядеть следующим образом:
{
"Aspire": {
"Npgsql": {
"ConnectionString": "Host=myserver;Database=postgresdb;User id=myuser;Password=mypassword",
"HealthChecks": true,
"Tracing": true,
"Metrics": true
}
}
}
Предыдущая конфигурация задает строку подключения и включает проверки работоспособности, трассировку и метрики для компонента PostgreSQL. Затем код больше не должен указывать строку подключения, просто используйте builder.AddNpgsqlDataSource();.
Если вы используете компонент Entity Framework Core PostgreSQL, можно использовать ключ Aspire:Npgsql:EntityFrameworkCore:PostgreSQL для настройки контекста базы данных:
{
"Aspire": {
"Npgsql": {
"EntityFrameworkCore": {
"PostgreSQL": {
"ConnectionString": "Host=myserver;Database=postgresdb;User id=myuser;Password=mypassword",
"MaxRetryCount": 0,
"HealthChecks": false,
"Tracing": false
}
}
}
}
}
Дополнительные сведения о параметрах конфигурации Entity Framework см. в документации .NET Aspire.
Использование встроенных делегатов
Последним вариантом является передача встроенного делегата configureSettings методу AddNpgsqlDataSource. Этот делегат позволяет настроить параметры компонента базы данных непосредственно с помощью кода:
builder.AddNpgsqlDataSource(
"postgresdb", static settings => settings.HealthChecks = false);
Использование компонентов базы данных SQL для .NET Aspire
Предыдущий шаблон совпадает с компонентом базы данных SQL. Изменения вносятся как в проект узла приложения, так и в микрослужбы, использующие службу базы данных.
Настройка узла приложения
Чтобы установить компонент размещения базы данных SQL, используйте следующую команду:
dotnet add package Aspire.Hosting.SqlServer --prerelease
Чтобы зарегистрировать контейнер и базу данных, добавьте этот код в Program.cs файл узла приложения:
var sql = builder.AddSqlServer("sql");
var sqldb = sql.AddDatabase("sqldb");
Затем передайте ссылку на службу базы данных любым проектам, которые его используют:
var northernTradersCatalogAPI = builder.AddProject<Projects.NorthernTraders_CatalogAPI>()
.WithReference(sqldb);
Настройка потребляющих проектов
Чтобы установить компонент базы данных SQL .NET Aspire, используйте команду, например в проектах .NET Aspire:
dotnet add package Aspire.Microsoft.Data.SqlClient --prerelease
Кроме того, чтобы использовать компонент .NET Aspire SqlServer Entity Framework Core, используйте следующую команду:
dotnet add package Aspire.Microsoft.EntityFrameworkCore.SqlServer --prerelease
Эти пакеты NuGet также можно добавить с помощью сочетания клавиш add > .NET Aspire Component в Visual Studio.
Код файла Program.cs проекта *.AppHost для доступа к базе данных аналогичен примеру PostgreSQL.
var sqlServer = builder.AddSqlServer("sql")
.AddDatabase("sqldata");
var myService = builder.AddProject<Projects.MyService>()
.WithReference(sqlServer);
Использование базы данных SQL Server
В проектах, которым требуется доступ к SQL, в файле Program.cs этот код регистрирует контекст базы данных Entity Framework:
builder.AddSqlServerDbContext<YourDbContext>("sqldata");
После регистрации базы данных в потребляемом проекте можно взаимодействовать с контекстом базы данных YourDbContext с помощью внедрения зависимостей. Этот пример кода извлекает прогнозы погоды из базы данных и выбирает один случайным образом для возврата:
app.MapGet("/weatherforecast", async (YourDbContext context) =>
{
var rng = new Random();
var forecasts = await context.Forecasts.ToListAsync();
var forecast = forecasts[rng.Next(forecasts.Count)];
return forecast;
});
Настройка компонента SQL Server
Как и раньше, если вы используете то же имя базы данных в узле приложения и потребляемом проекте, вам не нужно настраивать подключение между базой данных SQL Server и проектами. Компонент .NET Aspire SQL Server также поддерживает другие способы настройки компонента.
Использование поставщиков конфигураций
Компонент SQL Server также поддерживает Microsoft.Extensions.Configuration. По умолчанию он ищет параметры с помощью ключа Aspire:SqlServer:SqlClient. В проектах с помощью appsettings.jsonпример конфигурации может выглядеть следующим образом:
{
"Aspire": {
"SqlServer": {
"SqlClient": {
"ConnectionString": "YOUR_CONNECTIONSTRING",
"HealthChecks": true,
"Tracing": false,
"Metrics": false
}
}
}
}
Использование встроенных конфигураций
При добавлении компонента SQL Server можно передать встроенный делегат configureSettings в метод AddSqlServerClient. Этот делегат позволяет настроить параметры компонента базы данных непосредственно с помощью кода:
builder.AddSqlServerClient("sqldata", static settings => settings.HealthChecks = false);
Вы можете передать любой из поддерживаемых вариантов:
-
ConnectionString: строка подключения базы данных SQL Server -
HealthChecks: логическое значение, указывающее, включена ли проверка работоспособности базы данных. -
Tracing: логическое значение, указывающее, включена ли трассировка OpenTelemetry -
Metrics: логическое значение, указывающее, включены ли метрики OpenTelemetry
Подключение к нескольким базам данных
Компонент SQL Server поддерживает несколько подключений через именованные экземпляры. Например, можно подключиться к двум разным базам данных SQL Server в одном проекте:
{
"Aspire": {
"SqlServer": {
"SqlClient": {
"INSTANCE_1": {
"ServiceUri": "YOUR_URI",
"HealthChecks": false
},
"INSTANCE_2": {
"ServiceUri": "YOUR_URI",
"HealthChecks": false
}
}
}
}
}
С помощью этой конфигурации можно подключиться к двум разным базам данных в одном проекте:
builder.AddSqlServerClient("INSTANCE_1");
builder.AddSqlServerClient("INSTANCE_2");
Использование компонента MySQL
Чтобы установить компонент .NET Aspire MySQL, используйте следующую команду в проектах .NET Aspire, для которых требуется доступ к данным:
dotnet add package Aspire.MySqlConnector --prerelease
Или используйте сочетание клавиш Add > .NET Aspire Component в Visual Studio, чтобы установить компонент из диспетчера пакетов NuGet.
*. Код файла Program.cs проекта AppHost для доступа к базе данных аналогичен примеру PostgreSQL:
var mysqldb = builder.AddMySql("mysql")
.AddDatabase("mysqldb")
.WithPhpMyAdmin();
var myService = builder.AddProject<Projects.MyService>()
.WithReference(mysqldb);
Как и компонент PostgreSQL, компонент MySQL также позволяет создать контейнер для средств управления базами данных. В предыдущем примере в решение добавляется PhpMyAdmin.
Использование базы данных MySQL
Шаблон тот же в проектах, которым нужен доступ к MySQL. В файле Program.cs этот код регистрирует базу данных:
builder.AddMySqlDataSource("mysqldb");
После регистрации базы данных в потребляемом проекте вы можете взаимодействовать с источником данных в любое время, используя внедрение зависимостей:
app.MapGet("/catalog", async (MySqlConnection db) =>
{
const string sql = """
SELECT Id, Name, Description, Price
FROM catalog
""";
// the db object is a connection to the MySQL database registered with AddMySqlDataSource
return await db.QueryAsync<CatalogItem>(sql);
});
Настройка компонента MySQL
Компонент MySQL поддерживает те же три варианта управления конфигурацией.
Строки подключения
Файл appsettings.json может содержать строку подключения для базы данных MySQL:
{
"ConnectionStrings": {
"MySqConnection": "Server=myserver;Database=mysqldb;Uid=myuser;Pwd=mypassword"
}
}
Затем в проекте можно подключиться к базе данных со строкой подключения, используя следующий код:
builder.AddMySqlDataSource("MySqConnection");
Поставщики конфигураций
Ключ Aspire:MySqlConnector используется для настройки компонента MySQL.
{
"Aspire": {
"MySqlConnector": {
"ConnectionString": "Server=myserver;Database=mysqldb;Uid=myuser;Pwd=mypassword",
"HealthChecks": true,
"Tracing": false,
"Metrics": false
}
}
}
Встроенные конфигурации
builder.AddMySqlDataSource("mysqldb", static settings => settings.HealthChecks = false);
Узнайте, как заполнить базу данных
Стек .NET Aspire использует контейнеры, получая преимущества согласованных сред и простых развертываний. Недостатком является то, что контейнеры не имеют состояния. Все данные или схемы, добавленные в базу данных, теряются при уничтожении контейнера. .NET Aspire предоставляет способы заполнения баз данных данными при создании контейнеров.
Использование томов и скриптов
Самый простой способ заполнить базу данных — использовать тома и скрипты SQL. Тома могут хранить данные для нескольких контейнеров одновременно, обеспечивать высокую производительность, а также их легко архивировать или переносить. Скрипты, хранящиеся в этих томах, выполняются при создании контейнера, заполняя базу данных данными. Скрипт может быть SQL-файлом, который содержит данные и схему, которые требуется для базы данных.
Например, если у вас был этот скрипт SQL, хранящийся в файле с именем postgres-backup.sql, в папке Service.API/Seed:
CREATE TABLE catalog (
Id INT PRIMARY KEY,
Name VARCHAR(50),
Description VARCHAR(255),
Price DECIMAL(18, 2)
);
INSERT INTO catalog (Id, Name, Description, Price)
VALUES (1, 'Item 1', 'Description of item 1', 10.99),
(2, 'Item 2', 'Description of item 2', 20.99),
(3, 'Item 3', 'Description of item 3', 30.99);
В узле приложения решения можно привязать папку Service.API/Seed к папке контейнера /docker-entrypoint-initdb.d. Эта папка является специальной папкой в контейнере PostgreSQL, который запускает все скрипты SQL, которые он находит при создании контейнера:
var catalogDB = builder.AddPostgres("postgres")
.WithPgAdmin()
.WithEnvironment("POSTGRES_DB", "backendDB")
.WithBindMount("../Service.API/Seed", "/docker-entrypoint-initdb.d")
.AddDatabase("backendDB");
Вы даже можете разделить скрипты SQL на создание схемы и скрипты заполнения данных. Если все они содержатся в папке Service.API/Seed, они выполняются при создании базы данных .NET Aspire.
Заполнение базы данных данными с использованием Entity Framework Core
Для компонентов, поддерживающих Entity Framework Core, базу данных можно заполнить с помощью класса DbContext и механизма миграций Entity Framework Core. Этот метод использует код C# для заполнения базы данных. Однако эта инициализация должна производиться только во время разработки или тестирования, а не в продакшене.
// Register DbContext class
builder.AddNpgsqlDbContext<CatalogContext>("sqldata");
var app = builder.Build();
app.MapDefaultEndpoints();
if (app.Environment.IsDevelopment())
{
// Retrieve an instance of the DbContext class and manually run migrations during development
using (var scope = app.Services.CreateScope())
{
var context = scope.ServiceProvider.GetRequiredService<CatalogContext>();
context.Database.EnsureCreated();
}
}
Приведенный выше код проверяет состояние среды приложения. Если он находится в разработке, код извлекает класс CatalogContext и запускает метод EnsureCreated. Этот метод создает базу данных и выполняет все ожидающие миграции.
Дополнительные сведения о заполнении различных компонентов базы данных можно найти в документации по .NET Aspire .