SDK Connectivity and Client Configuration

Connecting to Cosmos DB

Creating the CosmosClient

C# (.NET SDK)

// ✅ Singleton pattern — create once, reuse everywhere
CosmosClient cosmosClient = new CosmosClient(
    accountEndpoint: "https://novasaas.documents.azure.com:443/",
    authKeyOrResourceToken: "<your-account-key>",
    clientOptions: new CosmosClientOptions
    {
        ApplicationRegion = Regions.AustraliaEast,
        ConnectionMode = ConnectionMode.Direct,
        ConsistencyLevel = ConsistencyLevel.Session
    });

// Get references (no network call)
Database database = cosmosClient.GetDatabase("novasaas");
Container container = database.GetContainer("workitems");

Java SDK

// Singleton pattern in Java
CosmosAsyncClient client = new CosmosClientBuilder()
    .endpoint("https://novasaas.documents.azure.com:443/")
    .key("<your-account-key>")
    .preferredRegions(Arrays.asList("Australia East", "UK South"))
    .directMode()
    .consistencyLevel(ConsistencyLevel.SESSION)
    .buildAsyncClient();

CosmosAsyncDatabase database = client.getDatabase("novasaas");
CosmosAsyncContainer container = database.getContainer("workitems");

Key point: GetDatabase() and GetContainer() are local proxy objects — they don’t make network calls. The first actual network call happens when you read, write, or query.

Authentication: account key vs Entra ID

Aspect	Account key	Microsoft Entra ID (RBAC)
What it is	A static key string (primary/secondary)	OAuth tokens via Azure AD/Entra
Security	Key in config = secret to protect	Token-based, no secret in code
Granularity	Full access (read/write/manage)	Fine-grained roles (data reader, contributor, etc.)
Rotation	Manual — regenerate and redeploy	Automatic via managed identities
Best for	Development, quick prototyping	Production, enterprise, zero-trust

// Entra ID authentication with DefaultAzureCredential
using Azure.Identity;

CosmosClient cosmosClient = new CosmosClient(
    accountEndpoint: "https://novasaas.documents.azure.com:443/",
    tokenCredential: new DefaultAzureCredential(),
    clientOptions: new CosmosClientOptions
    {
        ConnectionMode = ConnectionMode.Direct
    });

Ravi’s mistake: Ravi hard-coded the account key in appsettings.json and pushed it to GitHub. The key was exposed for 3 hours before someone noticed. Priya mandated Entra ID with managed identity for all production services — no keys in code, ever.

Direct mode vs gateway mode

Aspect	Direct mode (default)	Gateway mode
Protocol	TCP on ports 10000-20000	HTTPS on port 443 only
Latency	Lower — direct connection to backend replicas	Higher — extra hop through the gateway
Connection count	More connections (one per replica)	Fewer — multiplexed through gateway
Firewall friendly	Requires opening TCP port range	✅ Port 443 only — works everywhere
Best for	Production workloads needing lowest latency	Restrictive corporate firewalls, Azure Functions Consumption plan
Default in .NET	✅ Yes (Direct is default)	Must be explicitly set
Metadata routing	Client caches routing table, connects directly to partition replicas	Gateway handles all routing

// Gateway mode — for restricted environments
var options = new CosmosClientOptions
{
    ConnectionMode = ConnectionMode.Gateway,
    GatewayModeMaxConnectionLimit = 50
};

💡 Exam tip: when to choose gateway mode

Direct mode is almost always better for performance. Choose gateway mode when: (1) your firewall blocks TCP ports 10000-20000, (2) you’re running in Azure Functions Consumption plan (which has limited outbound connections), or (3) you’re behind a corporate proxy that only allows HTTPS/443. The exam loves this question — if the scenario mentions “firewall restrictions” or “port 443 only,” the answer is gateway mode.

Preferred regions

For multi-region accounts, configure the SDK to read from the nearest region:

// Single preferred region
var options = new CosmosClientOptions
{
    ApplicationRegion = Regions.AustraliaEast
};

