Oktatóanyag: ASP.NET webalkalmazás fejlesztése a NoSQL-hez készült Azure Cosmos DB-vel

Cikk
04/10/2024

A KÖVETKEZŐRE VONATKOZIK: NoSQL

A .NET-hez készült Azure SDK lehetővé teszi az adatok lekérdezését egy API for NoSQL-tárolóban a LINQ in C# vagy egy SQL-lekérdezési sztring használatával. Ez az oktatóanyag végigvezeti egy olyan meglévő ASP.NET webalkalmazás frissítésének folyamatán, amely helyőrző adatokat használ az API-ból való lekérdezéshez.

Ebben az oktatóanyagban az alábbiakkal fog megismerkedni:

Adatbázis és tároló létrehozása és feltöltése a NoSQL API használatával
ASP.NET webalkalmazás létrehozása sablonból
Adatok lekérdezése a NoSQL-tároló API-jából az Azure SDK for .NET használatával

Előfeltételek

Egy meglévő Azure Cosmos DB for NoSQL-fiók.
- Ha már rendelkezik Azure-előfizetéssel, hozzon létre egy új fiókot.
- Nincs Azure-előfizetés? Ingyenesen kipróbálhatja az Azure Cosmos DB-t hitelkártya nélkül.
Visual Studio Code
.NET 6 (LTS) vagy újabb
C#-alkalmazások írásának tapasztalata.

API létrehozása NoSQL-erőforrásokhoz

Először egy adatbázist és egy tárolót fog létrehozni a noSQL-fiókhoz készült meglévő API-ban. Ezt a fiókot ezután a dotnet eszközzel tölti fel adatokkal cosmicworks .

Nyissa meg a meglévő API for NoSQL-fiókját az Azure Portalon.
Az erőforrás menüjében válassza a Kulcsok lehetőséget.
A Kulcsok lapon figyelje meg és rögzítse az ELSŐDLEGES KAPCSOLATI SZTRING* mező értékét. Ez az érték az oktatóanyag során lesz felhasználva.
Az erőforrásmenüben válassza az Adatkezelő lehetőséget.
Az Adatkezelő lapon válassza az Új tároló lehetőséget a parancssávon.

Az Új tároló párbeszédpanelen hozzon létre egy új tárolót a következő beállításokkal:

Beállítás	Érték
Adatbázis azonosítója	`cosmicworks`
Adatbázis átviteli sebességének típusa	Kézi
Adatbázis átviteli sebességének mennyisége	`1000`
Tároló azonosítója	`products`
Partíciókulcs	`/category/name`

Képernyőkép az Adatkezelő Új tároló párbeszédpaneléről különböző értékekkel az egyes mezőkben.

Fontos

Ebben az oktatóanyagban először 1000 RU/s-ra skálázzuk az adatbázist megosztott átviteli sebességre az adatmigrálás teljesítményének maximalizálása érdekében. Az adatmigrálás befejezése után 400 RU/s kiosztott átviteli sebességre skálázunk le.

Kattintson az OK gombra az adatbázis és a tároló létrehozásához.
Nyisson meg egy terminált a tároló adatokkal való feltöltéséhez parancsok futtatásához.

Tipp.

Itt opcionálisan használhatja az Azure Cloud Shellt.
Telepítse a dotnet eszköz 2 . verzióját a cosmicworks NuGetből.
```
dotnet tool install --global cosmicworks  --version 2.*
```
Az eszközzel feltöltheti a cosmicworks NoSQL-fiók API-ját mintatermék-adatokkal a laborban korábban rögzített URI - és ELSŐDLEGESKULCS-értékekkel . Ezeket a rögzített értékeket a rendszer a paraméterekhez és key a endpoint paraméterekhez használja.
```
cosmicworks \
    --number-of-products 1759 \
    --number-of-employees 0 \
    --disable-hierarchical-partition-keys \
    --connection-string <nosql-connection-string>
```

