Ukládání dat v databázích kompatibilních s SQL

15 min

Sada .NET Aspire je navržená tak, aby byla produktivnější a pomohla vám vytvářet robustní, škálovatelné a zabezpečené webové aplikace. Strukturovaná relační data můžete rychle uložit přidáním jedné z podporovaných komponent Aspire.

Aktuální databázové komponenty kompatibilní s SQL jsou:

Databáze PostgreSQL
Databáze SQL
Databáze Oracle
Databáze MySQL

Poznámka:

Microsoft může přidat podporu pro jiné databázové systémy a třetí strany mohou také přispívat, takže tento seznam se může rozšířit.

V této lekci se seznámíte se třemi z těchto komponent, které databáze mají podporu Entity Framework Core a jak je používat k ukládání a načítání dat.

Postup přidání databázové komponenty do projektu

Bez ohledu na to, kterou databázi zvolíte, je přístup k přidání databázové komponenty .NET Aspire do projektu stejný.

V projektu hostitele aplikace:

Nainstalujte komponentu hostování .NET Aspire do hostitelského projektu aplikace.
Zaregistrujte databázi a vytvořte pro ni kontejner v hostiteli aplikace řešení.
Předejte odkaz na projekty, které potřebují přístup k vytvořenému kontejneru hostujícímu databázi.

V projektech, které používají databázi:

Přidejte komponentu .NET Aspire s balíčkem NuGet do projektů, které vyžadují přístup k datům. Pokud existuje komponenta .NET Core Entity Framework (EF), můžete ji místo toho použít.
Zaregistrujte zdroj dat nebo kontext databáze ef v souboru Program.cs projektu.
Pomocí injektáže závislostí vložte zdroj dat do služeb.

Pojďme se podívat na konkrétní postupy pro každou z podporovaných databází.

Použití komponent .NET Aspire PostgreSQL

Komponenty .NET Aspire PostgreSQL vyžadují změny v projektu hostitele aplikace i všech mikroslužeb, které používají databáze.

Konfigurace hostitele aplikace

Začněte instalací příslušné hostitelské komponenty na hostitele aplikace:

dotnet add package Aspire.Hosting.PostgreSQL --prerelease

Pokud chcete databázi zaregistrovat a vytvořit pro ni kontejner, přidejte tento kód do souboru Program.cs hostitele aplikace:

var postgres = builder.AddPostgres("postgres");
var postgresdb = postgres.AddDatabase("postgresdb");

Do všech projektů, které ji využívají, musíte také předat odkaz na databázovou službu:

var northernTradersCatalogAPI = builder.AddProject<Projects.NorthernTraders_CatalogAPI>()
                                       .WithReference(postgresdb);

Konfigurace náročných projektů

Pokud chcete nainstalovat komponentu .NET Aspire PostgreSQL, použijte příkaz podobný tomuto v projektech .NET Aspire:

dotnet add package Aspire.Npgsql --prerelease

Nebo pokud chcete použít komponentu .NET Aspire PostgreSQL Entity Framework Core, použijte místo toho tento příkaz:

dotnet add package Aspire.Npgsql.EntityFrameworkCore.PostgreSQL --prerelease

Případně můžete pomocí zástupce Přidat > komponentu .NET Aspire v sadě Visual Studio nainstalovat komponentu ze správce balíčků NuGet:

Kód v *. Soubor Program.cs projektu AppHost vytvoří databázi a předá ji projektům, které ho chtějí použít:

var postgres = builder.AddPostgres("pg")
                      .AddDatabase("postgresdb");

var exampleProject = builder.AddProject<Projects.SampleProject>()
                            .WithReference(postgres);

Některé součásti databáze .NET Aspire také umožňují vytvořit kontejner pro nástroje pro správu databází. Pokud chcete ke správě databáze PostgreSQL přidat nástroj PgAdmin , použijte tento kód:

var postgresdb = builder.AddPostgres("pg")
                        .AddDatabase("postgresdb")
                        .WithPgAdmin();

Výhodou toho, že .NET Aspire vytvoří kontejner, je, že pro připojení nástroje PgAdmin k databázi PostgreSQL nemusíte provádět žádnou konfiguraci, je to všechno automatické.

Použití databáze PostgreSQL

V libovolném projektu, ve kterém chcete databázi používat, přidáte zdroj dat, který představuje připojení k PostgreSQL. V souboru Program.cs tento kód zaregistruje databázi:

builder.AddNpgsqlDataSource("postgresdb");

Nebo pokud chcete použít komponentu Entity Framework Core, zaregistrujte kontext databáze:

builder.AddNpgsqlDbContext<YourDbContext>("postgresdb");