// Multiple preferred regions (failover order)
var options = new CosmosClientOptions
{
    ApplicationPreferredRegions = new List<string>
    {
        Regions.AustraliaEast,
        Regions.UKSouth,
        Regions.BrazilSouth
    }
};

The SDK automatically routes reads to the nearest available region. If Australia East goes down, it fails over to UK South, then Brazil South.

Rule: Use ApplicationRegion (single region) OR ApplicationPreferredRegions (ordered list) — not both. Setting both throws an exception.

SDK diagnostics

When debugging performance issues, Cosmos DB diagnostics provide detailed timing:

ItemResponse<ProjectItem> response = await container.ReadItemAsync<ProjectItem>(
    "proj-001", new PartitionKey("tenant-abc"));

// Access diagnostics
CosmosDiagnostics diagnostics = response.Diagnostics;
Console.WriteLine($"Request charge: {response.RequestCharge} RU");
Console.WriteLine($"Diagnostics: {diagnostics}");

// The diagnostics JSON includes:
// - Request latency breakdown (transport, backend, retry)
// - Region contacted
// - Number of retries
// - Partition key range ID

💡 Exam tip: singleton is critical

The CosmosClient should be a singleton — one instance per Cosmos DB account for the entire application lifetime. Creating a new client per request causes: (1) TCP connection storms, (2) increased latency from connection warm-up, (3) socket exhaustion. Use dependency injection (services.AddSingleton<CosmosClient>(...)) in ASP.NET. The exam tests this pattern.

🎬 Video walkthrough

🎬 Video coming soon

SDK Connectivity — DP-420 Module 6

SDK Connectivity — DP-420 Module 6

~14 min

Flashcards

Question

Why should the CosmosClient be a singleton?

Click or press Enter to reveal answer

Answer

The CosmosClient manages TCP connections, caches routing tables, and handles retries. Creating a new client per request causes TCP connection storms, socket exhaustion, and increased latency. One instance per account, reused for the app's lifetime.

Click to flip back

💡 Show hint

Question

What protocol does Direct mode use, and what ports?

Click or press Enter to reveal answer

Answer

Direct mode uses TCP on ports 10000-20000. It connects directly to backend partition replicas, skipping the gateway hop. This gives lower latency but requires those ports to be open in your firewall.

Click to flip back

💡 Show hint

Question

When should you use Gateway mode instead of Direct mode?

Click or press Enter to reveal answer

Answer

Use Gateway mode when: (1) firewall blocks TCP ports 10000-20000, (2) running in Azure Functions Consumption plan, (3) behind a corporate proxy allowing only HTTPS/443. Gateway mode routes all traffic through port 443.

Click to flip back

💡 Show hint

Question

Can you use both ApplicationRegion and ApplicationPreferredRegions?

Click or press Enter to reveal answer

Answer

No — using both throws an exception. Use ApplicationRegion for a single preferred region, or ApplicationPreferredRegions for an ordered failover list. Never both.

Click to flip back

💡 Show hint

Knowledge check

Knowledge Check

Priya deploys NovaSaaS to a corporate environment where the firewall only allows outbound traffic on port 443. Which connection mode should she use?

ADirect mode — it's faster and the defaultBGateway mode — it uses HTTPS on port 443 onlyCSession mode — it works through any firewallDBridge mode — it tunnels TCP over HTTPS

Check Answer

Knowledge Check

Ravi creates a new CosmosClient for every HTTP request in his API. What problem will this cause?

ANo problem — the SDK is designed for per-request instantiationBTCP connection storms, socket exhaustion, and increased latencyCData corruption due to concurrent client instancesDHigher RU charges because each client uses more throughput

Check Answer

Knowledge Check

Priya's app authenticates to Cosmos DB using a managed identity in production. What's the main security advantage over account keys?

AManaged identity is faster to authenticateBNo secrets in code — tokens are issued and rotated automatically by AzureCManaged identity provides higher throughputDAccount keys can only be used in development environments

Check Answer

---

Next up: SDK CRUD & Transactions — learn all the Create, Read, Update, Delete operations plus TransactionalBatch and optimistic concurrency with ETags.