Figyelje meg a parancssori eszköz kimenetét. 1759 elemet kell hozzáadnia a tárolóhoz. A példakimenet a rövidség kedvéért csonkolt.

── Parsing connection string ────────────────────────────────────────────────────────────────
╭─Connection string──────────────────────────────────────────────────────────────────────────╮
│ AccountEndpoint=https://<account-name>.documents.azure.com:443/;AccountKey=<account-key>;  │
╰────────────────────────────────────────────────────────────────────────────────────────────╯
── Populating data ──────────────────────────────────────────────────────────────────────────
╭─Products configuration─────────────────────────────────────────────────────────────────────╮
│ Database   cosmicworks                                                                     │
│ Container  products                                                                        │
│ Count      1,759                                                                           │
╰────────────────────────────────────────────────────────────────────────────────────────────╯
...
[SEED]  00000000-0000-0000-0000-000000005951 | Road-650 Black, 60 - Bikes
[SEED]  00000000-0000-0000-0000-000000005950 | Mountain-100 Silver, 42 - Bikes
[SEED]  00000000-0000-0000-0000-000000005949 | Men's Bib-Shorts, L - Clothing
[SEED]  00000000-0000-0000-0000-000000005948 | ML Mountain Front Wheel - Components
[SEED]  00000000-0000-0000-0000-000000005947 | Mountain-500 Silver, 42 - Bikes

Térjen vissza a fiókjához tartozó Adatkezelő lapra.
Az Adatok szakaszban bontsa ki az cosmicworks adatbázis csomópontot, majd válassza a Méretezés lehetőséget.
Csökkentse az átviteli sebességet 1000-ről 400-ra.
A parancssávon válassza a Mentés lehetőséget.
Az Adatok szakaszban bontsa ki és válassza ki a termékek tárolócsomópontot.
A parancssávon válassza az Új SQL-lekérdezés lehetőséget.

A lekérdezésszerkesztőben adja hozzá ezt az SQL-lekérdezési sztringet.

SELECT
  p.sku,
  p.price
FROM products p
WHERE p.price < 2000
ORDER BY p.price DESC

Válassza a Lekérdezés végrehajtása lehetőséget a lekérdezés futtatásához és az eredmények megfigyeléséhez.
Az eredményeknek a tároló összes elemének lapszámozott tömbjének kell lenniükprice, amelynek értéke 2000-nél kisebb a legmagasabb ártól a legalacsonyabbig. A rövidség kedvéért a kimenet egy részhalmaza szerepel itt.
```
[
  {
    "sku": "BK-R79Y-48",
    "price": 1700.99
  },
  ...
  {
    "sku": "FR-M94B-46",
    "price": 1349.6
  },
...
```

Cserélje le a lekérdezésszerkesztő tartalmát erre a lekérdezésre, majd válassza ismét a Lekérdezés végrehajtása lehetőséget az eredmények megfigyeléséhez.

SELECT
    p.name,
    p.category.name AS category,
    p.category.subCategory.name AS subcategory,
    p.tags
FROM products p
JOIN tag IN p.tags
WHERE STRINGEQUALS(tag, "yellow", true)

Az eredményeknek kisebb elemekből álló tömbnek kell lenniük, hogy csak olyan elemeket tartalmazzanak, amelyek legalább egy címkét tartalmaznak, és a név értéke Tag-32. A rövidség kedvéért itt is a kimenet egy részhalmaza szerepel.
```
[
  ...
  {
    "name": "HL Touring Frame - Yellow, 60",
    "category": "Components",
    "subcategory": "Touring Frames",
    "tags": [
      "Components",
      "Touring Frames",
      "Yellow",
      "60"
    ]
  },
  ...
]
```

ASP.NET webalkalmazás létrehozása

