Quickstart: Construa uma aplicação web .NET utilizando a API da Azure Cosmos para a MongoDBQuickstart: Build a .NET web app using Azure Cosmos DB's API for MongoDB

APLICA A: Azure Cosmos DB API para MongoDB

Azure Cosmos DB é a base de dados NoSQL rápida da Microsoft com APIs abertos para qualquer escala.Azure Cosmos DB is Microsoft’s fast NoSQL database with open APIs for any scale. Pode criar e consultar rapidamente documentos, bases de dados chave/valor e gráficos, que beneficiam da distribuição global e das capacidades de escala horizontal no núcleo da Cosmos DB.You can quickly create and query document, key/value and graph databases, all of which benefit from the global distribution and horizontal scale capabilities at the core of Cosmos DB.

Este quickstart demonstra como criar uma conta Cosmos com a API da Azure Cosmos para a MongoDB.This quickstart demonstrates how to create a Cosmos account with Azure Cosmos DB's API for MongoDB. Em seguida, você construirá e implementará uma aplicação web de lista de tarefas construída usando o controlador MongoDB .NET.You'll then build and deploy a tasks list web app built using the MongoDB .NET driver.

Pré-requisitos para executar a aplicação de exemploPrerequisites to run the sample app

Para executar a amostra, você precisará de Visual Studio e uma conta DB Azure Cosmos válida.To run the sample, you'll need Visual Studio and a valid Azure Cosmos DB account.

Se ainda não tem Visual Studio, baixe a Edição Comunitária do Visual Studio 2019 com a ASP.NET e a carga de trabalho de desenvolvimento web instalada com configuração.If you don't already have Visual Studio, download Visual Studio 2019 Community Edition with the ASP.NET and web development workload installed with setup.

Se não tiver uma subscrição do Azure,crie uma conta gratuita antes de começar.If you don't have an Azure subscription, create a free account before you begin.

Criar uma conta de base de dadosCreate a database account

  1. Numa nova janela do browser, inicie sessão no portal do Azure.In a new browser window, sign in to the Azure portal.

  2. No menu esquerdo, selecione Criar um recurso.In the left menu, select Create a resource.

    Criar um recurso no portal do Azure

  3. Na página Nova, selecione Databases > Azure Cosmos DB.On the New page, select Databases > Azure Cosmos DB.

    O painel Bases de dados do portal do Azure

  4. Na página De Conta DB Create Azure Cosmos, insira as definições para a nova conta DB da Azure Cosmos.On the Create Azure Cosmos DB Account page, enter the settings for the new Azure Cosmos DB account.

    DefiniçãoSetting ValorValue DescriçãoDescription
    SubscriçãoSubscription A sua subscriçãoYour subscription Selecione a subscrição do Azure que quer utilizar para esta conta do Azure Cosmos DB.Select the Azure subscription that you want to use for this Azure Cosmos DB account.
    Grupo de RecursosResource Group Criar novoCreate new

    Em seguida, insira o mesmo nome que Nome de ContaThen enter the same name as Account Name
    Selecione Criar novo.Select Create new. Em seguida, insira um novo nome de grupo de recursos para a sua conta.Then enter a new resource group name for your account. Para simplificar, use o mesmo nome que o nome da sua conta DB Azure Cosmos.For simplicity, use the same name as your Azure Cosmos DB account name.
    Nome da ContaAccount Name Introduza um nome exclusivoEnter a unique name Introduza um nome exclusivo para identificar a sua conta do Azure Cosmos DB.Enter a unique name to identify your Azure Cosmos DB account. A sua conta URI será mongo.cosmos.azure.com anexada ao seu nome de conta único.Your account URI will be mongo.cosmos.azure.com appended to your unique account name.

    O nome da conta só pode usar letras minúsculas, números e hífens (-), e deve ter entre 3 e 31 caracteres de comprimento.The account name can use only lowercase letters, numbers, and hyphens (-), and must be between 3 and 31 characters long.
    APIAPI Azure Cosmos DB para Mongo DB APIAzure Cosmos DB for Mongo DB API A API determina o tipo de conta a criar.The API determines the type of account to create. A Azure Cosmos DB fornece cinco APIs: Core (SQL) para bases de dados de documentos, Gremlin para bases de dados de gráficos, Azure Cosmos DB para Mongo DB API para bases de dados de documentos, Tabela Azure e Cassandra.Azure Cosmos DB provides five APIs: Core (SQL) for document databases, Gremlin for graph databases, Azure Cosmos DB for Mongo DB API for document databases, Azure Table, and Cassandra. De momento, deve criar uma conta separada para cada API.Currently, you must create a separate account for each API.

    Selecione Azure Cosmos DB para Mongo DB API porque neste quickstart você está criando uma coleção que funciona com o MongoDB.Select Azure Cosmos DB for Mongo DB API because in this quickstart you are creating a collection that works with MongoDB.

    Saiba mais sobre a Azure Cosmos DB para a MongoDB API.Learn more about Azure Cosmos DB for MongoDB API.
    LocalizaçãoLocation Selecione a região mais próxima dos seus utilizadoresSelect the region closest to your users Selecione a localização geográfica para alojar a sua conta do Azure Cosmos DB.Select a geographic location to host your Azure Cosmos DB account. Utilize a localização mais próxima dos seus utilizadores para lhes dar o acesso mais rápido aos dados.Use the location that's closest to your users to give them the fastest access to the data.
    Modo de capacidadeCapacity mode Produção provisida ou sem servidorProvisioned throughput or Serverless Selecione Provisão para criar uma conta no modo de produção previsto.Select Provisioned throughput to create an account in provisioned throughput mode. Selecione Serverless para criar uma conta no modo sem servidor.Select Serverless to create an account in serverless mode.

    Nota: Apenas a versão 3.6 da API de MongoDB é suportada por contas sem servidor.Note: Only MongoDB API version 3.6 is supported by serverless accounts. Escolher 3.2 como a versão forçará a conta no modo de produção previsto.Choosing 3.2 as the version will force the account in provisioned throughput mode.

    Selecione Review+Create.Select Review+Create. Pode saltar a secção 'Rede e Etiquetas'.You can skip the Network and Tags section.

    A página da nova conta do Azure Cosmos DB

  5. A criação da conta demora alguns minutos.The account creation takes a few minutes. Espere que o portal exiba os Parabéns! A sua conta Azure Cosmos DB para a API da Mongo DB está pronta.Wait for the portal to display the Congratulations! Your Azure Cosmos DB for Mongo DB API account is ready page.

    O painel de Notificações do portal do Azure

