Inicio rápido: Creación de una aplicación Xamarin.Forms con .NET SDK y la API de Azure Cosmos DB para MongoDBQuickStart: Build a Xamarin.Forms app with .NET SDK and Azure Cosmos DB's API for MongoDB

Azure Cosmos DB es un servicio de base de datos con varios modelos y de distribución global de Microsoft.Azure Cosmos DB is Microsoft's globally distributed multi-model database service. Puede crear rápidamente bases de datos de documentos, clave-valor y grafos, y realizar consultas en ellas. Todas las bases de datos se beneficiarán de las funcionalidades de distribución global y escala horizontal en Azure 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 Azure Cosmos DB.

En este artículo de inicio rápido se muestra cómo crear una cuenta de Cosmos configurada con la API de Azure Cosmos DB para MongoDB, una base de datos de documentos y una colección desde Azure Portal.This quickstart demonstrates how to create a Cosmos account configured with Azure Cosmos DB's API for MongoDB, document database, and collection using the Azure portal. Luego compilará una aplicación Xamarin.Forms de aplicación de tareas pendientes mediante el controlador .NET de MongoDB.You'll then build a todo app Xamarin.Forms app by using the MongoDB .NET driver.

Requisitos previos para ejecutar la aplicación de ejemploPrerequisites to run the sample app

Para ejecutar el ejemplo, necesitará Visual Studio o Visual Studio para Mac y una cuenta de Azure CosmosDB válida.To run the sample, you'll need Visual Studio or Visual Studio for Mac and a valid Azure CosmosDB account.

Si no tiene Visual Studio, descargue Visual Studio 2019 Community Edition con la carga de trabajo desarrollo móvil con .NET instalada con el programa de instalación.If you don't already have Visual Studio, download Visual Studio 2019 Community Edition with the Mobile development with .NET workload installed with setup.

Si prefiere trabajar en un equipo Mac, descargue Visual Studio para Mac y ejecute el programa de instalación.If you prefer to work on a Mac, download Visual Studio for Mac and run the setup.

Si no tiene una suscripción a Azure, cree una cuenta gratuita antes de empezar.If you don't have an Azure subscription, create a free account before you begin.

Creación de una cuenta de base de datosCreate a database account

  1. En una nueva ventana del explorador, inicie sesión en Azure Portal.In a new browser window, sign in to the Azure portal.

  2. En el menú de la izquierda, seleccione Crear un recurso.In the left menu, select Create a resource.

    Crear un recurso en Azure Portal

  3. En la página Nuevo, seleccione Bases de datos > Azure Cosmos DB.On the New page, select Databases > Azure Cosmos DB.

    El panel de las bases de datos de Azure Portal

  4. En la página Crear una cuenta de Azure Cosmos DB, especifique la configuración de la nueva cuenta de Azure Cosmos DB.On the Create Azure Cosmos DB Account page, enter the settings for the new Azure Cosmos DB account.

    ConfiguraciónSetting ValueValue DescripciónDescription
    SubscriptionSubscription Su suscripciónYour subscription Seleccione la suscripción de Azure que quiere usar para esta cuenta de Azure Cosmos DB.Select the Azure subscription that you want to use for this Azure Cosmos DB account.
    Grupo de recursosResource Group Crear nuevoCreate new

    A continuación, escriba el mismo nombre que el nombre de cuenta.Then enter the same name as Account Name
    Seleccione Crear nuevo.Select Create new. Luego, escriba un nombre nuevo de grupo de recursos para la cuenta.Then enter a new resource group name for your account. Para simplificar, use el mismo nombre que el de la cuenta de Azure Cosmos DB.For simplicity, use the same name as your Azure Cosmos DB account name.
    Nombre de cuentaAccount Name Escriba un nombre único.Enter a unique name Escriba un nombre único para identificar la cuenta de Azure Cosmos DB.Enter a unique name to identify your Azure Cosmos DB account. El URI de la cuenta será mongo.cosmos.azure.com y se anexará al nombre único de la cuenta.Your account URI will be mongo.cosmos.azure.com appended to your unique account name.

    El nombre de la cuenta solo puede utilizar letras minúsculas, números y guiones (-), y debe tener entre 3 y 31 caracteres de longitud.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 la API de Mongo DBAzure Cosmos DB for Mongo DB API La API determina el tipo de cuenta que se va a crear.The API determines the type of account to create. Azure Cosmos DB proporciona cinco API: Core (SQL) para bases de datos de documentos, Gremlin para bases de datos de grafos, API Mongo DB de Azure Cosmos DB para bases de datos de documentos, Azure Table y 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. Actualmente, debe crear una cuenta independiente para cada API.Currently, you must create a separate account for each API.

    Seleccione Azure Cosmos DB para la API de Mongo DB, ya que en este inicio rápido va a crear una colección que funciona con MongoDB.Select Azure Cosmos DB for Mongo DB API because in this quickstart you are creating a collection that works with MongoDB.

    Obtenga más información sobre Azure Cosmos DB para la API de Mongo DB.Learn more about Azure Cosmos DB for MongoDB API.
    LocationLocation Seleccionar la región más cercana a los usuariosSelect the region closest to your users Seleccione una ubicación geográfica para hospedar la cuenta de Azure Cosmos DB.Select a geographic location to host your Azure Cosmos DB account. Use la ubicación más cercana a los usuarios para proporcionarles el acceso más rápido a los datos.Use the location that's closest to your users to give them the fastest access to the data.

    Seleccione Revisar y crear.Select Review+Create. Puede omitir las secciones Red y Etiquetas.You can skip the Network and Tags section.

    Página de la nueva cuenta de Azure Cosmos DB

  5. La cuenta tarda unos minutos en crearse.The account creation takes a few minutes. Espere a que el portal muestre la página ¡Enhorabuena! Su cuenta de Azure Cosmos DB para la API de Mongo DB está a punto.Wait for the portal to display the Congratulations! Your Azure Cosmos DB for Mongo DB API account is ready page.

    El panel de las notificaciones de Azure Portal