Most egy új ASP.NET-webalkalmazást fog létrehozni egy mintaprojektsablon használatával. Ezután megismerheti a forráskódot, és futtathatja a mintát, hogy megismerkedjen az alkalmazással, mielőtt azure Cosmos DB-kapcsolatot adna hozzá a .NET-hez készült Azure SDK-val.

Fontos

Ez az oktatóanyag transzparens módon lekéri a csomagokat a NuGetből. dotnet nuget list source A csomagforrásokat ellenőrizheti. Ha nincs NuGet csomagforrásként, használja dotnet nuget add source a webhely forrásként való telepítését.

Nyisson meg egy terminált egy üres könyvtárban.
Telepítse a cosmicworks.template.web projektsablon-csomagot a NuGetből.
```
dotnet new install cosmicworks.template.web
```
Hozzon létre egy új webalkalmazás-projektet az újonnan telepített dotnet new cosmosdbnosql-webapp sablonnal.
```
dotnet new cosmosdbnosql-webapp
```
Hozza létre és futtassa a webalkalmazás-projektet.
```
dotnet run
```

Figyelje meg a futtatási parancs kimenetét. A kimenetnek tartalmaznia kell azon portok és URL-címek listáját, amelyeken az alkalmazás fut.

...
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:5000
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:5001
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Production
...

Nyisson meg egy új böngészőt, és keresse meg a futó webalkalmazást. Figyelje meg a futó alkalmazás mindhárom oldalát.
Állítsa le a futó alkalmazást a futó folyamat leállításával.

Tipp.

A Ctrl+C paranccsal állítsa le a futó folyamatot. Másik lehetőségként bezárhatja és újra megnyithatja a terminált.
Nyissa meg a Visual Studio Code-ot az aktuális projektmappával munkaterületként.

Tipp.

A terminálon futtatva code . megnyithatja a Visual Studio Code-ot, és automatikusan megnyithatja a munkakönyvtárat aktuális munkaterületként.

Nyissa meg és nyissa meg a Services/ICosmosService.cs fájlt. Figyelje meg az alapértelmezett és az RetrieveActiveProductsAsyncRetrieveAllProductsAsync alapértelmezett metódus implementációit. Ezek a metódusok a projekt első futtatásakor használandó termékek statikus listáját hozzák létre. Itt található egy csonkolt példa az egyik módszerre.

public async Task<IEnumerable<Product>> RetrieveActiveProductsAsync()
{
    await Task.Delay(1);

    return new List<Product>()
    {
        new Product(id: "baaa4d2d-5ebe-45fb-9a5c-d06876f408e0", category: new Category(name: "Components, Road Frames"), sku: "FR-R72R-60", name: """ML Road Frame - Red, 60""", description: """The product called "ML Road Frame - Red, 60".""", price: 594.83000000000004m),
        new Product(id: "bd43543e-024c-4cda-a852-e29202310214", category: new Category(name: "Components, Forks"), sku: "FK-5136", name: """ML Fork""", description: """The product called "ML Fork".""", price: 175.49000000000001m),
        ...
    };
}

Nyissa meg és nyissa meg a Services/CosmosService.cs fájlt. Figyelje meg a CosmosService osztály aktuális implementációját. Ez az osztály implementálja az ICosmosService felületet, de nem bírál felül metódusokat. Ebben az összefüggésben az osztály az alapértelmezett felületi implementációt fogja használni, amíg felül nem bírálja a megvalósítást a felületen.
```
public class CosmosService : ICosmosService
{ }
```
Végül nyissa meg és nyissa meg a Models/Product.cs és Models/Category.cs fájlokat. Figyelje meg az egyes fájlokban definiált rekordtípusokat. Az oktatóanyag során ezeket a típusokat fogja használni a lekérdezésekben.
```
public record Product(
    string id,
    Category category,
    string sku,
    string name,
    string description,
    decimal price
);
```
```
public record Category(
    string name
);
```

Adatok lekérdezése a .NET SDK használatával

Ezután hozzáadja a .NET-hez készült Azure SDK-t ehhez a mintaprojekthez, és a kódtár használatával lekérdezi az adatokat a NoSQL-tároló API-jából.