Jakmile je databáze zaregistrovaná v náročném projektu, můžete s zdrojem dat pracovat, kdykoli ji potřebujete, pomocí injektáže závislostí:

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

Nebo můžete načíst kontext YourDbContext databáze pro interakci s databází:

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;
		}
	}
}

Konfigurace komponenty PostgreSQL

Zásobník .NET Aspire se pokusí snížit množství konfigurace, kterou potřebujete provést. Pomocí injektáže závislostí a zjišťování služeb můžete přistupovat k databázi, aniž byste museli konfigurovat připojovací řetězec ve svých projektech.

Pomocí hostitelského projektu aplikace vytvoříte kontejner databáze a předáte ho jako odkaz na projekty, umožní přijímajícím projektům přístup k umístění databáze, připojovací řetězec a portům. Není nutné spravovat proměnné prostředí ani appsettings.json soubory.

Pokud ale chcete, nebo potřebujete větší kontrolu nad konfigurací databáze, existují další možnosti.

Použití připojovací řetězec

V projektu, který vyžaduje databázi, použijete připojovací řetězec pro připojení k databázi. Tento přístup je užitečný, když se potřebujete připojit k databázi, která není zaregistrovaná v hostiteli aplikace.

builder.AddNpgsqlDataSource("NpgsqlConnectionString");

Potom do konfiguračního souboru můžete přidat připojovací řetězec:

{
  "ConnectionStrings": {
    "NpgsqlConnectionString": "Host=myserver;Database=postgresdb;User id=myuser;Password=mypassword"
  }
}

Použití zprostředkovatelů konfigurace

.NET Aspire má funkci komponent, které jim umožňují podporovat Microsoft.Extensions.Configuration. Komponenta PostgreSQL tuto funkci podporuje a ve výchozím nastavení hledá nastavení pomocí Aspire:Npgsql klíče. V projektech používajících appsettings.json může ukázková konfigurace vypadat takto:

{
  "Aspire": {
    "Npgsql": {
      "ConnectionString": "Host=myserver;Database=postgresdb;User id=myuser;Password=mypassword",
      "HealthChecks": true,
      "Tracing": true,
      "Metrics": true
    }
  }
}

Předchozí konfigurace nastavuje připojovací řetězec a povoluje kontroly stavu, trasování a metriky pro komponentu PostgreSQL. Kód pak už nemusíte zadávat připojovací řetězec, stačí použít builder.AddNpgsqlDataSource();.

Pokud používáte komponentu PostgreSQL Entity Framework Core, můžete pomocí Aspire:Npgsql:EntityFrameworkCore:PostgreSQL klíče nakonfigurovat kontext databáze:

{
  "Aspire": {
    "Npgsql": {
      "EntityFrameworkCore": {
        "PostgreSQL": {
          "ConnectionString": "Host=myserver;Database=postgresdb;User id=myuser;Password=mypassword",
          "MaxRetryCount": 0,
          "HealthChecks": false,
          "Tracing": false
        }
      }
    }
  }
}

Další informace o možnostech konfigurace entity Framework naleznete v dokumentaci k .NET Aspire.

Použití vložených delegátů

Poslední možností je předat vložený configureSettings delegát metodě AddNpgsqlDataSource . Tento delegát umožňuje konfigurovat nastavení pro komponentu databáze přímo pomocí kódu:

builder.AddNpgsqlDataSource(
    "postgresdb", static settings => settings.HealthChecks = false);

Použití komponent .NET Aspire SQL Database

Předchozí vzor je stejný pro komponentu SQL Database. V hostitelském projektu aplikace i v mikroslužbách, které využívají databázovou službu, provedete změny.

Konfigurace hostitele aplikace

Pokud chcete nainstalovat součást hostování databáze SQL, použijte tento příkaz:

dotnet add package Aspire.Hosting.SqlServer --prerelease

Pokud chcete zaregistrovat kontejner a databázi, přidejte tento kód do souboru Program.cs hostitele aplikace:

var sql = builder.AddSqlServer("sql");
var sqldb = sql.AddDatabase("sqldb");

Pak předejte odkaz na databázovou službu všem projektům, které ji využívají:

var northernTradersCatalogAPI = builder.AddProject<Projects.NorthernTraders_CatalogAPI>()
                                       .WithReference(sqldb);

Konfigurace náročných projektů

Pokud chcete nainstalovat komponentu .NET Aspire SQL Database, použijte příkaz podobný tomuto v projektech .NET Aspire:

dotnet add package Aspire.Microsoft.Data.SqlClient --prerelease

Nebo pokud chcete použít komponentu .NET Aspire SqlServer Entity Framework Core, použijte místo toho tento příkaz:

dotnet add package Aspire.Microsoft.EntityFrameworkCore.SqlServer --prerelease

