Cvičení – použití databázových služeb k zachování dat z projektu .NET Aspire

  • 20 min

V tomto cvičení nahradíte aktuální úložiště dat pro aplikaci nativní pro vývoj v cloudu vaší společnosti. V tuto chvíli aplikace používá místně uloženou databázi SQLite pro data katalogu a mezipaměť Redis Cache v paměti pro nákupní košíky zákazníka. Stávající úložiště dat nahradíte PostgreSQL a MongoDB.

Požadavky na instalaci

Požadavky pro .NET Aspire jsou:

  • .NET 8
  • Visual Studio 2022 Preview
  • Docker Desktop nebo Podman
  • Úloha .NET Aspire v sadě Visual Studio

Pokud už máte nainstalované požadavky, můžete přeskočit k klonování stávající aplikace.

Instalace .NET 8

Postupujte podle tohoto odkazu na .NET 8 a vyberte správný instalační program pro váš operační systém. Pokud například používáte Windows 11 a moderní procesor, vyberte sadu x64 .NET 8 SDK pro Windows.

Po dokončení stahování spusťte instalační program a postupujte podle pokynů. V okně terminálu spusťte následující příkaz a ověřte, že instalace proběhla úspěšně:

dotnet --version

Měli byste vidět číslo verze sady .NET SDK, kterou jste nainstalovali. Příklad:

8.0.300-preview.24203.14

Instalace sady Visual Studio 2022 Preview

Postupujte podle tohoto odkazu sady Visual Studio 2022 Preview a vyberte Stáhnout verzi Preview. Po dokončení stahování spusťte instalační program a postupujte podle pokynů.

Instalace Docker Desktopu

Postupujte podle tohoto odkazu na Docker Desktop a vyberte správný instalační program pro váš operační systém. Po dokončení stahování spusťte instalační program a postupujte podle pokynů.

Otevřete aplikaci Docker Desktop a přijměte smlouvu o poskytování služeb.

Instalace úlohy .NET Aspire v sadě Visual Studio

Nainstalujte úlohu .NET Aspire pomocí rozhraní příkazového řádku .NET:

  1. Otevřete terminál.

  2. Pomocí těchto příkazů nainstalujte úlohy .NET Aspire:

    dotnet workload update
dotnet workload install aspire
dotnet workload list

    Měli byste vidět podrobnosti o úloze .NET Aspire.

     Installed Workload Id      Manifest Version      Installation Source
---------------------------------------------------------------------------------------------
aspire                     8.0.0/8.0.100         SDK 8.0.300-preview.24203, VS 17.10.34902.84

Use `dotnet workload search` to find additional workloads to install.

Klonování a úprava aplikace Severní hory

Pojďme použít git k získání aktuální aplikace Severní hory:

  1. Na příkazovém řádku přejděte do složky podle vašeho výběru, kde můžete pracovat s kódem.

  2. Spuštěním následujícího příkazu naklonujte ukázkovou aplikaci Northern Mountains eShop :

    git clone -b aspire-databases https://github.com/MicrosoftDocs/mslearn-aspire-starter

  3. Spusťte Visual Studio a pak vyberte Otevřít projekt nebo řešení.

  4. Přejděte do složky, do které jste naklonovali eShop, otevřete počáteční složku a vyberte eShop.databases.sln soubor a pak vyberte Otevřít.

  5. V Průzkumník řešení rozbalte projekt eShop.AppHost a otevřete Program.cs.

    // Databases

var basketStore = builder.AddRedis("BasketStore").WithRedisCommander();

// Identity Providers

var idp = builder.AddKeycloakContainer("idp", tag: "23.0")
    .ImportRealms("../Keycloak/data/import");

// DB Manager Apps

builder.AddProject<Projects.Catalog_Data_Manager>("catalog-db-mgr");

// API Apps

var catalogApi = builder.AddProject<Projects.Catalog_API>("catalog-api");

