Szybki start: używanie usługi Azure DocumentDB ze sterownikiem MongoDB dla języka C#

W tym szybkim przewodniku tworzysz podstawową aplikację usługi Azure DocumentDB przy użyciu języka C#. Azure DocumentDB to magazyn danych NoSQL, który umożliwia aplikacjom przechowywanie dokumentów w chmurze i uzyskiwanie do nich dostępu przy użyciu oficjalnych sterowników bazy danych MongoDB. W tym przewodniku pokazano, jak tworzyć dokumenty i wykonywać podstawowe zadania w klastrze usługi Azure DocumentDB przy użyciu języka C#.

Dokumentacja interfejsu | APIKod źródłowy | Pakiet (NuGet)

Wymagania wstępne

Subskrypcja platformy Azure
- Jeśli nie masz subskrypcji platformy Azure, utwórz bezpłatne konto

.NET 10.0 lub nowszy

Tworzenie klastra usługi Azure DocumentDB

Aby rozpocząć, musisz najpierw utworzyć klaster usługi Azure DocumentDB, który służy jako podstawa do przechowywania danych NoSQL i zarządzania nimi.

Zaloguj się do witryny Azure Portal (https://portal.azure.com).
W menu witryny Azure Portal lub na stronie głównej wybierz pozycję Utwórz zasób.
Na stronie Nowy wyszukaj i wybierz pozycję Azure DocumentDB.
Na stronie Tworzenie klastra usługi Azure DocumentDB i w sekcji Podstawy wybierz opcję Konfiguruj w sekcji Warstwa klastra .
Na stronie Skalowanie skonfiguruj te opcje, a następnie wybierz Zapisz aby zapisać zmiany w warstwie klastra.

Wartość

Warstwa klastra M30 tier, 2 vCore, 8-GiB RAM

Przechowywanie na odłam 128 GiB

	Wartość
Warstwa klastra	`M30 tier, 2 vCore, 8-GiB RAM`
Przechowywanie na odłam	`128 GiB`

W sekcji Podstawowe skonfiguruj następujące opcje:

	Wartość
Subscription	Wybierz subskrypcję platformy Azure
Grupa zasobów	Utwórz nową grupę zasobów lub wybierz istniejącą grupę zasobów
Nazwa klastra	Podaj globalnie unikatową nazwę
Lokalizacja	Wybieranie obsługiwanego regionu platformy Azure dla subskrypcji
Wersja bazy danych MongoDB	Wybierz pozycję `8.0`
Nazwa użytkownika administratora	Tworzenie nazwy użytkownika w celu uzyskania dostępu do klastra jako administrator użytkownika
Hasło	Używanie unikatowego hasła skojarzonego z nazwą użytkownika

Zrzut ekranu przedstawiający parametry klastra.

Wskazówka

Zapisz wartości używane dla nazwy użytkownika i hasła. Te wartości są używane w dalszej części tego przewodnika. Aby uzyskać więcej informacji na temat prawidłowych wartości, zobacz ograniczenia klastra.

Wybierz Dalej: Sieć.
W sekcji Reguły zapory na karcie Sieć skonfiguruj następujące opcje:

Wartość

Metoda łączności Public access

Zezwól na publiczny dostęp do tego klastra z usług i zasobów w ramach platformy Azure Enabled
Dodaj regułę zapory dla bieżącego urządzenia klienckiego, aby udzielić dostępu do klastra, wybierając pozycję + Dodaj bieżący adres IP klienta.

Wskazówka

W wielu środowiskach firmowych adresy IP maszyny deweloperów są ukryte z powodu sieci VPN lub innych ustawień sieci firmowych. W takich przypadkach można tymczasowo zezwolić na dostęp do wszystkich adresów IP, dodając 0.0.0.0 - 255.255.255.255 zakres adresów IP jako regułę zapory. Użyj tej reguły zapory tylko tymczasowo w ramach testowania i programowania połączeń.
Wybierz opcję Recenzja i utwórz.
Przejrzyj ustawienia, które podałeś, a następnie wybierz Utwórz. Utworzenie klastra trwa kilka minut. Poczekaj na zakończenie wdrażania zasobów.
Na koniec wybierz pozycję Przejdź do zasobu , aby przejść do klastra usługi Azure DocumentDB w portalu.

	Wartość
Metoda łączności	`Public access`
Zezwól na publiczny dostęp do tego klastra z usług i zasobów w ramach platformy Azure	Enabled

Zrzut ekranu przedstawiający opcje zasobów goto.

Pobieranie poświadczeń klastra

Pobierz poświadczenia używane do nawiązania połączenia z klastrem.

Na stronie klastra wybierz opcję Parametry połączenia w menu zasobów.
W sekcji Parametry połączenia skopiuj lub zarejestruj wartość z pola Parametry połączenia .

Zrzut ekranu przedstawiający opcję parametrów połączenia.

Ważne

Parametry połączenia w portalu nie zawierają wartości hasła. Musisz zastąpić element zastępczy <password> poświadczeniami, które wprowadziłeś podczas tworzenia klastra, lub wprowadzić hasło interaktywnie.

Inicjowanie projektu

Utwórz nowy projekt aplikacji konsolowej platformy .NET w bieżącym katalogu.

Rozpocznij w pustym katalogu.
Otwórz terminal w bieżącym katalogu.
Utwórz nową aplikację konsolową platformy .NET.
```
dotnet new console
```
Skompiluj projekt, aby upewnić się, że został utworzony pomyślnie.
```
dotnet build
```

Instalowanie biblioteki klienta

Biblioteka klienta jest dostępna jako pakiet MongoDB.Driver za pośrednictwem NuGet.

Zainstaluj sterownik .NET bazy danych MongoDB przy użyciu menedżera pakietów NuGet.
```
dotnet add package MongoDB.Driver
```
Otwórz i przejrzyj plik azure-documentdb-dotnet-quickstart.csproj , aby sprawdzić, czy odwołanie do pakietu istnieje.

Zaimportuj wymagane przestrzenie nazw do kodu aplikacji:

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

Model obiektów

Name	Description
`MongoClient`	Typ używany do nawiązywania połączenia z bazą danych MongoDB.
`IMongoDatabase`	Reprezentuje bazę danych w klastrze.
`IMongoCollection<T>`	Reprezentuje kolekcję w bazie danych w klastrze.

Kod w tej aplikacji łączy się z bazą danych o nazwie adventureworks i kolekcją o nazwie products. Kolekcja products zawiera szczegóły, takie jak nazwa, kategoria, ilość, unikatowy identyfikator i flaga sprzedaży dla każdego produktu. Przykłady kodu w tym miejscu wykonują najbardziej typowe operacje podczas pracy z kolekcją.

Uwierzytelnianie klienta

Najpierw połącz się z klientem przy użyciu podstawowych parametrów połączenia.

Utwórz główną metodę i skonfiguruj łańcuch połączenia. Zastąp <your-cluster-name>, <your-username> i <your-password> rzeczywistymi informacjami o klastrze.

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);

