Gegevens opslaan in sql-compatibele databases

15 minuten

De .NET Aspire-stack is ontworpen om u productiever te maken en u te helpen bij het bouwen van robuuste, schaalbare en veilige webtoepassingen. U kunt gestructureerde relationele gegevens snel opslaan door een van de ondersteunde Aspire-onderdelen toe te voegen.

De huidige sql-compatibele databaseonderdelen zijn:

PostgreSQL-databases
SQL Databases
Oracle-databases
MySQL-databases

Notitie

Microsoft kan ook ondersteuning toevoegen voor andere databasesystemen en derden, zodat deze lijst kan worden uitgebreid.

In deze les leert u meer over drie van deze onderdelen, die databases Entity Framework Core ondersteunen en hoe u deze kunt gebruiken om gegevens op te slaan en op te halen.

Een databaseonderdeel toevoegen aan uw project

Welke database u ook kiest, de methode voor het toevoegen van een .NET Aspire-databaseonderdeel aan uw project is hetzelfde.

In het app-hostproject:

Installeer het hostonderdeel .NET Aspire in het app-hostproject.
Registreer een database en maak er een container voor in de app-host van de oplossing.
Geef een verwijzing door naar de projecten die toegang nodig hebben tot de gemaakte container die als host fungeert voor de database.

In de projecten die gebruikmaken van de database:

Voeg het .NET Aspire-onderdeel toe met een NuGet-pakket aan de projecten waarvoor gegevenstoegang is vereist. Als er een EF-onderdeel (.NET Core Entity Framework) is, kunt u dat ook gebruiken.
Registreer de gegevensbron of databasecontext voor EF in het Program.cs-bestand van het project.
Gebruik afhankelijkheidsinjectie om de gegevensbron in uw services te injecteren.

Laten we eens kijken naar de details van het uitvoeren van deze stappen voor elk van de ondersteunde databases.

De .NET Aspire PostgreSQL-onderdelen gebruiken

De .NET Aspire PostgreSQL-onderdelen vereisen wijzigingen in zowel het app-hostproject als eventuele microservices die gebruikmaken van de databases.

De app-host configureren

Begin met het installeren van het juiste hostingonderdeel op de app-host:

dotnet add package Aspire.Hosting.PostgreSQL --prerelease

Als u vervolgens een database wilt registreren en er een container voor wilt maken, voegt u deze code toe aan het Program.cs-bestand van de app-host:

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

U moet ook een verwijzing naar de databaseservice doorgeven aan alle projecten die deze gebruiken:

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

De verbruikende projecten configureren

Als u het .NET Aspire PostgreSQL-onderdeel wilt installeren, gebruikt u een opdracht zoals deze in uw .NET Aspire-projecten:

dotnet add package Aspire.Npgsql --prerelease

Als u het .NET Aspire PostgreSQL Entity Framework Core-onderdeel wilt gebruiken, gebruikt u in plaats daarvan deze opdracht:

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

U kunt ook de snelkoppeling .NET Aspire Component toevoegen > in Visual Studio gebruiken om het onderdeel te installeren vanuit NuGet-pakketbeheer:

Code in de *. Het Program.cs-bestand van AppHost-project maakt de database en geeft deze door aan projecten die het willen gebruiken:

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

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

Met sommige .NET Aspire-databaseonderdelen kunt u ook een container maken voor databasebeheerhulpprogramma's. Gebruik deze code om PgAdmin toe te voegen aan uw oplossing om de PostgreSQL-database te beheren:

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

Het voordeel van het maken van .NET Aspire is dat u geen configuratie hoeft uit te voeren om PgAdmin te verbinden met de PostgreSQL-database. Dit is allemaal automatisch.

Een PostgreSQL-database gebruiken

In een project waarin u de database wilt gebruiken, voegt u een gegevensbron toe om de verbinding met PostgreSQL weer te geven. In het bestand Program.cs registreert deze code de database:

builder.AddNpgsqlDataSource("postgresdb");

Als u een Entity Framework Core-onderdeel wilt gebruiken, registreert u de databasecontext:

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

Zodra de database is geregistreerd in het verbruikende project, kunt u met de gegevensbron communiceren wanneer u deze nodig hebt met behulp van afhankelijkheidsinjectie:

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

U kunt ook de databasecontext YourDbContext ophalen om met de database te communiceren:

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

Het PostgreSQL-onderdeel configureren

De .NET Aspire-stack probeert de hoeveelheid configuratie te verminderen die u moet doen. Met behulp van afhankelijkheidsinjectie en servicedetectie hebt u toegang tot de database zonder dat u de verbindingsreeks s in uw projecten hoeft te configureren.

Met behulp van het app-hostproject om de databasecontainer te maken en door te geven als verwijzing naar de projecten, kunnen de ontvangende projecten toegang krijgen tot de databaselocatie, verbindingsreeks s en poorten. U hoeft geen omgevingsvariabelen of appsettings.json bestanden te beheren.

Maar als u wilt, of als u meer controle nodig hebt over de configuratie van de database, zijn er meer opties.

Een verbindingsreeks

In het project waarvoor de database is vereist, gebruikt u een verbindingsreeks om verbinding te maken met de database. Deze methode is handig wanneer u verbinding moet maken met een database die niet is geregistreerd in de app-host.

builder.AddNpgsqlDataSource("NpgsqlConnectionString");

Vervolgens kunt u in het configuratiebestand de verbindingsreeks toevoegen:

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

Configuratieproviders gebruiken

.NET Aspire heeft een functie van onderdelen waarmee ze een Microsoft.Extensions.Configuration. Het PostgreSQL-onderdeel ondersteunt deze functie en zoekt standaard naar instellingen met behulp van de Aspire:Npgsql sleutel. In projecten met behulp van appsettings.json kan een voorbeeldconfiguratie er als volgt uitzien:

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

De vorige configuratie is het instellen van de verbindingsreeks, het inschakelen van statuscontroles, tracering en metrische gegevens voor het PostgreSQL-onderdeel. Vervolgens hoeft u de verbindingsreeks niet meer op te geven.builder.AddNpgsqlDataSource();

Als u het PostgreSQL Entity Framework Core-onderdeel gebruikt, kunt u de Aspire:Npgsql:EntityFrameworkCore:PostgreSQL sleutel gebruiken om de databasecontext te configureren:

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

Zie de .NET Aspire-documentatie voor meer informatie over de entity framework-configuratieopties.

Inline gedelegeerden gebruiken

De laatste optie is om een configureSettings inline gedelegeerde door te geven aan de AddNpgsqlDataSource methode. Met deze gemachtigde kunt u de instellingen voor het databaseonderdeel rechtstreeks configureren met code:

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

De onderdelen van .NET Aspire SQL Database gebruiken

Het vorige patroon is hetzelfde voor het SQL Database-onderdeel. U kunt wijzigingen aanbrengen in zowel het app-hostproject als de microservices die de databaseservice gebruiken.

De app-host configureren

Als u het hostonderdeel sql-database wilt installeren, gebruikt u deze opdracht:

dotnet add package Aspire.Hosting.SqlServer --prerelease

Als u de container en database wilt registreren, voegt u deze code toe aan het Program.cs-bestand van de app-host:

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

Geef vervolgens een verwijzing naar de databaseservice door aan alle projecten die deze gebruiken:

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

De verbruikende projecten configureren

Als u het .NET Aspire SQL Database-onderdeel wilt installeren, gebruikt u een opdracht zoals deze in uw .NET Aspire-projecten:

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

Als u het .NET Aspire SqlServer Entity Framework Core-onderdeel wilt gebruiken, gebruikt u in plaats daarvan deze opdracht:

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

Deze NuGet-pakketten kunnen ook worden toegevoegd met behulp van de snelkoppeling .NET Aspire Component toevoegen > in Visual Studio.