El ejemplo que se describe en este artículo es compatible con la versión 2.6.1 de MongoDB.Driver.The sample described in this article is compatible with MongoDB.Driver version 2.6.1.

Clonación de la aplicación de ejemploClone the sample app

En primer lugar, descargue la aplicación de ejemplo de GitHub.First, download the sample app from GitHub. Implementa una aplicación de tareas pendientes con el modelo de almacenamiento de documentos de MongoDB.It implements a todo app with MongoDB's document storage model.

  1. En Windows, abra un símbolo del sistema o, en Mac, abra Terminal, cree una nueva carpeta denominada git-samples y, a continuación, cierre la ventana.On Windows open a command prompt or on Mac open the terminal, create a new folder named git-samples, then close the window.

    md "C:\git-samples"
    
    mkdir '$home\git-samples\
    
  2. Abra una ventana de terminal de Git, como git bash y utilice el comando cd para cambiar a la nueva carpeta para instalar la aplicación de ejemplo.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. Ejecute el comando siguiente para clonar el repositorio de ejemplo.Run the following command to clone the sample repository. Este comando crea una copia de la aplicación de ejemplo en el equipo.This command creates a copy of the sample app on your computer.

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

Si no desea usar git, también puede descargar el proyecto como un archivo ZIPIf you don't wish to use git, you can also download the project as a ZIP file

Revisión del códigoReview the code

Este paso es opcional.This step is optional. Si está interesado en aprender cómo se crean los recursos de base de datos en el código, puede revisar los siguientes fragmentos de código.If you're interested in learning how the database resources are created in the code, you can review the following snippets. En caso contrario, puede ir directamente a Actualización de la cadena de conexión.Otherwise, you can skip ahead to Update your connection string.