Utwórz klienta bazy danych MongoDB i zweryfikuj połączenie.

        // 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");

Zdobądź kolekcję

Teraz pobierz bazę danych i kolekcję. Jeśli baza danych i kolekcja jeszcze nie istnieją, użyj sterownika, aby utworzyć ją automatycznie.

Uzyskaj referencję do bazy danych.

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

Pobierz odwołanie do kolekcji w bazie danych.

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

Tworzenie dokumentu

Następnie utwórz kilka nowych dokumentów w kolekcji. Aktualizuj lub wstaw dokumenty, aby upewnić się, że zastępują one te istniejące dokumenty, które mają ten sam unikatowy identyfikator.

Zdefiniuj klasę Product i utwórz przykładowe dokumenty produktu.

        // 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
            }
        };

Wstaw dokumenty przy użyciu operacji 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}");
        }

Dodaj definicję klasy Product na końcu pliku 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; }
}

Pobieranie dokumentu

Następnie wykonaj operację odczytu punktowego, aby zlokalizować i pobrać określony dokument z kolekcji.

Zdefiniuj filtr, aby znaleźć określony dokument według identyfikatora.

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

Wykonaj zapytanie i pobierz wynik.

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

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

Zapytanie o dokumenty

Na koniec wykonaj zapytanie o wiele dokumentów przy użyciu języka zapytań MongoDB (MQL).