var basketApi = builder.AddProject<Projects.Basket_API>("basket-api")
        .WithReference(basketStore)
        .WithReference(idp);

// Apps

// Force HTTPS profile for web app (required for OIDC operations)
var webApp = builder.AddProject<Projects.WebApp>("webapp")
    .WithReference(catalogApi)
    .WithReference(basketApi)
    .WithReference(idp, env: "Identity__ClientSecret");

    Předchozí kód zobrazuje aktuální konfiguraci aplikace. Aplikace používá mezipaměť Redis pro obchod s košíky.

  6. Prozkoumejte zbytek aplikace, zaměřte se na projekty Catalog.Data.Manager a Catalog.API a podívejte se, jak používají místně uloženou databázi SQLite.

  7. Aplikaci spustíte stisknutím klávesy F5 nebo výběrem možnosti > Spustit ladění.

  8. Pokud se zobrazí dialogové okno Start Docker Desktop , vyberte Ano.

  9. Jakmile se zobrazí řídicí panel eShop .NET Aspire, vyberte pro prostředek webové aplikace zabezpečený koncový bod:

    Snímek obrazovky s řídicím panelem EShop .NET Aspire Koncový bod webové aplikace je zvýrazněný.

  10. Aplikace se otevře v prohlížeči. Aplikaci můžete prozkoumat a zjistit, jak funguje.

    Snímek obrazovky s domovskou stránkou eShopu

    Testovací přihlašovací údaje uživatele jsou test@example.com a P@$$w 0rd1.

  11. Ladění zastavíte stisknutím kláves Shift+F5 nebo vyberete Ladění > zastavit ladění.

Přidání komponenty .NET Aspire PostgreSQL

Tým zodpovědný za mikroslužby katalogu vytvořil aplikaci tak, aby používal místně uloženou databázi SQLite. Tento přístup je v pořádku pro vývoj, ale tým chce použít robustnější databázi pro produkční prostředí.

Dva projekty se připojují k databázi SQLite, k projektům Catalog.Data.Manager a Catalog.API . Správce dat se používá pouze k vytvoření databáze s daty, takže byste se měli zaměřit na projekt Catalog.API .

  1. V Průzkumník řešení klikněte pravým tlačítkem na projekt Catalog.API a vyberte Balíček Add.NET> Aspire.

  2. Do vyhledávacího pole přidejte na konec npgsql.EntityFramework a stiskněte Enter.

  3. Na levé straně ve výsledcích vyberte Aspire.Npgsql.EntityFrameworkCore.PostgreSQL.

  4. Vpravo vyberte rozevírací seznam verze a pak vyberte nejnovější verzi 8.0.0 .

  5. Vyberte volbu Instalovat.

  6. Pokud se zobrazí dialogové okno Náhled změn, vyberte Použít.

  7. V dialogovém okně Přijetí licence vyberte Přijmout.

  8. V Průzkumník řešení vyberte projekt Catalog.API a zobrazte obsah souboru Catalog.API.csproj.

  9. PackageReference Odstraňte microsoft.EntityFrameworkCore.Sqlite:

    <PackageReference Include="Microsoft.EntityFrameworkCore.Sqlite" Version="8.0.3" />

Registrace nové databáze PostgreSQL DbContext

  1. V Průzkumník řešení rozbalte projekt Catalog.API a otevřete soubor Program.cs.

  2. Nahraďte SQLite DbContext:

    builder.Services.AddDbContext<CatalogDbContext>(
     options => options.UseSqlite(builder.Configuration.GetConnectionString("sqlconnection")
 	    ?? throw new InvalidOperationException(
 		    "Connection string 'sqlconnection' not found.")));

    S novým PostgreSQL DbContext:

    builder.AddNpgsqlDbContext<CatalogDbContext>("CatalogDB");

    Aplikace už nemusí číst Database.db soubor, takže odeberte přidružené řetězce v appsettings.json.

  3. V Průzkumník řešení v části Catalog.API vyberte appsettings.json.

  4. ConnectionStrings Odstraňte položky, soubor teď vypadá takto:

    {
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "OpenApi": {
    "Endpoint": {
      "Name": "Catalog.API v1"
    },
    "Document": {
      "Description": "The Catalog Microservice HTTP API. This is a Data-Driven/CRUD microservice sample",
      "Title": "eShop - Catalog HTTP API",
      "Version": "v1"
    }
  },
  "CatalogOptions": {
    "PicBasePathFormat": "items/{0}/pic/"
  }
}

  5. Klikněte pravým tlačítkem myši na projekt Catalog.Data.Manager a pak vyberte Odebrat.

  6. V dialogovém okně vyberte OK.