Todos los fragmentos de código siguiente se toman de la clase MongoService, que se encuentra en la ruta de acceso siguiente: src/TaskList.Core/Services/MongoService.cs.The following snippets are all taken from the MongoService class, found at the following path: src/TaskList.Core/Services/MongoService.cs.

  • Inicialice Mongo Client.Initialize the Mongo Client.

    MongoClientSettings settings = MongoClientSettings.FromUrl(
        new MongoUrl(APIKeys.ConnectionString)
    );
    
    settings.SslSettings =
        new SslSettings() { EnabledSslProtocols = SslProtocols.Tls12 };
    
    settings.RetryWrites = false;
    
    MongoClient mongoClient = new MongoClient(settings);
    
  • Recupere una referencia a la base de datos y la colección.Retrieve a reference to the database and collection. El SDK de .NET de MongoDB creará automáticamente tanto la base de datos como la colección si todavía no existen.The MongoDB .NET SDK will automatically create both the database and collection if they do not already exist.

    string dbName = "MyTasks";
    string collectionName = "TaskList";
    
    var db = mongoClient.GetDatabase(dbName);
    
    var collectionSettings = new MongoCollectionSettings {
        ReadPreference = ReadPreference.Nearest
    };
    
    tasksCollection = db.GetCollection<MyTask>(collectionName, collectionSettings);
    
  • Recupere todos los documentos como una lista.Retrieve all documents as a List.

    var allTasks = await TasksCollection
                    .Find(new BsonDocument())
                    .ToListAsync();
    
  • Consulta de documentos determinados.Query for particular documents.

    public async Task<List<MyTask>> GetIncompleteTasksDueBefore(DateTime date)
    {
        var tasks = await TasksCollection
                        .AsQueryable()
                        .Where(t => t.Complete == false)
                        .Where(t => t.DueDate < date)
                        .ToListAsync();
    
        return tasks;
    }
    
  • Cree una tarea e insértela en la colección.Create a task and insert it into the collection.

    public async Task CreateTask(MyTask task)
    {
        await TasksCollection.InsertOneAsync(task);
    }
    
  • Actualice una tarea de una colección.Update a task in a collection.

    public async Task UpdateTask(MyTask task)
    {
        await TasksCollection.ReplaceOneAsync(t => t.Id.Equals(task.Id), task);
    }
    
  • Elimine una tarea de una colección.Delete a task from a collection.

    public async Task DeleteTask(MyTask task)
    {
        await TasksCollection.DeleteOneAsync(t => t.Id.Equals(task.Id));
    }
    

Actualización de la cadena de conexiónUpdate your connection string

Ahora vuelva a Azure Portal para obtener la información de la cadena de conexión y cópiela en la aplicación.Now go back to the Azure portal to get your connection string information and copy it into the app.

  1. En Azure Portal, en la cuenta de Azure Cosmos DB, en el panel de navegación izquierdo, haga clic en Cadena de conexión y en Claves de lectura y escritura.In the Azure portal, in your Azure Cosmos DB account, in the left navigation click Connection String, and then click Read-write Keys. Usará los botones de copia que están en el lado derecho de la pantalla para copiar la cadena de conexión principal en los pasos siguientes.You'll use the copy buttons on the right side of the screen to copy the Primary Connection String in the next steps.

  2. Abra el archivo APIKeys.cs en el directorio Helpers (Aplicaciones auxiliares) del proyecto TaskList.Core.Open the APIKeys.cs file in the Helpers directory of the TaskList.Core project.

  3. Copie el valor de la cadena de conexión principal del portal (con el botón de copia) y conviértalo en el valor del campo ConnectionString en el archivo APIKeys.cs.Copy your primary connection string value from the portal (using the copy button) and make it the value of the ConnectionString field in your APIKeys.cs file.

  4. Quite &replicaSet=globaldb de la cadena de conexión.Remove &replicaSet=globaldb from the connection string. Obtendrá un error en tiempo de ejecución si no quita ese valor de la cadena de consulta.You will get a runtime error if you do not remove that value from the query string.

Importante

Debe quitar el par clave-valor &replicaSet=globaldb de la cadena de consulta de la cadena de conexión para evitar un error en tiempo de ejecución.You must remove the &replicaSet=globaldb key/value pair from the connection string's query string in order to avoid a runtime error.

Ya ha actualizado la aplicación con toda la información que necesita para comunicarse con Azure Cosmos DB.You've now updated your app with all the info it needs to communicate with Azure Cosmos DB.

Ejecución la aplicaciónRun the app

