Compilación de una aplicación de consola de .NET con Azure DocumentDB

En esta guía se muestra cómo crear una aplicación de consola de .NET para conectarse a un clúster de Azure DocumentDB. Configure el entorno de desarrollo, use la Azure.Identity biblioteca del SDK de Azure para .NET para autenticarse e interactuar con la base de datos para crear, consultar y actualizar documentos.

Prerrequisitos

Una suscripción de Azure
- Si no tiene ninguna suscripción a Azure, cree una cuenta gratuita

Un clúster de Azure DocumentDB existente
- Si no tiene un clúster, cree un nuevo clúster.

Use el entorno de Bash en Azure Cloud Shell. Para más información, consulte Introducción a Azure Cloud Shell.
Si prefieres ejecutar comandos de referencia CLI localmente, instala la CLI de Azure. Si estás utilizando Windows o macOS, considera ejecutar Azure CLI en un contenedor Docker. Para obtener más información, consulte Cómo ejecutar el Azure CLI en un contenedor de Docker.
- Si estás utilizando una instalación local, inicia sesión en Azure CLI utilizando el comando az login. Siga los pasos que se muestran en el terminal para completar el proceso de autenticación. Para ver otras opciones de inicio de sesión, consulte Autenticación en Azure mediante la CLI de Azure.
- En caso de que se le solicite, instale las extensiones de la CLI de Azure la primera vez que la use. Para obtener más información sobre las extensiones, consulte Uso y administración de extensiones con la CLI de Azure.
- Ejecute az version para ver la versión y las bibliotecas dependientes que están instaladas. Para actualizar a la versión más reciente, ejecute az upgrade.

La autenticación de Microsoft Entra está configurada para el clúster con el rol root concedido a la identidad.
- Para habilitar la autenticación de Microsoft Entra, revise la guía de configuración.
Versión más reciente de .NET.

Recuperación de metadatos del inquilino de Microsoft Entra

Para recuperar un token de acceso mediante la clase TokenCredential en Azure.Identity, necesita el identificador único para el inquilino de Microsoft Entra. En este paso de requisito previo, use la CLI de Azure para recuperar y registrar el tenantId valor.

Obtenga los detalles de la suscripción de Azure a la que está conectado actualmente con az account show.
```
az account show
```

El comando genera una respuesta JSON que contiene varios campos.

{
  "environmentName": "AzureCloud",
  "homeTenantId": "eeeeffff-4444-aaaa-5555-bbbb6666cccc",
  "id": "dddd3d3d-ee4e-ff5f-aa6a-bbbbbb7b7b7b",
  "isDefault": true,
  "managedByTenants": [],
  "name": "example-azure-subscription",
  "state": "Enabled",
  "tenantId": "eeeeffff-4444-aaaa-5555-bbbb6666cccc",
  "user": {
    "cloudShellID": true,
    "name": "kai@adventure-works.com",
    "type": "user"
  }
}

Registre el valor de la tenantId propiedad . Esta propiedad es el identificador único de tu tenant de Microsoft Entra y a veces se conoce como tenant ID. Este valor se usará en los pasos de una sección posterior.

Configuración de la aplicación de consola

A continuación, cree un nuevo proyecto de aplicación de consola e importe las bibliotecas necesarias para autenticarse en el clúster.

En un directorio vacío, cree una nueva aplicación de consola de .NET.
```
dotnet new console
```
Importe el Azure.Identity paquete desde NuGet.
```
dotnet add package Azure.Identity
```
A continuación, importe el MongoDB.Driver paquete.
```
dotnet add package MongoDB.Driver
```
Compila el proyecto .NET
```
dotnet build
```

Conectarse al clúster

Ahora, utilice la Azure.Identity biblioteca para obtener un TokenCredential que usará para conectarse a su clúster. El controlador oficial de MongoDB tiene una interfaz especial que se debe implementar para obtener tokens de Microsoft Entra para su uso al conectarse al clúster.

En el archivo Program.cs, agregue bloques "using" para los espacios de nombres Azure.Identity y MongoDB.Driver.
```
using Azure.Identity;
using MongoDB.Driver;
```

Cree una nueva clase en un archivo independiente que implemente todos los miembros necesarios de la MongoDB.Driver.Authentication.Oidc.IOidcCallback interfaz.

using Azure.Core;
using MongoDB.Driver.Authentication.Oidc;

internal sealed class AzureIdentityTokenHandler(
    TokenCredential credential,
    string tenantId
) : IOidcCallback
{
    private readonly string[] scopes = ["https://ossrdbms-aad.database.windows.net/.default"];

    public OidcAccessToken GetOidcAccessToken(OidcCallbackParameters parameters, CancellationToken cancellationToken)
    {
        AccessToken token = credential.GetToken(
            new TokenRequestContext(scopes, tenantId: tenantId),
            cancellationToken
        );

        return new OidcAccessToken(token.Token, token.ExpiresOn - DateTimeOffset.UtcNow);
    }

    public async Task<OidcAccessToken> GetOidcAccessTokenAsync(OidcCallbackParameters parameters, CancellationToken cancellationToken)
    {
        AccessToken token = await credential.GetTokenAsync(
            new TokenRequestContext(scopes, parentRequestId: null, tenantId: tenantId),
            cancellationToken
        );

        return new OidcAccessToken(token.Token, token.ExpiresOn - DateTimeOffset.UtcNow);
    }
}

Sugerencia

Para fines ilustrativos, esta clase se denomina AzureIdentityTokenHandler. Puede nombrar esta clase como desee. En el resto de esta guía se supone que la clase se denomina AzureIdentityTokenHandler.