Databázový tým vytvoří zálohu databáze PostgreSQL, kterou můžete použít k vytvoření a nasazení databáze katalogu. Zálohu můžete zobrazit ve složce Catalog.API/Seed .

Vytvoření databáze PostgreSQL pomocí vázaného svazku

Projekt AppHost může vytvořit kontejner databáze PostgreSQL, nasadit ho daty z vázaného svazku a pak prostřednictvím injektáže závislostí předat odkazy na Catalog.API.

  1. V Průzkumník řešení klikněte pravým tlačítkem na projekt eShop.AppHost a vyberte Balíček Add.NET> Aspire.

  2. Do vyhledávacího pole přidejte na konec PostgreSQL a stiskněte Enter.

  3. Na levé straně ve výsledcích vyberte Aspire.Hosting.PostgreSQL.

  4. Vpravo vyberte rozevírací seznam verze a pak vyberte nejnovější verzi 8.0.0 .

  5. Vyberte volbu Instalovat.

  6. Pokud se zobrazí dialogové okno Náhled změn, vyberte Použít.

  7. V dialogovém okně Přijetí licence vyberte Přijmout.

  8. V Průzkumník řešení rozbalte projekt eShop.AppHost a otevřete Program.cs soubor.

  9. //Databases Pod komentář přidejte následující kód:

    // Databases

var basketStore = builder.AddRedis("BasketStore").WithRedisCommander();
var postgres = builder.AddPostgres("postgres")
    .WithEnvironment("POSTGRES_DB", "CatalogDB")
    .WithBindMount("../Catalog.API/Seed", "/docker-entrypoint-initdb.d").WithPgAdmin();
var catalogDB = postgres.AddDatabase("CatalogDB");

    Předchozí kód vytvoří kontejner databáze PostgreSQL, přidá databázi s názvem CatalogDB a vytvoří vazbu adresáře /docker-entrypoint-initdb.d s adresářem .. /Catalog.API/Počáteční adresář. Kód také vytvoří kontejner pro nástroj pgAdmin, který umožňuje spravovat databázi PostgreSQL.

  10. catalogDB Přidejte odkaz na projekt Catalog.API přidáním .WithReference(catalogDB)kódu:

    // API Apps

var catalogApi = builder.AddProject<Projects.Catalog_API>("catalog-api")
  .WithReference(catalogDB);

  11. Projekt Catalog.Data.Manager už není potřeba, proto projekt odeberte z AppHostu. Odstraňte tento kód:

    // DB Manager Apps

builder.AddProject<Projects.Catalog_Data_Manager>("catalog-db-mgr");

Otestování aplikace

