SDK Connectivity and Client Configuration

Connecting to Cosmos DB

Simple explanation

Think of the CosmosClient as a phone. You set it up once (get a phone number, connect to a network), then make as many calls as you want. You don’t buy a new phone for every call — that would be expensive and slow.

Direct mode is like calling someone on their personal mobile — fast, fewer hops. Gateway mode is like calling through a hotel switchboard — works everywhere, but adds a step.

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

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

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

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

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

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?

Knowledge Check

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

Knowledge Check

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

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