De *. De Program.cs-bestandscode van het AppHost-project voor toegang tot de database is vergelijkbaar met het PostgreSQL-voorbeeld:

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

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

Een SQL Server-database gebruiken

In de projecten waarvoor SQL-toegang is vereist, registreert deze code in het bestand Program.cs de context van de Entity Framework-database:

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

Zodra de database is geregistreerd in het verbruikende project, kunt u communiceren met de databasecontext YourDbContext met behulp van afhankelijkheidsinjectie. Deze voorbeeldcode haalt weersvoorspellingen op uit een database en selecteert er een willekeurig om te retourneren:

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

Het SQL Server-onderdeel configureren

Net als voorheen hoeft u, als u dezelfde databasenaam gebruikt in de app-host en het verbruikende project, de verbinding tussen uw SQL Server-database en de projecten niet te configureren. Het .NET Aspire SQL Server-onderdeel ondersteunt ook andere manieren om het onderdeel te configureren.

Configuratieproviders gebruiken

Het SQL Server-onderdeel ondersteunt Microsoft.Extensions.Configurationook . Standaard wordt er gezocht naar instellingen met behulp van de Aspire:SqlServer:SqlClient sleutel. In projecten met behulp van appsettings.json kan een voorbeeldconfiguratie er als volgt uitzien:

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

Inlineconfiguraties gebruiken

Wanneer u het SQL Server-onderdeel toevoegt, kunt u een configureSettings inline gedelegeerde doorgeven aan de AddSqlServerClient methode. Met deze gemachtigde kunt u de instellingen voor het databaseonderdeel rechtstreeks configureren met code:

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

U kunt een van de ondersteunde opties doorgeven:

ConnectionString: de verbindingsreeks van de SQL Server-database
HealthChecks: Een Booleaanse waarde die aangeeft of de databasestatuscontrole is ingeschakeld
Tracing: Een Booleaanse waarde die aangeeft of de OpenTelemetry-tracering is ingeschakeld
Metrics: Een Booleaanse waarde die aangeeft of de metrische gegevens van OpenTelemetry zijn ingeschakeld

Verbinding maken met meerdere databases

Het SQL Server-onderdeel ondersteunt meerdere verbindingen via benoemde exemplaren. U kunt bijvoorbeeld verbinding maken met twee verschillende SQL Server-databases in hetzelfde project:

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

Met deze configuratie kunt u verbinding maken met de twee verschillende databases in hetzelfde project:

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

Het MySQL-onderdeel gebruiken

Als u het .NET Aspire MySQL-onderdeel wilt installeren, gebruikt u een opdracht zoals deze in uw .NET Aspire-projecten waarvoor gegevenstoegang is vereist:

dotnet add package Aspire.MySqlConnector --prerelease

Of gebruik de snelkoppeling .NET Aspire Component toevoegen > in Visual Studio om het onderdeel te installeren vanuit NuGet Package Manager.

De *. De Program.cs-bestandscode van het AppHost-project voor toegang tot de database is vergelijkbaar met het PostgreSQL-voorbeeld:

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

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

Net als het PostgreSQL-onderdeel kunt u met het MySQL-onderdeel ook een container maken voor hulpprogramma's voor databasebeheer. In het vorige voorbeeld wordt PhpMyAdmin toegevoegd aan de oplossing.

Een MySQL-database gebruiken

Het patroon is hetzelfde in de projecten waarvoor MySQL-toegang nodig is. In het bestand Program.cs registreert deze code de database:

builder.AddMySqlDataSource("mysqldb");

Zodra de database is geregistreerd in het verbruikende project, kunt u met de gegevensbron communiceren wanneer u deze nodig hebt met behulp van afhankelijkheidsinjectie:

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

Het MySQL-onderdeel configureren

Het MySQL-onderdeel ondersteunt dezelfde drie opties voor het beheren van de configuratie.