Zdefiniuj zapytanie, aby znaleźć dokumenty spełniające określone kryteria.

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

Iteruj wyniki, aby wyświetlić pasujące dokumenty.

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

Eksplorowanie danych przy użyciu programu Visual Studio Code

Użyj rozszerzenia DocumentDB w programie Visual Studio Code, aby wykonywać podstawowe operacje bazy danych, w tym wykonywanie zapytań, wstawianie, aktualizowanie i usuwanie danych.

Otwórz program Visual Studio Code.
Przejdź do widoku Rozszerzenia i wyszukaj termin DocumentDB. Znajdź rozszerzenie DocumentDB dla programu VS Code .
Wybierz przycisk Zainstaluj dla rozszerzenia. Poczekaj na zakończenie instalacji. Załaduj ponownie program Visual Studio Code, jeśli zostanie wyświetlony monit.
Przejdź do rozszerzenia usługi DocumentDB , wybierając odpowiednią ikonę na pasku działań.
W okienku Połączenia usługi DocumentDB wybierz pozycję + Nowe połączenie....
W oknie dialogowym wybierz pozycję Odnajdywanie usług , a następnie Pozycję Azure DocumentDB — Azure Service Discovery.
Wybierz subskrypcję platformy Azure i nowo utworzony klaster usługi Azure DocumentDB.

Wskazówka

W wielu środowiskach firmowych adresy IP maszyny deweloperów są ukryte z powodu sieci VPN lub innych ustawień sieci firmowych. W takich przypadkach można tymczasowo zezwolić na dostęp do wszystkich adresów IP, dodając 0.0.0.0 - 255.255.255.255 zakres adresów IP jako regułę zapory. Użyj tej reguły zapory tylko tymczasowo w ramach testowania i programowania połączeń. Aby uzyskać więcej informacji, zobacz konfigurowanie zapory.
Wróć do panelu Połączenia DocumentDB, rozwiń węzeł klastra i przejdź do istniejących dokumentów i kolekcji.
Otwórz menu kontekstowe kolekcji, a następnie wybierz pozycję >.
Wprowadź następujące polecenia języka zapytań bazy danych MongoDB (MQL), a następnie wybierz pozycję Uruchom wszystko. Zwróć uwagę na dane wyjściowe poleceń.
```
db.products.find({
  price: { $gt: 200 },
  sale: true
})
.sort({ price: -1 })
.limit(3)
```

Uprzątnij zasoby

Po zakończeniu pracy z klastrem usługi Azure DocumentDB możesz usunąć utworzone zasoby platformy Azure, aby nie ponosić dodatkowych opłat.

Na pasku wyszukiwania witryny Azure Portal wyszukaj i wybierz pozycję Grupy zasobów.
Na liście wybierz grupę zasobów używana dla tego szybkiego startu.
Na stronie grupa zasobów wybierz pozycję Usuń grupę zasobów.
W oknie dialogowym potwierdzenia usunięcia wprowadź nazwę grupy zasobów, aby potwierdzić, że zamierzasz ją usunąć. Na koniec wybierz pozycję Usuń , aby trwale usunąć grupę zasobów.

Co to jest usługa Azure DocumentDB?

Sprzężenie zwrotne

Czy ta strona była pomocna?

Last updated on 2025-11-19