Vuelva al editor del archivo Program.cs .
Cree una variable de cadena con el nombre del clúster existente. A continuación, use esa variable para crear una nueva instancia de tipo MongoUrl mediante MongoUrl.Create
```
string clusterName = "<azure-documentdb-cluster-name>";

MongoUrl url = MongoUrl.Create($"mongodb+srv://{clusterName}.global.mongocluster.cosmos.azure.com/");
```

Configure una nueva MongoSettings instancia utilizando el MongoUrl creado en los pasos anteriores y la configuración estándar recomendada para Azure DocumentDB.

MongoClientSettings settings = MongoClientSettings.FromUrl(url);

settings.UseTls = true;
settings.RetryWrites = false;
settings.MaxConnectionIdleTime = TimeSpan.FromMinutes(2);

Cree una nueva credencial de tipo DefaultAzureCredential.
```
DefaultAzureCredential credential = new();
```
Sugerencia

Puede usar cualquier credencial de tipo TokenCredential aquí. DefaultAzureCredential es la opción más fluida para los escenarios de desarrollo inicial.
Cree una nueva instancia de su clase que implementa IOidcCallback y configúrela con el ID de inquilino que registró anteriormente en esta guía.
```
string tenantId = "<microsoft-entra-tenant-id>";

AzureIdentityTokenHandler tokenHandler = new(credential, tenantId);
```
Configure las credenciales de la configuración mediante MongoCredential.CreateOidcCredential y pase la implementación de devolución de llamada del controlador personalizado.
```
settings.Credential = MongoCredential.CreateOidcCredential(tokenHandler);
```

Congela la configuración y, a continuación, crea una nueva instancia de MongoClient.

settings.Freeze();

MongoClient client = new(settings);

Console.WriteLine("Client created");

Realización de operaciones comunes

Por último, use la biblioteca oficial para realizar tareas comunes con bases de datos, colecciones y documentos. Aquí, usará las mismas clases y métodos que usaría para interactuar con MongoDB o DocumentDB para administrar las colecciones y los elementos.

Represente los documentos mediante la creación de un tipo de registro personalizado en su propio archivo.
```
public record Product(
    string id,
    string category,
    string name,
    int quantity,
    decimal price,
    bool clearance
);
```
Sugerencia

Para fines ilustrativos, esta estructura se denomina Product. En el resto de esta guía se supone que ya tiene esta estructura definida.
Vuelva al archivo Program.cs .

Obtenga un puntero a la base de datos mediante MongoClient.GetDatabase.

string databaseName = "<database-name>";

IMongoDatabase database = client.GetDatabase(databaseName);

Console.WriteLine("Database pointer created");

Después, utilice el puntero de la base de datos para obtener un puntero a la colección mediante IMongoDatabase.GetCollection<>.

string collectionName = "<collection-name>";

IMongoCollection<Product> collection = database.GetCollection<Product>(collectionName);

Console.WriteLine("Collection pointer created");

Cree y actualice/inserte (upsert) dos documentos utilizando el método IMongoCollection<>.ReplaceOneAsync.

Product classicSurfboard = new(
    id: "bbbbbbbb-1111-2222-3333-cccccccccccc",
    category: "gear-surf-surfboards",
    name: "Kiama Classic Surfboard",
    quantity: 25,
    price: 790.00m,
    clearance: false
);

Product paddleKayak = new(
    id: "cccccccc-2222-3333-4444-dddddddddddd",
    category: "gear-paddle-kayaks",
    name: "Lastovichka Paddle Kayak",
    quantity: 10,
    price: 599.99m,
    clearance: true
);

await collection.ReplaceOneAsync<Product>(
    doc => doc.id == classicSurfboard.id,
    classicSurfboard,
    new ReplaceOptions { IsUpsert = true }
);

Console.WriteLine($"Upserted document:\t{classicSurfboard.id}");

await collection.ReplaceOneAsync<Product>(
    doc => doc.id == paddleKayak.id,
    paddleKayak,
    new ReplaceOptions { IsUpsert = true }
);

Console.WriteLine($"Upserted document:\t{paddleKayak.id}");

Lea un único documento de la colección mediante IMongoCollection<>.Find y IFindFluent<,>.SingleAsync. Use un filtro para especificar el documento específico que desea buscar.

Product document = await collection.Find(
    doc => doc.id == "cccccccc-2222-3333-4444-dddddddddddd"
).SingleAsync();

Console.WriteLine($"Found document:\t{document.name}");

Consulta de todos los documentos que coinciden con un filtro mediante el mismo Find método. Use un filtro para definir una propiedad específica (como category) y un valor específico (como gear-surf-surfboards). Enumerar los resultados mediante IFindFluent<,>.ToListAsync.
```
List<Product> documents = await collection.Find(
    doc => doc.category == "gear-surf-surfboards"
).ToListAsync();

foreach (Product doc in documents)
{
    Console.WriteLine($"Queried document:\t{doc}");
}
```

Elimine un documento específico de la colección mediante IMongoCollection<>.DeleteOneAsync y un filtro.

await collection.DeleteOneAsync(
    doc => doc.id == "bbbbbbbb-1111-2222-3333-cccccccccccc"
);

Console.WriteLine($"Deleted document");

Guarde todos los archivos de código en el proyecto.
Ejecución del proyecto mediante dotnet run
```
dotnet run
```

Observe la salida de la aplicación en ejecución.

Client created
Database pointer created
Collection pointer created
Upserted document:      bbbbbbbb-1111-2222-3333-cccccccccccc
Upserted document:      cccccccc-2222-3333-4444-dddddddddddd
Found document: Lastovichka Paddle Kayak
Queried document:       Product { id = bbbbbbbb-1111-2222-3333-cccccccccccc, category = gear-surf-surfboards, name = Kiama Classic Surfboard, quantity = 25, price = 790.00, clearance = False }
Deleted document

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2025-11-19