A terminálban adja hozzá a csomagot a Microsoft.Azure.Cosmos NuGetből.
```
dotnet add package Microsoft.Azure.Cosmos
```
Készítse el a projektet.
```
dotnet build
```
A Visual Studio Code-ban lépjen újra a Services/CosmosService.cs fájlra.
Adjon hozzá egy új, a névterekre és Microsoft.Azure.Cosmos.Linq névterekre Microsoft.Azure.Cosmos vonatkozó irányelveket.
```
using Microsoft.Azure.Cosmos;
using Microsoft.Azure.Cosmos.Linq;
```
A CosmosService osztályban adjon hozzá egy újprivate readonly, névvel ellátott tagot CosmosClient_client.
```
private readonly CosmosClient _client;
```
Hozzon létre egy új üres konstruktort az CosmosService osztályhoz.
```
public CosmosService()
{ }
```
A konstruktoron belül hozzon létre egy új osztálypéldányt CosmosClient , amely egy sztringparaméterben halad át a laborban korábban rögzített ELSŐDLEGES KAPCSOLATI SZTRING értékkel. Tárolja ezt az új példányt a _client tagban.
```
public CosmosService()
{ 
    _client = new CosmosClient(
        connectionString: "<primary-connection-string>"
    );
}
```
A CosmosService osztályban hozzon létre egy újprivate, névvel ellátott containertulajdonságotContainer. Állítsa be a get kiegészítőt az adatbázis és products a cosmicworks tároló visszaadásához.
```
private Container container
{
    get => _client.GetDatabase("cosmicworks").GetContainer("products");
}
```
Hozzon létre egy új aszinkron metódust, RetrieveAllProductsAsync amely egy IEnumerable<Product>.
```
public async Task<IEnumerable<Product>> RetrieveAllProductsAsync()
{ }
```
A következő lépésekhez adja hozzá ezt a kódot a metódushoz RetrieveAllProductsAsync .
1. GetItemLinqQueryable<> Az általános metódussal lekérhet egy olyan típusú IQueryable<> objektumot, amellyel nyelvvel integrált lekérdezést (LINQ) hozhat létre. Tárolja az objektumot egy névvel ellátott queryableváltozóban.
```
var queryable = container.GetItemLinqQueryable<Product>();
```
2. LINQ-lekérdezés létrehozása a Where bővítménymetelyekkel OrderByDescending . ToFeedIterator A bővítménymetódussal iterátort hozhat létre az Adatok Lekérése az Azure Cosmos DB-ből, és az iterátort egy nevesített feedváltozóban tárolja. Az iterátor későbbi elidegenítéséhez csomagolja be ezt a teljes kifejezést egy használandó utasításba.
```
using FeedIterator<Product> feed = queryable
    .Where(p => p.price < 2000m)
    .OrderByDescending(p => p.price)
    .ToFeedIterator();
```
3. Hozzon létre egy új változót results az általános List<> típus használatával.
```
List<Product> results = new();
```
4. Hozzon létre egy időhurkot , amely addig iterál, amíg a HasMoreResultsfeed változó tulajdonsága hamis értéket nem ad vissza. Ez a hurok biztosítja, hogy végighaladhasson a kiszolgálóoldali eredmények összes lapján.
```
while (feed.HasMoreResults)
{ }
```
5. A cikluson belül aszinkron módon hívja meg a ReadNextAsync változó metódusátfeed, és tárolja az eredményt egy nevesített responseváltozóban.
```
while (feed.HasMoreResults)
{
    var response = await feed.ReadNextAsync();
}
```
6. A cikluson belül is használjon foreach hurkot a válasz egyes elemeinek végigfuttatásához és a results listához való hozzáadásához.
```
while (feed.HasMoreResults)
{
    var response = await feed.ReadNextAsync();
    foreach (Product item in response)
    {
        results.Add(item);
    }
}
```
7. Adja vissza a results listát a metódus kimeneteként RetrieveAllProductsAsync .
```
return results;
```
Hozzon létre egy új aszinkron metódust, RetrieveActiveProductsAsync amely egy IEnumerable<Product>.
```
public async Task<IEnumerable<Product>> RetrieveActiveProductsAsync()
{ }
```
A következő lépésekhez adja hozzá ezt a kódot a metódushoz RetrieveActiveProductsAsync .
1. Hozzon létre egy SQL-lekérdezéssel elnevezett sql új sztringet, amely több olyan mezőt kér le, amelyben szűrő (@tagFilter) van alkalmazva az egyes elemek címketömbjeire.
```
string sql = """
SELECT
    p.id,
    p.name,
    p.category,
    p.sku,
    p.description,
    p.price
FROM products p
JOIN tag IN p.tags
WHERE STRINGEQUALS(tag, @tagFilter, true)
""";
```
2. Hozzon létre egy új QueryDefinition változót, amely query a sztringben lesz az sql egyetlen lekérdezési paraméter. Emellett használja a WithParameter folyadékmetódust az érték red paraméterre való alkalmazásához @tagFilter .
```
var query = new QueryDefinition(
    query: sql
)
    .WithParameter("@tagFilter", "red");
```
3. GetItemQueryIterator<> Az általános módszer és a query változó használatával hozzon létre egy iterátort, amely adatokat kap az Azure Cosmos DB-ből. Tárolja az iterátort egy nevesített feedváltozóban. Az iterátor későbbi elidegenítéséhez csomagolja be ezt a teljes kifejezést egy használandó utasításba.
```
using FeedIterator<Product> feed = container.GetItemQueryIterator<Product>(
    queryDefinition: query
);
```
4. Használjon egy kis ciklust több oldalnyi eredmény iterálásához, és tárolja az értéket egy általános List<> elnevezett eredményben. Adja vissza az eredményeket a metódus kimeneteként RetrieveActiveProductsAsync .
```
List<Product> results = new();

while (feed.HasMoreResults)
{
    FeedResponse<Product> response = await feed.ReadNextAsync();
    foreach (Product item in response)
    {
        results.Add(item);
    }
}

return results;
```
Mentse a Services/CosmosClient.cs fájlt.