Použití .NET Aspire umožnilo vašemu týmu odebrat celý projekt. Rozhraní API katalogu také potřebuje pouze jeden řádek kódu pro přidání kontextu databáze PostgresSQL. Injektáž závislostí a zjišťování služby z AppHost znamenají, že nejsou potřeba žádné další změny kódu, aby se rozhraní API mohlo připojit k nové databázi.

  1. Zkompilujte a spusťte aplikaci, stiskněte klávesu F5 nebo vyberte > Spustit ladění.

    Snímek obrazovky znázorňující aktualizovaný řídicí panel .NET Aspire se zvýrazněnými dvěma novými kontejnery PostgreSQL

    Na řídicím panelu jsou dva nové kontejnery, které hostují databázový server PostgreSQL a nástroj pgAdmin. K dispozici je také prostředek databáze PostgreSQL, který je hostitelem databáze CatalogDB.

  2. Pomocí nástroje pgAdmin se připojte k databázi PostgreSQL a prozkoumejte data. Vyberte koncový bod postgres pgadmin.

    Snímek obrazovky s rozhraním pgAdmin, který zvýrazňuje navigaci na tabulku Katalog.

  3. Rozbalte položky postgres>>Databases CatalogDB Schemas>>>CatalogDB>Tables. Potom klikněte pravým tlačítkem myši na tabulku Katalog a vyberte Zobrazit/Upravit data>Prvních 100 řádků.

  4. Zobrazí se data načtená hostitelem AppHost.

    Snímek obrazovky s rozhraním pgAdmin zobrazující vrácené řádky z tabulky Katalog

  5. V prohlížeči vyberte kartu řídicího panelu prostředků eShop a pak vyberte koncový bod webové aplikace .

  6. Aplikace se otevře a funguje jako předtím.

  7. Ladění zastavíte stisknutím kláves Shift+F5 nebo vyberete Ladění > zastavit ladění.

Přidání komponenty .NET Aspire MongoDB do aplikace

Aktuální aplikace používá Redis jako úložiště dat v paměti pro nákupní košík zákazníka. Tým chce pro košík používat robustnější a odolné úložiště dat. Mezipaměť Redis nahraďte databází MongoDB.

Změna rozhraní Basket.API tak, aby používala MongoDB

  1. V Průzkumník řešení klikněte pravým tlačítkem myši na projekt Basket.API, vyberte Přidat a pak vyberte Přidat.NET> Aspire balíček.
  2. Do vyhledávacího pole na konci zadejte MongoDB a stiskněte Enter.
  3. Vyberte ovladač Aspire.MongoDB.Driver a pak vyberte nejnovější verzi 8.0.0.
  4. Vyberte volbu Instalovat.
  5. Pokud se zobrazí dialogové okno Náhled změn, vyberte Použít.
  6. V dialogovém okně Přijetí licence vyberte Přijmout. @

Vytvoření obchodu s košíky MongoDB

Mikroslužba košíku používá HostingExtensions ke správě úložiště dat Redis. Nahraďte úložiště dat Redis úložištěm dat MongoDB.

  1. V Průzkumník řešení rozbalte projekt Basket.API, pak složku Storage a pak vyberte soubor RedisBasketStore.cs.

    Existují dvě asynchronní metody, GetBasketAsync které UpdateBasketAsyncpoužívají mezipaměť Redis. Umožňuje vytvářet verze MongoDB těchto metod.

  2. V Průzkumník řešení klikněte pravým tlačítkem myši na složku Úložiště a pak vyberte Přidat>třídu.

  3. V dialogovém okně Přidat novou položku pojmenujte soubor MongoBasketStore.cs a pak vyberte Přidat.

  4. Nahraďte kód v souboru MongoBasketStore.cs následujícím kódem:

    using eShop.Basket.API.Models;
using MongoDB.Driver;
using MongoDB.Driver.Linq;

namespace eShop.Basket.API.Storage;

public class MongoBasketStore
{
  private readonly IMongoCollection<CustomerBasket> _basketCollection;

  public MongoBasketStore(IMongoClient mongoClient)
  {
    // The database name needs to match the created database in the AppHost
    _basketCollection = mongoClient.GetDatabase("BasketDB").GetCollection<CustomerBasket>("basketitems");
  }

  public async Task<CustomerBasket?> GetBasketAsync(string customerId)
  {
    var filter = Builders<CustomerBasket>.Filter.Eq(r => r.BuyerId, customerId);

    return await _basketCollection.Find(filter).FirstOrDefaultAsync();
  }