Tyto balíčky NuGet je možné přidat také pomocí zástupce přidat komponentu .>NET Aspire v sadě Visual Studio.

*. Kód souboru Program.cs projektu AppHost pro přístup k databázi je podobný příkladu PostgreSQL:

var sqlServer = builder.AddSqlServer("sql")
                       .AddDatabase("sqldata");

var myService = builder.AddProject<Projects.MyService>()
                       .WithReference(sqlServer);

Použití databáze SQL Serveru

V projektech, které potřebují přístup SQL, tento kód v souboru Program.cs zaregistruje kontext databáze Entity Framework:

builder.AddSqlServerDbContext<YourDbContext>("sqldata");

Jakmile je databáze zaregistrovaná v náročném projektu, můžete s kontextem YourDbContext databáze pracovat pomocí injektáže závislostí. Tento ukázkový kód načte předpověď počasí z databáze a vybere jednu náhodně, která se má vrátit:

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

Konfigurace komponenty SQL Serveru

Stejně jako předtím, pokud použijete stejný název databáze v hostiteli aplikace a spotřebě projektu, nemusíte konfigurovat připojení mezi databází SQL Serveru a projekty. Komponenta .NET Aspire SQL Serveru také podporuje další způsoby konfigurace komponenty.

Použití zprostředkovatelů konfigurace

Komponenta SQL Serveru také podporuje Microsoft.Extensions.Configuration. Ve výchozím nastavení hledá nastavení pomocí Aspire:SqlServer:SqlClient klíče. V projektech používajících appsettings.json může ukázková konfigurace vypadat takto:

{
  "Aspire": {
    "SqlServer": {
      "SqlClient": {
        "ConnectionString": "YOUR_CONNECTIONSTRING",
        "HealthChecks": true,
        "Tracing": false,
        "Metrics": false
      }
    }
  }
}

Použití vložených konfigurací

Když přidáte komponentu SYSTÉMU SQL Server, můžete metodě AddSqlServerClient předat vložený configureSettings delegát. Tento delegát umožňuje konfigurovat nastavení pro komponentu databáze přímo pomocí kódu:

builder.AddSqlServerClient("sqldata", static settings => settings.HealthChecks = false);

Můžete předat některou z podporovaných možností:

ConnectionString: Připojovací řetězec databáze SQL Serveru
HealthChecks: Logická hodnota označující, jestli je povolená kontrola stavu databáze.
Tracing: Logická hodnota označující, jestli je povolené trasování OpenTelemetry.
Metrics: Logická hodnota označující, jestli jsou povoleny metriky OpenTelemetry.

Připojení k více databázím

Komponenta SQL Serveru podporuje více připojení prostřednictvím pojmenovaných instancí. Můžete se například připojit ke dvěma různým databázím SQL Serveru ve stejném projektu:

{
  "Aspire": {
    "SqlServer": {
      "SqlClient": {
        "INSTANCE_1": {
          "ServiceUri": "YOUR_URI",
          "HealthChecks": false
        },
        "INSTANCE_2": {
          "ServiceUri": "YOUR_URI",
          "HealthChecks": false
        }
      }
    }
  }
}

Pomocí této konfigurace se můžete připojit ke dvěma různým databázím ve stejném projektu:

builder.AddSqlServerClient("INSTANCE_1");
builder.AddSqlServerClient("INSTANCE_2");

Použití komponenty MySQL

Pokud chcete nainstalovat komponentu .NET Aspire MySQL, použijte příkaz podobný tomuto v projektech .NET Aspire, které vyžadují přístup k datům:

dotnet add package Aspire.MySqlConnector --prerelease

Nebo pomocí zástupce Přidat > komponentu .NET Aspire v sadě Visual Studio nainstalujte komponentu ze správce balíčků NuGet.

*. Kód souboru Program.cs projektu AppHost pro přístup k databázi je podobný příkladu PostgreSQL:

var mysqldb = builder.AddMySql("mysql")
                     .AddDatabase("mysqldb")
                     .WithPhpMyAdmin();

var myService = builder.AddProject<Projects.MyService>()
                       .WithReference(mysqldb);

Podobně jako komponenta PostgreSQL umožňuje komponenta MySQL také vytvořit kontejner pro nástroje pro správu databází. Předchozí příklad přidá Do řešení PhpMyAdmin .

Použití databáze MySQL

Vzor je stejný v projektech, které potřebují přístup k MySQL. V souboru Program.cs tento kód zaregistruje databázi:

builder.AddMySqlDataSource("mysqldb");

Jakmile je databáze zaregistrovaná v náročném projektu, můžete s zdrojem dat pracovat, kdykoli ji potřebujete, pomocí injektáže závislostí:

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