O exemplo descrito neste artigo é compatível com MongoDB.Driver versão 2.6.1.The sample described in this article is compatible with MongoDB.Driver version 2.6.1.

Clonar a aplicação de exemploClone the sample app

Primeiro, descarregue a aplicação de amostras do GitHub.First, download the sample app from GitHub.

  1. Abra uma linha de comandos, crie uma nova pasta designada git-samples e, em seguida, feche a linha de comandos.Open a command prompt, create a new folder named git-samples, then close the command prompt.

    mkdir "C:\git-samples"
    
  2. Abra uma janela de terminal do git, como o git bash e utilize o comando cd para alterar para uma nova pasta e instalar a aplicação de exemplo.Open a git terminal window, such as git bash, and use the cd command to change to the new folder to install the sample app.

    cd "C:\git-samples"
    
  3. Execute o seguinte comando para clonar o repositório de exemplo.Run the following command to clone the sample repository. Este comando cria uma cópia da aplicação de exemplo no seu computador.This command creates a copy of the sample app on your computer.

    git clone https://github.com/Azure-Samples/azure-cosmos-db-mongodb-dotnet-getting-started.git
    

Se ainda não pretende utilizar o git, também pode transferir o projeto como um ficheiro ZIP.If you don't wish to use git, you can also download the project as a ZIP file.

Rever o códigoReview the code

Este passo é opcional.This step is optional. Se estiver interessado em aprender de que forma os recursos da base de dados são criados no código, pode consultar os seguintes fragmentos.If you're interested in learning how the database resources are created in the code, you can review the following snippets. Caso contrário, pode avançar diretamente para Update your connection string (Atualizar a cadeia de ligação).Otherwise, you can skip ahead to Update your connection string.

Os seguintes fragmentos são retirados do ficheiro Dal.cs no diretório DAL.The following snippets are all taken from the Dal.cs file in the DAL directory.

  • Inicialize o cliente.Initialize the client.

        MongoClientSettings settings = new MongoClientSettings();
        settings.Server = new MongoServerAddress(host, 10255);
        settings.UseSsl = true;
        settings.SslSettings = new SslSettings();
        settings.SslSettings.EnabledSslProtocols = SslProtocols.Tls12;
    
        MongoIdentity identity = new MongoInternalIdentity(dbName, userName);
        MongoIdentityEvidence evidence = new PasswordEvidence(password);
    
        settings.Credential = new MongoCredential("SCRAM-SHA-1", identity, evidence);
    
        MongoClient client = new MongoClient(settings);
    
  • Obter a base de dados e a coleção.Retrieve the database and the collection.

    private string dbName = "Tasks";
    private string collectionName = "TasksList";
    
    var database = client.GetDatabase(dbName);
    var todoTaskCollection = database.GetCollection<MyTask>(collectionName);
    
  • Obter todos os documentos.Retrieve all documents.

    collection.Find(new BsonDocument()).ToList();
    

Crie uma tarefa e insira-a na coleçãoCreate a task and insert it into the collection

 public void CreateTask(MyTask task)
 {
     var collection = GetTasksCollectionForEdit();
     try
     {
         collection.InsertOne(task);
     }
     catch (MongoCommandException ex)
     {
         string msg = ex.Message;
     }
 }

Da mesma forma, pode atualizar e eliminar documentos ao utilizar os métodos collection.UpdateOne() e collection.DeleteOne().Similarly, you can update and delete documents by using the collection.UpdateOne() and collection.DeleteOne() methods.

Atualizar a cadeia de ligaçãoUpdate your connection string