Visual Studio 2019Visual Studio 2019

  1. En Visual Studio, haga clic con el botón derecho en cada proyecto en el Explorador de soluciones y, después, haga clic en Administrar paquetes NuGet.In Visual Studio, right-click on each project in Solution Explorer and then click Manage NuGet Packages.
  2. Haga clic en Restore all NuGet packages (Restaurar todos los paquetes NuGet).Click Restore all NuGet packages.
  3. Haga clic con el botón derecho en TaskList.Android y seleccione Establecer como proyecto de inicio.Right click on the TaskList.Android and select Set as startup project.
  4. Presione F5 para iniciar la depuración de la aplicación.Press F5 to start debugging the application.
  5. Si quiere ejecutar en iOS, primero asegúrese de que la máquina esté conectada a un equipo Mac (aquí hay algunas instrucciones sobre cómo hacerlo).If you want to run on iOS, first your machine is connected to a Mac (here are instructions on how to do so).
  6. Haga clic con el botón derecho en el proyecto TaskList.iOS y seleccione Establecer como proyecto de inicio.Right click on TaskList.iOS project and select Set as startup project.
  7. Haga clic en F5 para iniciar la depuración de la aplicación.Click F5 to start debugging the application.

Visual Studio para MacVisual Studio for Mac

  1. En la lista desplegable de plataforma, seleccione TaskList.iOS o TaskList.Android, en función de la plataforma en que quiere realizar la ejecución.In the platform dropdown list, select either TaskList.iOS or TaskList.Android, depending which platform you want to run on.
  2. Presione cmd+Entrar para empezar a depurar la aplicación.Press cmd+Enter to start debugging the application.

Revisión de los SLA en Azure PortalReview SLAs in the Azure portal

Azure Portal supervisa el rendimiento, capacidad de almacenamiento, disponibilidad, latencia y coherencia de su cuenta de Cosmos DB.The Azure portal monitors your Cosmos DB account throughput, storage, availability, latency, and consistency. Los gráficos de las métricas asociadas con un Acuerdo de Nivel de Servicio (SLA) de Azure Cosmos DB muestran el rendimiento real en comparación con el valor de este acuerdo.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 hace que la supervisión de los Acuerdos de Nivel de Servicio sea transparente.This suite of metrics makes monitoring your SLAs transparent.

Para revisar las métricas y los Acuerdos de Nivel de Servicio:To review metrics and SLAs:

  1. Seleccione Métricas en el menú de navegación de la cuenta de Cosmos DB.Select Metrics in your Cosmos DB account's navigation menu.

  2. Seleccione una pestaña como Latencia y seleccione un período de tiempo a la derecha.Select a tab such as Latency, and select a timeframe on the right. Compare las líneas Real y SLA de los gráficos.Compare the Actual and SLA lines on the charts.

    Conjunto de métricas de Azure Cosmos DB

  3. Revise las métricas de las otras pestañas.Review the metrics on the other tabs.

Limpieza de recursosClean up resources

Cuando haya terminado tanto con la aplicación como con la cuenta de Azure Cosmos DB, puede eliminar los recursos de Azure que creó para no tener más gastos.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 los recursos:To delete the resources:

  1. En la barra de búsqueda de Azure Portal, busque y seleccione Grupos de recursos.In the Azure portal Search bar, search for and select Resource groups.

  2. En la lista, seleccione el grupo de recursos que creó para este inicio rápido.From the list, select the resource group you created for this quickstart.

    Selección del grupo de recursos que se eliminará

  3. En la página Información general del grupo de recursos, seleccione Eliminar grupo de recursos.On the resource group Overview page, select Delete resource group.

    Eliminar el grupo de recursos

  4. En la ventana siguiente, escriba el nombre del grupo de recursos que desea eliminar y, después, seleccione Eliminar.In the next window, enter the name of the resource group to delete, and then select Delete.

Pasos siguientesNext steps

En esta guía de inicio rápido, ha aprendido a crear una cuenta de Azure Cosmos DB y ejecutar una aplicación Xamarin.Forms con la API para MongoDB.In this quickstart, you've learned how to create an Azure Cosmos DB account and run a Xamarin.Forms app using the API for MongoDB. Ahora puede importar datos adicionales en la cuenta de Cosmos DB.You can now import additional data to your Cosmos DB account.