Поделиться через

Краткое руководство: Использование Azure DocumentDB с драйвером MongoDB для C#

В этом кратком руководстве описано, как создать базовое приложение Azure DocumentDB с помощью C#. Azure DocumentDB — это хранилище данных NoSQL, позволяющее приложениям хранить документы в облаке и получать к ним доступ с помощью официальных драйверов MongoDB. В этом руководстве показано, как создавать документы и выполнять основные задачи в кластере Azure DocumentDB с помощью C#.

Справочник по | APIИсходный код | Пакет (NuGet)

Предпосылки

  • .NET 10.0 или более поздней версии

Создание кластера Azure DocumentDB

Чтобы приступить к работе, сначала необходимо создать кластер Azure DocumentDB, который служит основой для хранения данных NoSQL и управления ими.

  1. Войдите на портал Azure (https://portal.azure.com).

  2. В меню портала Azure или на главной странице выберите Создать ресурс.

  3. На новой странице найдите и выберите Azure DocumentDB.

    Снимок экрана: поиск Azure DocumentDB.

  4. На странице Создание кластера Azure DocumentDB и в разделе Основы выберите параметр Настройка в разделе Уровень кластера.

    Снимок экрана: параметр

  5. На странице масштабирования настройте эти параметры и нажмите кнопку "Сохранить ", чтобы сохранить изменения на уровне кластера.

    Ценность
    Уровень кластера M30 tier, 2 vCore, 8-GiB RAM
    Хранилище на сегмент 128 GiB

    Снимок экрана: параметры конфигурации для вычислений и хранилища для нового кластера Azure DocumentDB.

  6. В разделе "Основные сведения" настройте следующие параметры:

    Ценность
    Subscription Выберите подписку Azure.
    Группа ресурсов Создание новой группы ресурсов или выбор существующей группы ресурсов
    Имя кластера Укажите глобально уникальное имя
    Местоположение Выбор поддерживаемого региона Azure для подписки
    Версия MongoDB Выберите 8.0
    Имя администратора Создание имени пользователя для доступа к кластеру в качестве администратора пользователя
    Пароль Использование уникального пароля, связанного с именем пользователя

    Снимок экрана: параметры кластера.

    Подсказка

    Запишите значения, используемые для имени пользователя и пароля. Эти значения используются далее в этом руководстве. Дополнительные сведения о допустимых значениях см. в разделе об ограничениях кластера.

  7. Выберите Next: Networking.

  8. В разделе правил брандмауэра на вкладке "Сеть" настройте следующие параметры:

    Ценность
    Метод подключения Public access
    Разрешить общедоступный доступ из служб и ресурсов в Azure к этому кластеру Enabled

  9. Добавьте правило брандмауэра для текущего клиентского устройства, чтобы предоставить доступ к кластеру, нажав кнопку +Добавить текущий IP-адрес клиента.

    Снимок экрана: конфигурации сети.

    Подсказка

    Во многих корпоративных средах IP-адреса компьютера разработчика скрыты из-за VPN или других параметров корпоративной сети. В этих случаях можно временно разрешить доступ ко всем IP-адресам, добавив 0.0.0.0 - 255.255.255.255 диапазон IP-адресов в качестве правила брандмауэра. Используйте это правило брандмауэра только временно в рамках тестирования и разработки подключений.

  10. Выберите Review + create.

  11. Проверьте настройки, которые вы указали, и затем выберите Создать. Создание кластера занимает несколько минут. Дождитесь завершения развертывания ресурсов.

  12. Наконец, выберите "Перейти к ресурсу" , чтобы перейти к кластеру Azure DocumentDB на портале.

Снимок экрана: параметры ресурса goto.

Получение учетных данных кластера

Получите учетные данные, используемые для подключения к кластеру.

  1. На странице кластера выберите параметр "Строки подключения " в меню ресурсов.

  2. В разделе "Строки подключения" скопируйте или запишите значение из поля строки подключения .

Снимок экрана, показывающий опцию строк подключения.

Это важно

Строка подключения на портале не включает значение пароля. Вы должны заменить плейсхолдер <password> на учетные данные, введенные при создании кластера, или ввести пароль в интерактивном режиме.

Инициализируйте проект

Создайте проект консольного приложения .NET в текущем каталоге.

  1. Начните в пустом каталоге.

  2. Откройте терминал в текущем каталоге.

  3. Создайте консольное приложение .NET.

    dotnet new console

  4. Создайте проект, чтобы убедиться, что он был успешно создан.

    dotnet build

Установка клиентской библиотеки

Клиентская библиотека доступна через NuGet в качестве MongoDB.Driver пакета.

  1. Установите драйвер MongoDB .NET с помощью диспетчера пакетов NuGet.

    dotnet add package MongoDB.Driver

  2. Откройте и просмотрите файл azure-documentdb-dotnet-quickstart.csproj , чтобы проверить наличие ссылки на пакет.

  3. Импортируйте необходимые пространства имен в код приложения:

    using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using MongoDB.Bson;
using MongoDB.Bson.Serialization.Attributes;
using MongoDB.Driver;

Объектная модель

Имя Description
MongoClient Тип, используемый для подключения к MongoDB.
IMongoDatabase Представляет базу данных в кластере.
IMongoCollection<T> Представляет коллекцию в базе данных в кластере.

Примеры кода

Код в этом приложении подключается к базе данных с именем adventureworks и коллекцией с именем products. Коллекция products содержит такие сведения, как имя, категория, количество, уникальный идентификатор и флаг продажи для каждого продукта. Примеры кода, приведенные здесь, выполняют наиболее распространенные операции при работе с коллекцией.

аутентификация клиента;

Сначала подключитесь к клиенту с помощью базовой строки подключения.

  1. Создайте основной метод и настройте строку подключения. Замените <your-cluster-name>и <your-username><your-password> фактическими сведениями о кластере.

    class Program
{
    static async Task Main(string[] args)
    {
        // Connection string for Azure DocumentDB cluster
        string connectionString = "mongodb+srv://<your-username>:<your-password>@<your-cluster-name>.global.mongocluster.cosmos.azure.com/?tls=true&authMechanism=SCRAM-SHA-256&retrywrites=false&maxIdleTimeMS=120000";

        // Create MongoDB client settings
        var settings = MongoClientSettings.FromConnectionString(connectionString);

  2. Создайте клиент MongoDB и проверьте подключение.

            // Create a new client and connect to the server
        var client = new MongoClient(settings);

        // Ping the server to verify connection
        var database = client.GetDatabase("admin");
        var pingCommand = new BsonDocument("ping", 1);
        await database.RunCommandAsync<BsonDocument>(pingCommand);

        Console.WriteLine("Successfully connected and pinged Azure DocumentDB");

Получите коллекцию

Теперь получите базу данных и коллекцию. Если база данных и коллекция еще не существуют, используйте драйвер для автоматического создания.

  1. Получите ссылку на базу данных.

            // Get database reference
        var adventureWorksDatabase = client.GetDatabase("adventureworks");
        Console.WriteLine($"Connected to database: {adventureWorksDatabase.DatabaseNamespace.DatabaseName}");

  2. Получите ссылку на коллекцию в базе данных.

            // Get collection reference
        var productsCollection = adventureWorksDatabase.GetCollection<Product>("products");
        Console.WriteLine($"Connected to collection: products");

Создание документа

Затем создайте несколько новых документов в коллекции. Добавление или обновление документов, чтобы гарантировать замену существующих документов при совпадении уникальных идентификаторов.

  1. Определите класс Product и создайте примеры документов продукта.

            // Create sample products
        var products = new List<Product>
        {
            new Product
            {
                Id = "00000000-0000-0000-0000-000000004018",
                Name = "Windry Mittens",
                Category = "apparel-accessories-gloves-and-mittens",
                Quantity = 121,
                Price = 35.00m,
                Sale = false
            },
            new Product
            {
                Id = "00000000-0000-0000-0000-000000004318",
                Name = "Niborio Tent",
                Category = "gear-camp-tents",
                Quantity = 140,
                Price = 420.00m,
                Sale = true
            }
        };

  2. Вставьте документы с помощью операций upsert.

            // Insert documents with upsert
        foreach (var product in products)
        {
            var filter = Builders<Product>.Filter.Eq(p => p.Id, product.Id);
            var options = new ReplaceOptions { IsUpsert = true };

            await productsCollection.ReplaceOneAsync(filter, product, options);
            Console.WriteLine($"Upserted product: {product.Name}");
        }

  3. Добавьте определение класса Product в конце файла Program.cs.

    public class Product
{
    [BsonId]
    [BsonElement("_id")]
    public string Id { get; set; }

    [BsonElement("name")]
    public string Name { get; set; }

    [BsonElement("category")]
    public string Category { get; set; }

    [BsonElement("quantity")]
    public int Quantity { get; set; }

    [BsonElement("price")]
    public decimal Price { get; set; }

    [BsonElement("sale")]
    public bool Sale { get; set; }
}

Получение документа

Затем выполните операцию точечного чтения, чтобы получить определенный документ из вашей коллекции.

  1. Определите фильтр для поиска определенного документа по идентификатору.

            // Retrieve a specific document by ID
        var filter = Builders<Product>.Filter.Eq(p => p.Id, "00000000-0000-0000-0000-000000004018");

  2. Выполните запрос и получите результат.

            var retrievedProduct = await productsCollection.Find(filter).FirstOrDefaultAsync();

        if (retrievedProduct != null)
        {
            Console.WriteLine($"Retrieved product: {retrievedProduct.Name} - ${retrievedProduct.Price}");
        }
        else
        {
            Console.WriteLine("Product not found");
        }

Поиск документов

Наконец, запросите несколько документов с помощью языка запросов MongoDB (MQL).

  1. Определите запрос для поиска документов, соответствующих определенным критериям.

            // Query for products on sale
        var saleFilter = Builders<Product>.Filter.Eq(p => p.Sale, true);
        var saleProducts = await productsCollection.Find(saleFilter).ToListAsync();

  2. Выполните итерацию результатов, чтобы отобразить соответствующие документы.

            Console.WriteLine("Products on sale:");
        foreach (var product in saleProducts)
        {
            Console.WriteLine($"- {product.Name}: ${product.Price:F2} (Category: {product.Category})");
        }
    }
}

Изучение данных с помощью Visual Studio Code

Используйте расширение DocumentDB в Visual Studio Code для выполнения основных операций базы данных, включая запросы, вставку, обновление и удаление данных.

  1. Откройте Visual Studio Code.

  2. Перейдите к представлению расширений и найдите термин DocumentDB. Найдите расширение DocumentDB для VS Code .

  3. Нажмите кнопку "Установить " для расширения. Дождитесь завершения установки. При появлении запроса перезагрузите Visual Studio Code.

  4. Перейдите к расширению DocumentDB , выбрав соответствующий значок в строке действий.

  5. В области "Подключения DocumentDB" выберите +Создать подключение....

  6. В диалоговом окне выберите "Обнаружение служб" , а затем Azure DocumentDB — Обнаружение служб Azure.

  7. Выберите подписку Azure и созданный кластер Azure DocumentDB.

    Подсказка

    Во многих корпоративных средах IP-адреса компьютера разработчика скрыты из-за VPN или других параметров корпоративной сети. В этих случаях можно временно разрешить доступ ко всем IP-адресам, добавив 0.0.0.0 - 255.255.255.255 диапазон IP-адресов в качестве правила брандмауэра. Используйте это правило брандмауэра только временно в рамках тестирования и разработки подключений. Дополнительные сведения см. в разделе "Настройка брандмауэра".

  8. В области "Подключения DocumentDB" разверните узел кластера и перейдите к существующим узлам документа и коллекции.

  9. Откройте контекстное меню для коллекции, а затем выберите DocumentDB Scrapbook New DocumentDB Scrapbook>.

  10. Введите следующие команды языка запросов MongoDB (MQL) и нажмите кнопку "Выполнить все". Просмотрите выходные данные команд.

    db.products.find({
  price: { $gt: 200 },
  sale: true
})
.sort({ price: -1 })
.limit(3)

Очистите ресурсы

Когда вы закончите работу с кластером Azure DocumentDB, вы можете удалить созданные ресурсы Azure, чтобы не взимать больше расходов.

  1. В строке поиска портал Azure найдите и выберите группы ресурсов.

    Снимок экрана: параметр поиска групп ресурсов.

  2. В списке выберите группу ресурсов, которую вы использовали для этого быстрого начала.

    Снимок экрана: группа ресурсов.

  3. На странице группы ресурсов выберите Удалить группу ресурсов.

  4. В диалоговом окне подтверждения удаления введите имя группы ресурсов, чтобы убедиться, что она будет удалена. Наконец, выберите "Удалить ", чтобы окончательно удалить группу ресурсов.

    Снимок экрана, показывающий кнопку подтверждения удаления группы ресурсов.

Связанный контент

  • Last updated on