Agora, regresse ao portal do Azure para obter as informações da cadeia de ligação e copie-as para a aplicação.Now go back to the Azure portal to get your connection string information and copy it into the app.

  1. No portal Azure, na sua conta Cosmos, na navegação esquerda clique em Connection String e, em seguida, clique em 'Ler-escrever Teclas'In the Azure portal, in your Cosmos account, in the left navigation click Connection String, and then click Read-write Keys. Vai utilizar os botões de copiar no lado direito do ecrã para copiar o Nome de Utilizador, a Palavra-passe e o Anfitrião para o ficheiro Dal.cs no próximo passo.You'll use the copy buttons on the right side of the screen to copy the Username, Password, and Host into the Dal.cs file in the next step.

  2. Abra o ficheiro Dal.cs no diretório DAL.Open the Dal.cs file in the DAL directory.

  3. Copie o valor de nome de utilizador a partir do portal (com o botão Copiar) e faça deste o valor de nome de utilizador no ficheiro Dal.cs.Copy your username value from the portal (using the copy button) and make it the value of the username in your Dal.cs file.

  4. Em seguida, copie o valor de anfitrião do portal e faça do mesmo o valor de anfitrião no ficheiro Dal.cs.Then copy your host value from the portal and make it the value of the host in your Dal.cs file.

  5. Por fim, copie o valor de palavra-passe do portal e faça do mesmo o valor de palavra-passe no ficheiro Dal.cs.Finally copy your password value from the portal and make it the value of the password in your Dal.cs file.

Atualizou agora a sua aplicação com todas as informações que precisa para comunicar com a Cosmos DB.You've now updated your app with all the info it needs to communicate with Cosmos DB.

Executar a aplicação WebRun the web app

  1. No Visual Studio, clique com o botão direito do rato no projeto no Explorador de Soluções e clique em Gerir Pacotes NuGet.In Visual Studio, right-click on the project in Solution Explorer and then click Manage NuGet Packages.

  2. Na caixa Procurar do NuGet, escreva MongoDB.Driver.In the NuGet Browse box, type MongoDB.Driver.

  3. A partir dos resultados, instale a biblioteca MongoDB.Driver.From the results, install the MongoDB.Driver library. Esta ação instala o pacote MongoDB.Driver, bem como todas as dependências do mesmo.This installs the MongoDB.Driver package as well as all dependencies.

  4. Clique em CTRL + F5 para executar a aplicação.Click CTRL + F5 to run the application. A aplicação é apresentada no browser.Your app displays in your browser.

  5. Clique em Criar no browser e crie algumas tarefas novas na aplicação de lista de tarefas.Click Create in the browser and create a few new tasks in your task list app.

Rever os SLAs no portal do AzureReview SLAs in the Azure portal

O portal Azure monitoriza a sua conta Cosmos DB, armazenamento, disponibilidade, latência e consistência.The Azure portal monitors your Cosmos DB account throughput, storage, availability, latency, and consistency. Gráficos para métricas associadas a um Acordo de Nível de Serviço DB da Azure Cosmos (SLA) mostram o valor SLA em comparação com o desempenho real.Charts for metrics associated with an Azure Cosmos DB Service Level Agreement (SLA) show the SLA value compared to actual performance. Este conjunto de métricas torna transparente a monitorização dos seus SLAs.This suite of metrics makes monitoring your SLAs transparent.

Para rever métricas e SLAs:To review metrics and SLAs:

  1. Selecione Métricas no menu de navegação da sua conta Cosmos DB.Select Metrics in your Cosmos DB account's navigation menu.

  2. Selecione um separador como Latência e selecione um prazo à direita.Select a tab such as Latency, and select a timeframe on the right. Compare as linhas Atual e SLA nas tabelas.Compare the Actual and SLA lines on the charts.

    Conjunto de métricas do Azure Cosmos DB

  3. Reveja as métricas nas outras abas.Review the metrics on the other tabs.

Limpar os recursosClean up resources

Quando terminar a sua app e a conta DB da Azure Cosmos, pode apagar os recursos Azure que criou para não incorrer em mais encargos.When you're done with your app and Azure Cosmos DB account, you can delete the Azure resources you created so you don't incur more charges. Para eliminar os recursos:To delete the resources:

  1. Na barra de pesquisa do portal Azure, procure e selecione grupos de Recursos.In the Azure portal Search bar, search for and select Resource groups.

  2. A partir da lista, selecione o grupo de recursos que criou para este arranque rápido.From the list, select the resource group you created for this quickstart.

    Selecione o grupo de recursos para eliminar

  3. Na página de visão geral do grupo de recursos, selecione Eliminar o grupo de recursos.On the resource group Overview page, select Delete resource group.

    Eliminar o grupo de recursos

  4. Na janela seguinte, insira o nome do grupo de recursos para eliminar e, em seguida, selecione Delete.In the next window, enter the name of the resource group to delete, and then select Delete.

Passos seguintesNext steps

Neste arranque rápido, aprendeu a criar uma conta Cosmos, criar uma coleção e executar uma aplicação de consola.In this quickstart, you've learned how to create a Cosmos account, create a collection and run a console app. Pode agora importar dados adicionais para a sua base de dados Cosmos.You can now import additional data to your Cosmos database.