Verbindingsreeksen

Het bestand appsettings.json kan de verbindingsreeks voor de MySQL-database bevatten:

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

Vervolgens kunt u in uw project verbinding maken met de database met de verbindingsreeks met behulp van code als volgt:

builder.AddMySqlDataSource("MySqConnection");

Configuratieproviders

De Aspire:MySqlConnector sleutel wordt gebruikt om het MySQL-onderdeel te configureren.

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

Inlineconfiguraties

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

Meer informatie over het seeden van uw database

De .NET Aspire-stack maakt gebruik van containers, wat de voordelen van consistente omgevingen en eenvoudige implementaties biedt. Een nadeel is dat de containers staatloos zijn. Alle gegevens of schema's die aan een database worden toegevoegd, gaan verloren wanneer de container wordt vernietigd. .NET Aspire biedt manieren om uw databases te seeden met gegevens wanneer ze hun containers maken.

Volumes en scripts gebruiken

De eenvoudigste manier om uw database te seeden, is door volumes en SQL-scripts te gebruiken. Volumes kunnen gegevens voor meerdere containers tegelijk opslaan, hoge prestaties bieden en eenvoudig back-ups maken of migreren. De scripts die in deze volumes worden opgeslagen, worden uitgevoerd wanneer een container wordt gemaakt en vullen de database met gegevens. Het script kan een SQL-bestand zijn dat de gegevens en het gewenste schema voor uw database bevat.

Als u bijvoorbeeld dit SQL-script hebt, opgeslagen in een bestand met de naam postgres-backup.sql, in de map 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);

In de app-host van uw oplossing kunt u de map Service.API/Seed binden aan de map /docker-entrypoint-initdb.d van de container. Deze map is een speciale map in de PostgreSQL-container die SQL-scripts uitvoert die worden gevonden wanneer de container wordt gemaakt:

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

U kunt de SQL-scripts zelfs splitsen in het maken van schema's en het seeden van gegevens. Als ze allemaal zijn opgenomen in de map Service.API/Seed , worden ze uitgevoerd wanneer .NET Aspire de database maakt.

Gegevens seeden met Entity Framework Core

Voor de onderdelen die Entity Framework Core ondersteunen, kunt u uw database seeden met behulp van de DbContext klasse- en Entity Framework-kernmigraties. Deze methode maakt gebruik van C#-code om de database te seeden. Deze seeding mag echter alleen plaatsvinden tijdens het ontwikkelen of testen, niet in productie.

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

De bovenstaande code controleert de status van de app-omgeving. Als deze in ontwikkeling is, haalt de code de CatalogContext klasse op en voert de EnsureCreated methode uit. Met deze methode maakt u de database en voert u alle migraties uit die in behandeling zijn.

Zie de .NET Aspire-documentatie voor meer informatie over het seeden van de verschillende databaseonderdelen.

Gegevens opslaan in sql-compatibele databases

Een databaseonderdeel toevoegen aan uw project

De .NET Aspire PostgreSQL-onderdelen gebruiken

De app-host configureren

De verbruikende projecten configureren

Een PostgreSQL-database gebruiken

Het PostgreSQL-onderdeel configureren

Een verbindingsreeks

Configuratieproviders gebruiken

Inline gedelegeerden gebruiken

De onderdelen van .NET Aspire SQL Database gebruiken

De app-host configureren

De verbruikende projecten configureren

Een SQL Server-database gebruiken

Het SQL Server-onderdeel configureren

Configuratieproviders gebruiken

Inlineconfiguraties gebruiken

Verbinding maken met meerdere databases

Het MySQL-onderdeel gebruiken

Een MySQL-database gebruiken

Het MySQL-onderdeel configureren

Verbindingsreeksen

Configuratieproviders

Inlineconfiguraties

Meer informatie over het seeden van uw database

Volumes en scripts gebruiken

Gegevens seeden met Entity Framework Core

Feedback