Przechowywanie danych w bazach danych zgodnych z programem SQL
Stos Aspirujący platformy .NET został zaprojektowany w celu zwiększenia produktywności i ułatwienia tworzenia niezawodnych, skalowalnych i bezpiecznych aplikacji internetowych. Możesz szybko przechowywać ustrukturyzowane dane relacyjne, dodając jeden z obsługiwanych składników Aspire.
Bieżące składniki bazy danych zgodne z programem SQL to:
- Bazy danych PostgreSQL
- Bazy danych SQL
- Bazy danych Oracle
- Bazy danych MySQL
Uwaga
Firma Microsoft może dodać obsługę innych systemów baz danych i innych firm może również współtworzyć tę listę, więc ta lista może zostać rozwinięta.
W tej lekcji poznasz trzy z tych składników, które bazy danych obsługują platformę Entity Framework Core i jak ich używać do przechowywania i pobierania danych.
Jak dodać składnik bazy danych do projektu
Niezależnie od wybranej bazy danych podejście do dodania składnika bazy danych .NET Aspire do projektu jest takie samo.
W projekcie hosta aplikacji:
- Zainstaluj składnik hostingu .NET Aspire w projekcie hosta aplikacji.
- Zarejestruj bazę danych i utwórz dla niej kontener na hoście aplikacji rozwiązania.
- Przekaż odwołanie do projektów, które wymagają dostępu do utworzonego kontenera hostujące bazę danych.
W projektach korzystających z bazy danych:
- Dodaj składnik .NET Aspire z pakietem NuGet do projektów, które wymagają dostępu do danych. Opcjonalnie, jeśli istnieje składnik programu .NET Core Entity Framework (EF), możesz go użyć.
- Zarejestruj źródło danych lub kontekst bazy danych dla programu EF w pliku Program.cs projektu.
- Użyj wstrzykiwania zależności, aby wstrzyknąć źródło danych do usług.
Przyjrzyjmy się konkretnym sposobom wykonywania tych kroków dla każdej z obsługiwanych baz danych.
Korzystanie ze składników programu .NET Aspire PostgreSQL
Składniki programu .NET Aspire PostgreSQL wymagają zmian zarówno w projekcie hosta aplikacji, jak i wszelkich mikrousług korzystających z baz danych.
Konfigurowanie hosta aplikacji
Rozpocznij od zainstalowania odpowiedniego składnika hostingu na hoście aplikacji:
dotnet add package Aspire.Hosting.PostgreSQL --prerelease
Następnie, aby zarejestrować bazę danych i utworzyć dla niej kontener, dodaj ten kod do pliku Program.cs hosta aplikacji:
var postgres = builder.AddPostgres("postgres");
var postgresdb = postgres.AddDatabase("postgresdb");
Należy również przekazać odwołanie do usługi bazy danych do wszystkich projektów, które go używają:
var northernTradersCatalogAPI = builder.AddProject<Projects.NorthernTraders_CatalogAPI>()
.WithReference(postgresdb);
Konfigurowanie projektów zużywających
Aby zainstalować składnik .NET Aspire PostgreSQL, użyj polecenia takiego jak ten w projektach platformy .NET Aspire:
dotnet add package Aspire.Npgsql --prerelease
Możesz też użyć składnika .NET Aspire PostgreSQL Entity Framework Core, zamiast tego użyj następującego polecenia:
dotnet add package Aspire.Npgsql.EntityFrameworkCore.PostgreSQL --prerelease
Alternatywnie możesz użyć skrótu Dodaj > składnik aspirujący platformy .NET w programie Visual Studio, aby zainstalować składnik z menedżera pakietów NuGet:
Kod w *. Plik Program.cs projektu AppHost tworzy bazę danych i przekazuje ją do projektów, które chcą go używać:
var postgres = builder.AddPostgres("pg")
.AddDatabase("postgresdb");
var exampleProject = builder.AddProject<Projects.SampleProject>()
.WithReference(postgres);
Niektóre składniki bazy danych .NET Aspire umożliwiają również utworzenie kontenera dla narzędzi do zarządzania bazami danych. Aby dodać narzędzie PgAdmin do rozwiązania do zarządzania bazą danych PostgreSQL, użyj następującego kodu:
var postgresdb = builder.AddPostgres("pg")
.AddDatabase("postgresdb")
.WithPgAdmin();
Zaletą umożliwienia platformy .NET Aspire utworzenia kontenera jest to, że nie trzeba wykonywać żadnej konfiguracji, aby połączyć narzędzie PgAdmin z bazą danych PostgreSQL, to wszystko jest automatyczne.
Korzystanie z bazy danych PostgreSQL
W każdym projekcie, w którym chcesz używać bazy danych, należy dodać źródło danych do reprezentowania połączenia z bazą danych PostgreSQL. W pliku Program.cs ten kod rejestruje bazę danych:
builder.AddNpgsqlDataSource("postgresdb");
Lub aby użyć składnika Entity Framework Core, zarejestruj kontekst bazy danych:
builder.AddNpgsqlDbContext<YourDbContext>("postgresdb");
Po zarejestrowaniu bazy danych w projekcie korzystającym z niego możesz wchodzić w interakcje ze źródłem danych w dowolnym momencie, używając iniekcji zależności:
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();
}
}
Możesz też pobrać kontekst YourDbContext bazy danych w celu interakcji z bazą danych:
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;
}
}
}
Konfigurowanie składnika PostgreSQL
Stos .NET Aspire próbuje zmniejszyć ilość konfiguracji, którą należy wykonać. Korzystając z iniekcji zależności i odnajdywania usług, można uzyskać dostęp do bazy danych bez konieczności konfigurowania parametry połączenia w projektach.
Użycie projektu hosta aplikacji do utworzenia kontenera bazy danych i przekazania go jako odwołania do projektów umożliwia odbieranie projektów uzyskiwanie dostępu do lokalizacji bazy danych, parametry połączenia i portów. Nie trzeba zarządzać zmiennymi środowiskowymi ani plikami appsettings.json .
Jeśli jednak chcesz, potrzebujesz większej kontroli nad konfiguracją bazy danych, istnieje więcej opcji.
Używanie parametry połączenia
W projekcie, który wymaga bazy danych, należy użyć parametry połączenia do nawiązania połączenia z bazą danych. Takie podejście jest przydatne, gdy musisz nawiązać połączenie z bazą danych, która nie jest zarejestrowana na hoście aplikacji.
builder.AddNpgsqlDataSource("NpgsqlConnectionString");
Następnie w pliku konfiguracji możesz dodać parametry połączenia:
{
"ConnectionStrings": {
"NpgsqlConnectionString": "Host=myserver;Database=postgresdb;User id=myuser;Password=mypassword"
}
}
Korzystanie z dostawców konfiguracji
Platforma .NET Aspire ma funkcję składników, które pozwalają im obsługiwać element Microsoft.Extensions.Configuration. Składnik PostgreSQL obsługuje tę funkcję i domyślnie wyszukuje ustawienia przy użyciu Aspire:Npgsql klucza. W projektach korzystających z appsettings.json przykładowa konfiguracja może wyglądać następująco:
{
"Aspire": {
"Npgsql": {
"ConnectionString": "Host=myserver;Database=postgresdb;User id=myuser;Password=mypassword",
"HealthChecks": true,
"Tracing": true,
"Metrics": true
}
}
}
Poprzednia konfiguracja ustawia parametry połączenia, włączając kontrole kondycji, śledzenie i metryki dla składnika PostgreSQL. Następnie kod nie musi już określać parametry połączenia, wystarczy użyć polecenia builder.AddNpgsqlDataSource();.
Jeśli używasz składnika Entity Framework Core bazy danych PostgreSQL, możesz użyć Aspire:Npgsql:EntityFrameworkCore:PostgreSQL klucza do skonfigurowania kontekstu bazy danych:
{
"Aspire": {
"Npgsql": {
"EntityFrameworkCore": {
"PostgreSQL": {
"ConnectionString": "Host=myserver;Database=postgresdb;User id=myuser;Password=mypassword",
"MaxRetryCount": 0,
"HealthChecks": false,
"Tracing": false
}
}
}
}
}
Aby uzyskać więcej informacji na temat opcji konfiguracji programu Entity Framework, zobacz dokumentację platformy .NET Aspire.
Używanie delegatów wbudowanych
Ostatnia opcja polega na przekazaniu delegata wbudowanego configureSettings AddNpgsqlDataSource do metody . Ten delegat umożliwia skonfigurowanie ustawień składnika bazy danych bezpośrednio przy użyciu kodu:
builder.AddNpgsqlDataSource(
"postgresdb", static settings => settings.HealthChecks = false);
Korzystanie ze składników programu .NET Aspire SQL Database
Poprzedni wzorzec jest taki sam dla składnika usługi SQL Database. Zmiany są wprowadzane zarówno w projekcie hosta aplikacji, jak i w mikrousługach korzystających z usługi bazy danych.
Konfigurowanie hosta aplikacji
Aby zainstalować składnik hostingu bazy danych SQL, użyj następującego polecenia:
dotnet add package Aspire.Hosting.SqlServer --prerelease
Aby zarejestrować kontener i bazę danych, dodaj ten kod do pliku Program.cs hosta aplikacji:
var sql = builder.AddSqlServer("sql");
var sqldb = sql.AddDatabase("sqldb");
Następnie przekaż odwołanie do usługi bazy danych do wszystkich projektów, które go używają:
var northernTradersCatalogAPI = builder.AddProject<Projects.NorthernTraders_CatalogAPI>()
.WithReference(sqldb);
Konfigurowanie projektów zużywających
Aby zainstalować składnik .NET Aspire SQL Database, użyj polecenia takiego jak ten w projektach programu .NET Aspire:
dotnet add package Aspire.Microsoft.Data.SqlClient --prerelease
Możesz też użyć składnika .NET Aspire SqlServer Entity Framework Core, zamiast tego użyj następującego polecenia:
dotnet add package Aspire.Microsoft.EntityFrameworkCore.SqlServer --prerelease
Te pakiety NuGet można również dodać przy użyciu skrótu Dodaj > składnik Aspirujący platformy .NET w programie Visual Studio.
*. Kod pliku Program.cs projektu AppHost w celu uzyskania dostępu do bazy danych jest podobny do przykładu bazy danych PostgreSQL:
var sqlServer = builder.AddSqlServer("sql")
.AddDatabase("sqldata");
var myService = builder.AddProject<Projects.MyService>()
.WithReference(sqlServer);
Korzystanie z bazy danych programu SQL Server
W projektach wymagających dostępu SQL w pliku Program.cs ten kod rejestruje kontekst bazy danych programu Entity Framework:
builder.AddSqlServerDbContext<YourDbContext>("sqldata");
Po zarejestrowaniu bazy danych w projekcie zużywających można wchodzić w interakcje z kontekstem YourDbContext bazy danych przy użyciu wstrzykiwania zależności. Ten przykładowy kod pobiera prognozy pogody z bazy danych i wybiera jeden losowo, aby zwrócić:
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;
});
Konfigurowanie składnika programu SQL Server
Tak jak wcześniej, jeśli używasz tej samej nazwy bazy danych na hoście aplikacji i projekcie korzystającym, nie musisz konfigurować połączenia między bazą danych programu SQL Server i projektami. Składnik .NET Aspire SQL Server obsługuje również inne sposoby konfigurowania składnika.
Korzystanie z dostawców konfiguracji
Składnik programu SQL Server obsługuje również program Microsoft.Extensions.Configuration. Domyślnie wyszukuje ustawienia przy użyciu Aspire:SqlServer:SqlClient klucza. W projektach korzystających z appsettings.json przykładowa konfiguracja może wyglądać następująco:
{
"Aspire": {
"SqlServer": {
"SqlClient": {
"ConnectionString": "YOUR_CONNECTIONSTRING",
"HealthChecks": true,
"Tracing": false,
"Metrics": false
}
}
}
}
Korzystanie z wbudowanych konfiguracji
Po dodaniu składnika programu SQL Server można przekazać delegata wbudowanego configureSettings AddSqlServerClient do metody . Ten delegat umożliwia skonfigurowanie ustawień składnika bazy danych bezpośrednio przy użyciu kodu:
builder.AddSqlServerClient("sqldata", static settings => settings.HealthChecks = false);
Możesz przekazać dowolną z obsługiwanych opcji:
ConnectionString: parametry połączenia bazy danych programu SQL ServerHealthChecks: wartość logiczna wskazująca, czy sprawdzanie kondycji bazy danych jest włączoneTracing: wartość logiczna wskazująca, czy śledzenie OpenTelemetry jest włączoneMetrics: wartość logiczna wskazująca, czy są włączone metryki OpenTelemetry
Nawiązywanie połączenia z wieloma bazami danych
Składnik programu SQL Server obsługuje wiele połączeń za pośrednictwem nazwanych wystąpień. Na przykład możesz nawiązać połączenie z dwiema różnymi bazami danych programu SQL Server w tym samym projekcie:
{
"Aspire": {
"SqlServer": {
"SqlClient": {
"INSTANCE_1": {
"ServiceUri": "YOUR_URI",
"HealthChecks": false
},
"INSTANCE_2": {
"ServiceUri": "YOUR_URI",
"HealthChecks": false
}
}
}
}
}
Korzystając z tej konfiguracji, możesz nawiązać połączenie z dwoma różnymi bazami danych w tym samym projekcie:
builder.AddSqlServerClient("INSTANCE_1");
builder.AddSqlServerClient("INSTANCE_2");
Korzystanie ze składnika MySQL
Aby zainstalować składnik .NET Aspire MySQL, użyj polecenia takiego jak ten w projektach platformy .NET Aspire, które wymagają dostępu do danych:
dotnet add package Aspire.MySqlConnector --prerelease
Możesz też użyć skrótu Dodaj > składnik Aspirujący platformy .NET w programie Visual Studio, aby zainstalować składnik z menedżera pakietów NuGet.
*. Kod pliku Program.cs projektu AppHost w celu uzyskania dostępu do bazy danych jest podobny do przykładu bazy danych PostgreSQL:
var mysqldb = builder.AddMySql("mysql")
.AddDatabase("mysqldb")
.WithPhpMyAdmin();
var myService = builder.AddProject<Projects.MyService>()
.WithReference(mysqldb);
Podobnie jak składnik PostgreSQL, składnik MySQL umożliwia również utworzenie kontenera dla narzędzi do zarządzania bazami danych. W poprzednim przykładzie dodano element PhpMyAdmin do rozwiązania.
Korzystanie z bazy danych MySQL
Wzorzec jest taki sam w projektach, które wymagają dostępu do bazy danych MySQL. W pliku Program.cs ten kod rejestruje bazę danych:
builder.AddMySqlDataSource("mysqldb");
Po zarejestrowaniu bazy danych w projekcie korzystającym z niego możesz wchodzić w interakcje ze źródłem danych w dowolnym momencie, używając iniekcji zależności:
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);
});
Konfigurowanie składnika MySQL
Składnik MySQL obsługuje te same trzy opcje zarządzania konfiguracją.
Parametry połączeń
Plik appsettings.json może zawierać parametry połączenia dla bazy danych MySQL:
{
"ConnectionStrings": {
"MySqConnection": "Server=myserver;Database=mysqldb;Uid=myuser;Pwd=mypassword"
}
}
Następnie w projekcie możesz nawiązać połączenie z bazą danych przy użyciu parametry połączenia przy użyciu kodu w następujący sposób:
builder.AddMySqlDataSource("MySqConnection");
Dostawcy konfiguracji
Klucz Aspire:MySqlConnector służy do konfigurowania składnika MySQL.
{
"Aspire": {
"MySqlConnector": {
"ConnectionString": "Server=myserver;Database=mysqldb;Uid=myuser;Pwd=mypassword",
"HealthChecks": true,
"Tracing": false,
"Metrics": false
}
}
}
Konfiguracje wbudowane
builder.AddMySqlDataSource("mysqldb", static settings => settings.HealthChecks = false);
Dowiedz się, jak rozmieszczać bazę danych
Stos .NET Aspire korzysta z kontenerów, uzyskując zalety spójnych środowisk i łatwych wdrożeń. Wadą jest to, że kontenery są bezstanowe. Wszystkie dane lub schematy dodane do bazy danych zostaną utracone, gdy kontener zostanie zniszczony. Platforma .NET Aspire udostępnia sposoby rozmieszczania baz danych przy użyciu danych podczas tworzenia ich kontenerów.
Używanie woluminów i skryptów
Najprostszym sposobem rozmieszczania bazy danych jest użycie woluminów i skryptów SQL. Woluminy mogą przechowywać dane dla wielu kontenerów naraz, oferować wysoką wydajność i łatwo tworzyć kopie zapasowe lub migrować. Skrypty przechowywane w tych woluminach są uruchamiane po utworzeniu kontenera, wypełniając bazę danych danymi. Skrypt może być plikiem SQL zawierającym dane i schemat bazy danych.
Jeśli na przykład ten skrypt SQL został zapisany w pliku o nazwie postgres-backup.sql, w folderze 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);
Na hoście aplikacji rozwiązania można powiązać folder Service.API/Seed z folderem /docker-entrypoint-initdb.d kontenera. Ten folder jest specjalnym folderem w kontenerze PostgreSQL, który uruchamia wszystkie skrypty SQL znalezione podczas tworzenia kontenera:
var catalogDB = builder.AddPostgres("postgres")
.WithPgAdmin()
.WithEnvironment("POSTGRES_DB", "backendDB")
.WithBindMount("../Service.API/Seed", "/docker-entrypoint-initdb.d")
.AddDatabase("backendDB");
Można nawet podzielić skrypty SQL na tworzenie schematu i skrypty rozmieszczania danych. Jeśli wszystkie znajdują się w folderze Service.API/Seed , są one wykonywane, gdy platforma .NET Aspire tworzy bazę danych.
Rozmieszczanie danych przy użyciu platformy Entity Framework Core
W przypadku składników, które obsługują platformę Entity Framework Core, możesz zainicjować bazę danych przy użyciu DbContext klas i migracji rdzeni platformy Entity Framework. Ta metoda używa kodu języka C# do rozmieszczania bazy danych. Jednak to rozmieszczanie powinno nastąpić tylko podczas opracowywania lub testowania, a nie w środowisku produkcyjnym.
// 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();
}
}
Powyższy kod sprawdza stan środowiska aplikacji. Jeśli jest on w programowania, kod pobiera klasę CatalogContext i uruchamia metodę EnsureCreated . Ta metoda tworzy bazę danych i uruchamia wszystkie oczekujące migracje.
Aby uzyskać więcej informacji na temat rozmieszczania różnych składników bazy danych, zobacz dokumentację platformy .NET Aspire.