Tipp.

Ha nem biztos abban, hogy a kód helyes, ellenőrizheti a forráskódot a GitHubon található mintakódon .

A végleges alkalmazás ellenőrzése

Végül az alkalmazást úgy fogja futtatni, hogy engedélyezve van a gyakori elérésű újratöltés . Az alkalmazás futtatása ellenőrzi, hogy a kód hozzáfér-e a NoSQL API-ból származó adatokhoz.

Futtassa az alkalmazást a terminálban.
```
dotnet run
```
A futtatási parancs kimenetének tartalmaznia kell azon portok és URL-címek listáját, amelyeken az alkalmazás fut. Nyisson meg egy új böngészőt, és keresse meg a futó webalkalmazást. Figyelje meg a futó alkalmazás mindhárom oldalát. Minden oldalnak tartalmaznia kell az Azure Cosmos DB-ből származó élő adatokat.

Az erőforrások eltávolítása

Ha már nincs rá szükség, törölje az oktatóanyagban használt adatbázist. Ehhez lépjen a fiók lapjára, válassza az Adatkezelőt, jelölje ki az adatbázist, majd válassza a cosmicworks Törlés lehetőséget.

Következő lépések

Most, hogy létrehozta az első .NET-webalkalmazást az Azure Cosmos DB használatával, mélyebben megismerkedhet az SDK-val, hogy további adatokat importáljon, összetett lekérdezéseket hajthat végre, és kezelheti a NoSQL-erőforrásokhoz készült Azure Cosmos DB-t.

Az Azure Cosmos DB for NoSQL és a .NET használatának első lépései