Konfigurace komponenty MySQL

Komponenta MySQL podporuje stejné tři možnosti správy konfigurace.

Připojovací řetězce

Soubor appsettings.json může obsahovat připojovací řetězec databáze MySQL:

{
  "ConnectionStrings": {
    "MySqConnection": "Server=myserver;Database=mysqldb;Uid=myuser;Pwd=mypassword"
  }
}

Pak se v projektu můžete připojit k databázi pomocí připojovací řetězec pomocí kódu, jako je tento:

builder.AddMySqlDataSource("MySqConnection");

Poskytovatelé konfigurace

Klíč Aspire:MySqlConnector se používá ke konfiguraci komponenty MySQL.

{
  "Aspire": {
    "MySqlConnector": {
      "ConnectionString": "Server=myserver;Database=mysqldb;Uid=myuser;Pwd=mypassword",
      "HealthChecks": true,
      "Tracing": false,
      "Metrics": false
    }
  }
}

Vložené konfigurace

builder.AddMySqlDataSource("mysqldb", static settings => settings.HealthChecks = false);

Naučte se, jak se dosadí databáze.

Zásobník .NET Aspire používá kontejnery a získává výhody konzistentních prostředí a snadných nasazení. Nevýhodou je, že kontejnery jsou bezstavové. Všechna data nebo schémata přidaná do databáze se při zničení kontejneru ztratí. .NET Aspire poskytuje způsoby, jak zasadit databáze s daty při vytváření jejich kontejnerů.

Použití svazků a skriptů

Nejjednodušším způsobem, jak svoji databázi dosadí, je použít svazky a skripty SQL. Svazky můžou ukládat data pro více kontejnerů najednou, nabízejí vysoký výkon a snadno se zálohují nebo migrují. Skripty uložené v těchto svazcích se spustí při vytvoření kontejneru a naplní databázi daty. Skriptem může být soubor SQL, který obsahuje data a schéma, které chcete pro databázi použít.

Pokud jste například měli tento skript SQL uložený v souboru s názvem postgres-backup.sql, ve složce 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);

V hostiteli aplikace vašeho řešení můžete vytvořit vazbu složky Service.API/Seed ke složce /docker-entrypoint-initdb.d kontejneru. Tato složka je speciální složkou v kontejneru PostgreSQL, která spouští všechny skripty SQL, které najde při vytvoření kontejneru:

    var catalogDB = builder.AddPostgres("postgres")
      .WithPgAdmin()
      .WithEnvironment("POSTGRES_DB", "backendDB")
      .WithBindMount("../Service.API/Seed", "/docker-entrypoint-initdb.d")
      .AddDatabase("backendDB");

Skripty SQL můžete dokonce rozdělit na vytváření schématu a počáteční skripty dat. Pokud jsou všechny obsažené ve složce Service.API/Seed , spustí se při vytváření databáze .NET Aspire.

Počáteční data pomocí Entity Framework Core

Pro komponenty, které podporují Entity Framework Core, můžete svou databázi připravit pomocí DbContext migrace třídy a Entity Framework Core. Tato metoda používá kód jazyka C# k vytvoření databáze. K tomuto seedingu by však mělo dojít pouze během vývoje nebo testování, nikoli v produkčním prostředí.

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

Výše uvedený kód zkontroluje stav prostředí aplikace. Pokud je ve vývoji, kód načte CatalogContext třídu a spustí metodu EnsureCreated . Tato metoda vytvoří databázi a spustí všechny čekající migrace.

Další informace o tom, jak nasadit různé databázové komponenty, naleznete v dokumentaci k .NET Aspire.

Pokračovat

Ukládání dat v databázích kompatibilních s SQL

Postup přidání databázové komponenty do projektu

Použití komponent .NET Aspire PostgreSQL

Konfigurace hostitele aplikace

Konfigurace náročných projektů

Použití databáze PostgreSQL

Konfigurace komponenty PostgreSQL

Použití připojovací řetězec

Použití zprostředkovatelů konfigurace

Použití vložených delegátů

Použití komponent .NET Aspire SQL Database

Konfigurace hostitele aplikace

Konfigurace náročných projektů

Použití databáze SQL Serveru

Konfigurace komponenty SQL Serveru

Použití zprostředkovatelů konfigurace

Použití vložených konfigurací

Připojení k více databázím

Použití komponenty MySQL

Použití databáze MySQL

Konfigurace komponenty MySQL

Připojovací řetězce

Poskytovatelé konfigurace

Vložené konfigurace

Naučte se, jak se dosadí databáze.

Použití svazků a skriptů

Počáteční data pomocí Entity Framework Core

Váš názor