Esercitazione: Sviluppare un'applicazione Web ASP.NET con Azure Cosmos DB per NoSQL

SI APPLICA A: NoSQL

Azure SDK per .NET consente di eseguire query sui dati in un contenitore API per NoSQL usando LINQ in C# o una stringa di query SQL. Questa esercitazione descrive il processo di aggiornamento di un'applicazione Web ASP.NET esistente che usa i dati segnaposto per eseguire query dall'API.

In questa esercitazione verranno illustrate le procedure per:

  • Creare e popolare un database e un contenitore usando l'API per NoSQL
  • Creare un'applicazione Web ASP.NET da un modello
  • Eseguire query sui dati dal contenitore API per NoSQL usando Azure SDK per .NET

Prerequisiti

Creare l'API per le risorse NoSQL

Prima di tutto, si creerà un database e un contenitore nell'API esistente per l'account NoSQL. Verrà quindi popolato questo account con i dati usando lo cosmicworks strumento dotnet.

  1. Passare all'API esistente per l'account NoSQL nella portale di Azure.

  2. Nel menu risorsa selezionare Chiavi.

    Screenshot di una pagina dell'api per l'account NoSQL. L'opzione Chiavi è evidenziata nel menu della risorsa.

  3. Nella pagina Chiavi osservare e registrare il valore dei campi URI, PRIMARY KEY e PRIMARY CONNECTION STRING* . Questi valori verranno usati durante l'esercitazione.

    Screenshot della pagina Chiavi con i campi URI, Chiave primaria e Stringa di connessione primaria evidenziati.

  4. Nel menu della risorsa selezionare Esplora dati.

    Screenshot dell'opzione Esplora dati evidenziata nel menu della risorsa.

  5. Nella pagina Esplora dati selezionare l'opzione Nuovo contenitore nella barra dei comandi.

    Screenshot dell'opzione Nuovo contenitore nella barra dei comandi Esplora dati.

  6. Nella finestra di dialogo Nuovo contenitore creare un nuovo contenitore con le impostazioni seguenti:

    Impostazione Valore
    ID database cosmicworks
    Tipo di velocità effettiva del database Manuale
    Quantità di velocità effettiva del database 4000
    ID contenitore products
    Chiave di partizione /categoryId

    Screenshot della finestra di dialogo Nuovo contenitore nella Esplora dati con vari valori in ogni campo.

    Importante

    In questa esercitazione verrà prima ridimensionato il database fino a 4.000 UR/s in velocità effettiva condivisa per ottimizzare le prestazioni per la migrazione dei dati. Al termine della migrazione dei dati, la velocità effettiva di provisioning verrà ridotta a 400 UR/s.

  7. Selezionare OK per creare il database e il contenitore.

  8. Aprire un terminale per eseguire comandi per popolare il contenitore con i dati.

    Suggerimento

    Facoltativamente, è possibile usare il Cloud Shell di Azure qui.

  9. Installare una versione preliminaredello cosmicworks strumento dotnet da NuGet.

    dotnet tool install --global cosmicworks  --prerelease
    
  10. Usare lo strumento per popolare l'API cosmicworks per l'account NoSQL con dati di prodotto di esempio usando i valori URI e PRIMARY KEY registrati in precedenza in questo lab. Tali valori registrati verranno usati rispettivamente per i endpoint parametri e key .

    cosmicworks \
        --datasets product \
        --endpoint <uri> \
        --key <primary-key>
    
  11. Osservare l'output dallo strumento della riga di comando. Deve aggiungere più di 200 elementi al contenitore. L'output di esempio incluso viene troncato per brevità.

    ...
    Revision:       v4
    Datasets:
            product
    
    Database:       [cosmicworks]   Status: Created
    Container:      [products]      Status: Ready
    
    product Items Count:    295
    Entity: [9363838B-2D13-48E8-986D-C9625BE5AB26]  Container:products      Status: RanToCompletion
    ...
    Container:      [product]       Status: Populated
    
  12. Tornare alla pagina Esplora dati per l'account.

  13. Nella sezione Dati espandere il nodo del cosmicworks database e quindi selezionare Ridimensiona.

    Screenshot dell'opzione Ridimensiona all'interno del nodo del database.

  14. Ridurre la velocità effettiva da 4.000 a 400.

    Screenshot delle impostazioni di velocità effettiva per il database ridotto a 400 UR/s.

  15. Sulla barra dei comandi selezionare Salva.

    Screenshot dell'opzione Salva nella barra dei comandi Esplora dati.

  16. Nella sezione Dati espandere e selezionare il nodo contenitore prodotti .

    Screenshot del nodo contenitore espanso all'interno del nodo del database.

  17. Nella barra dei comandi selezionare Nuova query SQL.

    Screenshot dell'opzione Nuova query SQL nella barra dei comandi Esplora dati.

  18. Nell'editor di query aggiungere questa stringa di query SQL.

    SELECT
      p.sku,
      p.price
    FROM products p
    WHERE p.price < 2000
    ORDER BY p.price DESC
    
  19. Selezionare Esegui query per eseguire la query e osservare i risultati.

    Screenshot dell'opzione Esegui query nella barra dei comandi Esplora dati.

  20. I risultati devono essere una matrice impaginata di tutti gli elementi nel contenitore con un price valore minore di 2.000 ordinati dal prezzo più alto al minimo. Per brevità, qui è incluso un subset dell'output.

    [
      {
        "sku": "BK-R79Y-48",
        "price": 1700.99
      },
      ...
      {
        "sku": "FR-M94B-46",
        "price": 1349.6
      },
    ...
    
  21. Sostituire il contenuto dell'editor di query con questa query e quindi selezionare Esegui query di nuovo per osservare i risultati.

    SELECT
      p.name,
      p.categoryName,
      p.tags
    FROM products p
    JOIN t IN p.tags
    WHERE t.name = "Tag-32"
    
  22. I risultati devono essere una matrice più piccola di elementi filtrati per contenere solo elementi che includono almeno un tag con un valore del nome di Tag-32. Di nuovo, un subset dell'output è incluso qui per brevità.

    ...
    {
    "name": "ML Mountain Frame - Black, 44",
    "categoryName": "Components, Mountain Frames",
    "tags": [
        {
        "id": "18AC309F-F81C-4234-A752-5DDD2BEAEE83",
        "name": "Tag-32"
        }
    ]
    },
    ...
    

Creare un'applicazione Web ASP.NET

A questo punto, si creerà una nuova applicazione Web ASP.NET usando un modello di progetto di esempio. Si esaminerà quindi il codice sorgente ed eseguirà l'esempio per acquisire familiarità con l'applicazione prima di aggiungere la connettività di Azure Cosmos DB usando Azure SDK per .NET.

Importante

Questa esercitazione esegue il pull trasparente dei pacchetti da NuGet. È possibile usare dotnet nuget list source per verificare le origini del pacchetto. Se Non si dispone di NuGet come origine del pacchetto, usare dotnet nuget add source per installare il sito come origine.

  1. Aprire un terminale in una directory vuota.

  2. Installare il pacchetto del modello di cosmicworks.template.web progetto da NuGet.

    dotnet new install cosmicworks.template.web
    
  3. Creare un nuovo progetto di applicazione Web usando il modello appena installato dotnet new cosmosdbnosql-webapp .

    dotnet new cosmosdbnosql-webapp
    
  4. Compilare ed eseguire il progetto dell'applicazione Web.

    dotnet run
    
  5. Osservare l'output del comando di esecuzione. L'output deve includere un elenco di porte e URL in cui è in esecuzione l'applicazione.

    ...
    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
    ...
    
  6. Aprire un nuovo browser e passare all'applicazione Web in esecuzione. Osservare tutte e tre le pagine dell'applicazione in esecuzione.

    Screenshot dell'applicazione Web di esempio in esecuzione con i dati segnaposto.

  7. Arrestare l'applicazione in esecuzione terminando il processo in esecuzione.

    Suggerimento

    Usare il comando CTRL+C per arrestare un processo in esecuzione. In alternativa, è possibile chiudere e riaprire il terminale.

  8. Aprire Visual Studio Code usando la cartella di progetto corrente come area di lavoro.

    Suggerimento

    È possibile eseguire code . nel terminale per aprire Visual Studio Code e aprire automaticamente la directory di lavoro come area di lavoro corrente.

  9. Passare a e aprire il file Services/ICosmosService.cs . Osservare le RetrieveActiveProductsAsync implementazioni del metodo e RetrieveAllProductsAsync predefinite. Questi metodi creano un elenco statico di prodotti da usare durante l'esecuzione del progetto per la prima volta. Qui viene fornito un esempio troncato di uno dei metodi.

    public async Task<IEnumerable<Product>> RetrieveActiveProductsAsync()
    {
        await Task.Delay(1);
    
        return new List<Product>()
        {
            new Product(id: "baaa4d2d-5ebe-45fb-9a5c-d06876f408e0", categoryId: "3E4CEACD-D007-46EB-82D7-31F6141752B2", categoryName: "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: "d5928182-0307-4bf9-8624-316b9720c58c", categoryId: "AA5A82D4-914C-4132-8C08-E7B75DCE3428", categoryName: "Components, Cranksets", sku: "CS-6583", name: """ML Crankset""", description: """The product called "ML Crankset".""", price: 256.49000000000001m)
        };
    }
    
  10. Passare a e aprire il file Services/CosmosService.cs . Osservare l'implementazione corrente della classe CosmosService . Questa classe implementa l'interfaccia ICosmosService , ma non esegue l'override di alcun metodo. In questo contesto, la classe userà l'implementazione predefinita dell'interfaccia fino a quando non viene fornito un override dell'implementazione nell'interfaccia.

    public class CosmosService : ICosmosService
    { }
    
  11. Infine, passare a e aprire il file Models/Product.cs . Osservare il tipo di record definito in questo file. Questo tipo verrà usato nelle query in questa esercitazione.

    public record Product(
        string id,
        string categoryId,
        string categoryName,
        string sku,
        string name,
        string description,
        decimal price
    );
    

Eseguire query sui dati usando .NET SDK

Si aggiungerà quindi Azure SDK per .NET a questo progetto di esempio e si userà la libreria per eseguire query sui dati dal contenitore API per NoSQL.

  1. Tornare al terminale, aggiungere il Microsoft.Azure.Cosmos pacchetto da NuGet.

    dotnet add package Microsoft.Azure.Cosmos
    
  2. Compilare il progetto.

    dotnet build
    
  3. Tornare a Visual Studio Code, passare di nuovo al file Services/CosmosService.cs .

  4. Aggiungere una nuova direttiva using per gli Microsoft.Azure.Cosmos spazi dei nomi e Microsoft.Azure.Cosmos.Linq .

    using Microsoft.Azure.Cosmos;
    using Microsoft.Azure.Cosmos.Linq;
    
  5. All'interno della classe CosmosService aggiungere un nuovo private readonly membro di tipo CosmosClient denominato _client.

    private readonly CosmosClient _client;
    
  6. Creare un nuovo costruttore vuoto per la CosmosService classe.

    public CosmosService()
    { }
    
  7. All'interno del costruttore creare una nuova istanza della CosmosClient classe passando un parametro stringa con il valore PRIMARY CONNECTION STRING registrato in precedenza nel lab. Archiviare questa nuova istanza nel _client membro.

    public CosmosService()
    { 
        _client = new CosmosClient(
            connectionString: "<primary-connection-string>"
        );
    }
    
  8. All'interno della classe CosmosService creare una nuova private proprietà di tipo Container denominata container. Impostare la funzione di accesso get per restituire il database e products il cosmicworks contenitore.

    private Container container
    {
        get => _client.GetDatabase("cosmicworks").GetContainer("products");
    }
    
  9. Creare un nuovo metodo asincrono denominato RetrieveAllProductsAsync che restituisce un IEnumerable<Product>oggetto .

    public async Task<IEnumerable<Product>> RetrieveAllProductsAsync()
    { }
    
  10. Per i passaggi successivi, aggiungere questo codice all'interno del RetrieveAllProductsAsync metodo.

    1. Usare il GetItemLinqQueryable<> metodo generico per ottenere un oggetto di tipo IQueryable<> che è possibile usare per costruire una query integrata nel linguaggio (LINQ). Archiviare l'oggetto in una variabile denominata queryable.

      var queryable = container.GetItemLinqQueryable<Product>();
      
    2. Creare una query LINQ usando i Where metodi di estensione e OrderByDescending . Usare il ToFeedIterator metodo di estensione per creare un iteratore per ottenere dati da Azure Cosmos DB e archiviare l'iteratore in una variabile denominata feed. Eseguire il wrapping di questa intera espressione in un'istruzione using per eliminare l'iteratore in un secondo momento.

      using FeedIterator<Product> feed = queryable
          .Where(p => p.price < 2000m)
          .OrderByDescending(p => p.price)
          .ToFeedIterator();
      
    3. Creare una nuova variabile denominata results usando il tipo generico List<> .

      List<Product> results = new();
      
    4. Creare un ciclo while che eseguirà l'iterazione feed fino a quando la HasMoreResults proprietà della variabile restituisce false. Questo ciclo garantisce il ciclo di tutte le pagine dei risultati lato server.

      while (feed.HasMoreResults)
      { }
      
    5. All'interno del feed ciclo while chiamare in modo asincrono il metodo della variabile e archiviare il ReadNextAsync risultato in una variabile denominata response.

      while (feed.HasMoreResults)
      {
          var response = await feed.ReadNextAsync();
      }
      
    6. Ancora all'interno del ciclo while , usare un ciclo foreach per passare ogni elemento nella risposta e aggiungerli all'elenco results .

      while (feed.HasMoreResults)
      {
          var response = await feed.ReadNextAsync();
          foreach (Product item in response)
          {
              results.Add(item);
          }
      }
      
    7. Restituisce l'elenco results come output del RetrieveAllProductsAsync metodo.

      return results;
      
  11. Creare un nuovo metodo asincrono denominato RetrieveActiveProductsAsync che restituisce un IEnumerable<Product>oggetto .

    public async Task<IEnumerable<Product>> RetrieveActiveProductsAsync()
    { }
    
  12. Per i passaggi successivi, aggiungere questo codice all'interno del RetrieveActiveProductsAsync metodo.

    1. Creare una nuova stringa denominata sql con una query SQL per recuperare più campi in cui viene applicato un filtro (@tagFilter) alla matrice di tag di ogni elemento.

      string sql = """
      SELECT
          p.id,
          p.categoryId,
          p.categoryName,
          p.sku,
          p.name,
          p.description,
          p.price,
          p.tags
      FROM products p
      JOIN t IN p.tags
      WHERE t.name = @tagFilter
      """;
      
    2. Creare una nuova QueryDefinition variabile denominata query passando la sql stringa come solo parametro di query. Usare anche il WithParameter metodo fluido per applicare il valore Tag-75 al @tagFilter parametro.

      var query = new QueryDefinition(
          query: sql
      )
          .WithParameter("@tagFilter", "Tag-75");
      
    3. Usare il metodo generico e la GetItemQueryIterator<>query variabile per creare un iteratore che ottiene dati da Azure Cosmos DB. Archiviare l'iteratore in una variabile denominata feed. Eseguire il wrapping di questa intera espressione in un'istruzione using per eliminare l'iteratore in un secondo momento.

      using FeedIterator<Product> feed = container.GetItemQueryIterator<Product>(
          queryDefinition: query
      );
      
    4. Usare un ciclo while per scorrere più pagine di risultati e archiviare il valore in un risultato denominato generico.List<> Restituisce i risultati come output del RetrieveActiveProductsAsync metodo.

      List<Product> results = new();
      
      while (feed.HasMoreResults)
      {
          FeedResponse<Product> response = await feed.ReadNextAsync();
          foreach (Product item in response)
          {
              results.Add(item);
          }
      }
      
      return results;
      
  13. Salvare il file Services/CosmosClient.cs .

    Suggerimento

    Se non si è certi che il codice sia corretto, è possibile controllare il codice sorgente rispetto al codice di esempio in GitHub.

Convalidare l'applicazione finale

Infine, si eseguirà l'applicazione con ricarica ad accesso frequente abilitato. L'esecuzione dell'applicazione convalida che il codice possa accedere ai dati dall'API per NoSQL.

  1. Tornare al terminale, eseguire l'applicazione.

    dotnet run
    
  2. L'output del comando di esecuzione deve includere un elenco di porte e URL in cui è in esecuzione l'applicazione. Aprire un nuovo browser e passare all'applicazione Web in esecuzione. Osservare tutte e tre le pagine dell'applicazione in esecuzione. Ogni pagina dovrebbe ora includere dati live da Azure Cosmos DB.

Pulire le risorse

Quando non è più necessario, eliminare il database usato in questa esercitazione. A tale scopo, passare alla pagina account, selezionare Esplora dati, selezionare il cosmicworks database e quindi selezionare Elimina.

Passaggi successivi

Dopo aver creato la prima applicazione Web .NET con Azure Cosmos DB, è ora possibile approfondire l'SDK per importare più dati, eseguire query complesse e gestire le risorse di Azure Cosmos DB per NoSQL.