  public async Task<CustomerBasket?> UpdateBasketAsync(CustomerBasket basket)
  {
    var filter = Builders<CustomerBasket>.Filter.Eq(r => r.BuyerId, basket.BuyerId);

    var result = await _basketCollection.ReplaceOneAsync(filter, basket, new ReplaceOptions { IsUpsert = true });

    return result.IsModifiedCountAvailable ? basket : null;
  }
}

    Předchozí kód vytvoří MongoBasketStore třídu, která funguje s modelem CustomerBasket . Kolekce zpracovává operace CRUD pro zákazníky nákupní košíky v databázi MongoDB.

  5. V Průzkumník řešení rozbalte rozšíření Basket.API>a pak vyberte soubor HostingExtensions.cs.

  6. Nahraďte kód Redis:

    builder.AddRedis("BasketStore");

builder.Services.AddSingleton<RedisBasketStore>();

    S kódem MongoDB:

    builder.AddMongoDBClient("BasketDB");

builder.Services.AddSingleton<MongoBasketStore>();

  7. V Průzkumník řešení rozbalte složku Grpc a pak otevřete soubor BasketService.cs.

  8. Změňte třídu tak, aby přijímala položku MongoBasketStore, nahraďte:

    public class BasketService(RedisBasketStore basketStore) : Basket.BasketBase

    Tímto:

    public class BasketService(MongoBasketStore basketStore) : Basket.BasketBase

Přidání databáze MongoDB do AppHostu

  1. V Průzkumník řešení klikněte pravým tlačítkem na projekt eShop.AppHost a vyberte Balíček Add.NET> Aspire.

  2. Do vyhledávacího pole na konci zadejte MongoDB a stiskněte Enter.

  3. Vyberte balíček Aspire.Hosting.MongoDB a pak vyberte nejnovější verzi 8.0.0.

  4. Vyberte volbu Instalovat.

  5. Pokud se zobrazí dialogové okno Náhled změn, vyberte Použít.

  6. V dialogovém okně Přijetí licence vyberte Přijmout. @

  7. V Průzkumník řešení rozbalte projekt eShop.AppHost a otevřete Program.cs soubor.

  8. V části Databáze přidejte komponentu MongoDB:

    var mongo = builder.AddMongoDB("mongo")
  .WithMongoExpress()
  .AddDatabase("BasketDB");

    Předchozí kód vytvoří kontejner databáze MongoDB a přidá databázi s názvem BasketDB. Kód také vytvoří kontejner pro nástroj Mongo Express, který umožňuje spravovat databázi MongoDB.

  9. Odstraňte kontejner Redis:

    var basketStore = builder.AddRedis("BasketStore").WithRedisCommander();

    Kód by teď měl vypadat takto:

    // Databases

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

var mongo = builder.AddMongoDB("mongo")
    .WithMongoExpress()
    .AddDatabase("BasketDB");

  10. Projekt Basket.API potřebuje odkaz na novou databázi MongoDB a měli byste odebrat odkaz Redis:

    var basketApi = builder.AddProject<Projects.Basket_API>("basket-api")
        .WithReference(mongo)
        .WithReference(idp);

Projekt Basket.API je teď připravený k použití databáze MongoDB. Pojďme aplikaci otestovat a zjistit, jestli funguje.

Otestování aplikace

  1. Zkompilujte a spusťte aplikaci, stiskněte klávesu F5 nebo vyberte > Spustit ladění.

    Snímek obrazovky řídicího panelu .NET Aspire se zvýrazněnými kontejnery MongoDB

    Na řídicím panelu můžete vidět nové kontejnery MongoDB, jeden pro databázový server druhý pro Mongo Express. K dispozici je také nový prostředek MongoDBDatabase , který hostuje databázi BasketDB .

  2. Vyberte koncový bod webové aplikace.

  3. Pokud se chcete přihlásit pomocí přihlašovacích údajů testovacího uživatele, vyberte ikonu uživatele v pravém horním rohu. E-mail je test@example.com a heslo je P@$$w 0rd1.

  4. Na domovské stránce vyberte Adventurer GPS Watch.

  5. Vyberte Přidat do nákupní tašky, měla by se zobrazit výjimka:

    Snímek obrazovky znázorňující výjimka RpcException

Ladění aplikace

Aplikace vyvolá výjimku při pokusu o přidání položky do nákupního košíku. K ladění problému můžete použít řídicí panel.

  1. V prohlížeči vyberte kartu řídicího panelu prostředků eShopu.

    Snímek obrazovky řídicího panelu, chyby v rozhraní Basket.API a webové aplikaci jsou zvýrazněné.

    Řídicí panel zobrazuje chyby v rozhraní basket-api a webové aplikaci. Projděte si protokoly pro rozhraní basket-api.

  2. V případě prostředku basket-api ve sloupci Protokoly vyberte Zobrazit.

    Snímek obrazovky s protokoly pro službu basket-api

    Existuje výjimka:

    System.FormatException: Element '_id' does not match any field or property of class eShop.Basket.API.Models.CustomerBasket.

  3. Vyberte položku nabídky Prostředky a pak vyberte koncový bod mongo-mongoexpress.

  4. V části Databáze vedle položky BasketDB vyberte Zobrazit.

  5. V kolekcích vedle košíkitems vyberte Zobrazit.

    Snímek obrazovky Mongo Expressu zobrazující data uložená v kolekci basketitems

    Dokumenty uložené v MongoDB mají pole _id . Každý dokument uložený v kolekci MongoDB musí mít jedinečné pole _id .

  6. Ladění zastavíte stisknutím kláves Shift+F5 nebo vyberete Ladění > zastavit ladění.

Zkontrolujte kód a opravte problém.

Pojďme se podívat na CustomerBasket a zjistit, jestli můžeme problém najít.

  1. V Průzkumník řešení rozbalte složku Basket.API>Models a pak otevřete soubor CustomerBasket.cs.

    public class CustomerBasket
{
    public required string BuyerId { get; set; }

    public List<BasketItem> Items { get; set; } = [];
}

    Model CustomerBasket nemá pole ani vlastnost, které odpovídají poli _id . Entity Framework se pokouší mapovat pole _id na model CustomerBasket a nemůže najít shodu.

  2. Aktualizujte CustomerBasket model tak, aby zahrnoval pole _id :

    public class CustomerBasket
{
    /// <summary>
    /// MongoDB document identifier
    /// </summary>
    public string _id { get; set; } = "";

    public required string BuyerId { get; set; }

    public List<BasketItem> Items { get; set; } = [];
}

Otestování opravené aplikace

  1. Pokud chcete aplikaci zkompilovat a spustit, stiskněte klávesu F5 nebo vyberte > Spustit ladění.

  2. U webové aplikace klikněte ve sloupci Koncové body pravým tlačítkem myši na adresu URL a pak vyberte Otevřít odkaz v okně InPrivate.

    Použití okna InPrivate zajišťuje, že prohlížeč k ověřování nepoužívá předchozí soubor cookie relace.

  3. Pokud se chcete přihlásit pomocí přihlašovacích údajů testovacího uživatele, vyberte ikonu uživatele v pravém horním rohu. E-mail je test@example.com a heslo je P@$$w 0rd1.

  4. Na domovské stránce vyberte Adventurer GPS Watch.

  5. Vyberte Přidat do nákupní tašky.

    Snímek obrazovky s pracovním nákupním košíkem eShopu

    Funkce košíku v severních horách teď funguje.

Databázi SQLite jste úspěšně nahradili databází PostgreSQL a mezipamětí Redis databází MongoDB. Použili jste .NET Aspire ke správě databází a prozkoumání dat v nich a pomocí řídicího panelu jste pomohli ladit problém s aplikací.