Delen via

Aanbevolen procedures voor Azure Cosmos DB .NET SDK

  • Artikel

VAN TOEPASSING OP: NoSQL

In dit artikel worden de aanbevolen procedures beschreven voor het gebruik van de Azure Cosmos DB .NET SDK. Als u deze procedures volgt, kunt u uw latentie, beschikbaarheid verbeteren en de algehele prestaties verbeteren.

Bekijk de onderstaande video voor meer informatie over het gebruik van de .NET SDK van een Azure Cosmos DB-engineer.

Checklijst

Geselecteerd Onderwerp Details/koppelingen
SDK-versie Gebruik altijd de nieuwste versie van de Azure Cosmos DB SDK die beschikbaar is voor optimale prestaties.
Singleton-client Gebruik één exemplaar van CosmosClient de levensduur van uw toepassing voor betere prestaties.
Regio's Zorg ervoor dat u uw toepassing uitvoert in dezelfde Azure-regio als uw Azure Cosmos DB-account, indien mogelijk om de latentie te verminderen. Schakel 2-4 regio's in en repliceer uw accounts in meerdere regio's voor de beste beschikbaarheid. Voor productieworkloads schakelt u door de service beheerde failover in. Bij afwezigheid van deze configuratie ondervindt het account verlies van schrijf beschikbaarheid voor alle duur van de storing in de schrijfregio, omdat handmatige failover niet slaagt vanwege een gebrek aan regioverbinding. Als u wilt weten hoe u meerdere regio's toevoegt met behulp van de .NET SDK, gaat u hier naar
Beschikbaarheid en failovers Stel de ApplicationPreferredRegions of ApplicationRegion in de v3 SDK in en de PreferredLocations in de v2 SDK met behulp van de lijst met voorkeursregio's. Tijdens failovers worden schrijfbewerkingen verzonden naar de huidige schrijfregio en worden alle leesbewerkingen verzonden naar de eerste regio in de lijst met voorkeursregio's. Zie de handleiding voor het oplossen van problemen met beschikbaarheid voor meer informatie over regionale failovermechanica.
CPU Mogelijk ondervindt u problemen met connectiviteit/beschikbaarheid vanwege een gebrek aan resources op uw clientcomputer. Bewaak uw CPU-gebruik op knooppunten met de Azure Cosmos DB-client en schaal omhoog/uit als het gebruik hoog is.
Hosting Gebruik waar mogelijk windows 64-bits hostverwerking voor de beste prestaties. Voor latentiegevoelige productieworkloads in de directe modus raden we u ten zeerste aan om waar mogelijk ten minste vier kernen en 8 GB geheugen-VM's te gebruiken.
Connectiviteitsmodi Gebruik de directe modus voor de beste prestaties. Zie de V3 SDK-documentatie of de V2 SDK-documentatie voor instructies over hoe u dit doet.
Netwerken Als u een virtuele machine gebruikt om uw toepassing uit te voeren, schakelt u Versneld netwerken op uw VIRTUELE machine in om te helpen bij knelpunten vanwege hoog verkeer en om latentie of CPU-jitter te verminderen. U kunt ook overwegen een hogere virtuele machine te gebruiken waarbij het maximale CPU-gebruik lager is dan 70%.
Tijdelijke poortuitputting Voor sparse- of sporadische verbindingen stellen we de IdleConnectionTimeout en PortReuseMode in op PrivatePortPool. De IdleConnectionTimeout eigenschap helpt bij het beheren van de tijd waarna ongebruikte verbindingen worden gesloten. Dit vermindert het aantal ongebruikte verbindingen. Standaard worden niet-actieve verbindingen voor onbepaalde tijd geopend. De waardeset moet groter zijn dan of gelijk zijn aan 10 minuten. We raden waarden tussen 20 minuten en 24 uur aan. Met PortReuseMode de eigenschap kan de SDK een kleine groep tijdelijke poorten gebruiken voor verschillende Azure Cosmos DB-doeleindpunten.
Async/Await gebruiken Voorkom het blokkeren van aanroepen: Task.Result, Task.Waiten Task.GetAwaiter().GetResult(). De volledige aanroepstack is asynchroon om te profiteren van asynchrone/wachtende patronen. Veel synchrone blokkeringsaanroepen leiden tot starvatie van threadgroepen en verminderde reactietijden.
End-to-end time-outs Als u end-to-end time-outs wilt ophalen, moet u zowel als RequestTimeout CancellationToken parameters gebruiken. Raadpleeg onze gids voor het oplossen van problemen met time-outs voor meer informatie.
Logica voor opnieuw proberen Zie de ontwerphandleiding voor meer informatie over welke fouten u opnieuw moet proberen en welke fouten opnieuw worden geprobeerd door SDK's. Voor accounts die zijn geconfigureerd met meerdere regio's, zijn er enkele scenario's waarbij de SDK automatisch opnieuw wordt geprobeerd in andere regio's. Ga naar de SDK-bronopslagplaats voor specifieke implementatiedetails voor .NET.
Namen van databases/verzamelingen opslaan in cache Haal de namen van uw databases en containers op uit de configuratie of cache ze op het begin. Aanroepen zoals ReadDatabaseAsync of ReadDocumentCollectionAsync en CreateDatabaseQuery of CreateDocumentCollectionQuery resulteren in metagegevens aanroepen naar de service, die de limiet voor de door het systeem gereserveerde RU verbruiken. CreateIfNotExist mag ook slechts eenmaal worden gebruikt voor het instellen van de database. Over het algemeen moeten deze bewerkingen onregelmatig worden uitgevoerd.
Bulkondersteuning In scenario's waarin u mogelijk niet hoeft te optimaliseren voor latentie, wordt u aangeraden bulksgewijs ondersteuning in te schakelen voor het dumpen van grote hoeveelheden gegevens.
Parallelle query's De Azure Cosmos DB SDK biedt ondersteuning voor het parallel uitvoeren van query's voor betere latentie en doorvoer voor uw query's. U wordt aangeraden de MaxConcurrency eigenschap in te stellen op het QueryRequestsOptions aantal partities dat u hebt. Als u niet op de hoogte bent van het aantal partities, begint u met het gebruik int.MaxValuevan , wat u de beste latentie geeft. Verlaag vervolgens het aantal totdat deze past bij de resourcebeperkingen van de omgeving om hoge CPU-problemen te voorkomen. Stel ook het MaxBufferedItemCount verwachte aantal resultaten in dat wordt geretourneerd om het aantal vooraf gemaakte resultaten te beperken.
Uitstel van prestaties testen Wanneer u tests uitvoert op uw toepassing, moet u tussenpozen back-offs RetryAfter implementeren. Het respecteren van de uitstel helpt ervoor te zorgen dat u een minimale hoeveelheid tijd besteedt aan het wachten tussen nieuwe pogingen.
Indexeren Met het indexeringsbeleid van Azure Cosmos DB kunt u ook opgeven welke documentpaden moeten worden opgenomen of uitgesloten van indexering met behulp van indexeringspaden (IndexingPolicy.IncludedPaths en IndexingPolicy.ExcludedPaths). Zorg ervoor dat u ongebruikte paden uitsluit van indexering voor snellere schrijfbewerkingen. Zie prestatietips voor .NET SDK v3 voor meer informatie over het maken van indexen met behulp van de SDK.
Documentgrootte De aanvraagkosten van een opgegeven bewerking komen rechtstreeks overeen met de grootte van het document. Het is raadzaam om de grootte van uw documenten te verkleinen als bewerkingen voor grote documenten meer kosten dan bewerkingen op kleinere documenten.
Het aantal threads/taken verhogen Omdat aanroepen naar Azure Cosmos DB via het netwerk worden uitgevoerd, moet u mogelijk de mate van gelijktijdigheid van uw aanvragen variëren, zodat de clienttoepassing zo min mogelijk tijd besteedt aan het wachten tussen aanvragen. Als u bijvoorbeeld de .NET Task Parallel Library gebruikt, maakt u de volgorde van honderden taken die lezen van of schrijven naar Azure Cosmos DB.
Metrische querygegevens inschakelen Voor meer logboekregistratie van uw back-endquery-uitvoeringen kunt u METrische SQL-querygegevens inschakelen met behulp van onze .NET SDK. Zie metrische querygegevens en prestaties voor meer informatie over het verzamelen van metrische sql-querygegevens.
SDK-logboekregistratie Logboek-SDK-diagnostische gegevens voor uitstekende scenario's, zoals uitzonderingen of wanneer aanvragen een verwachte latentie overschrijden.
DefaultTraceListener De DefaultTraceListener veroorzaakt prestatieproblemen in productieomgevingen die een hoog CPU- en I/O-knelpunt veroorzaken. Zorg ervoor dat u de nieuwste SDK-versies gebruikt of verwijder de DefaultTraceListener uit uw toepassing
Vermijd het gebruik van speciale tekens in id's Sommige tekens zijn beperkt en kunnen niet worden gebruikt in sommige id's: '/', '\', '?', '#'. De algemene aanbeveling is om geen speciale tekens te gebruiken in id's zoals databasenaam, verzamelingsnaam, item-id of partitiesleutel om onverwacht gedrag te voorkomen.

Diagnostische gegevens vastleggen

Alle antwoorden in de SDK, inclusief CosmosException, hebben een Diagnostics eigenschap. Deze eigenschap registreert alle informatie met betrekking tot de enkele aanvraag, inclusief of er nieuwe pogingen of tijdelijke fouten zijn opgetreden.

De diagnostische gegevens worden geretourneerd als een tekenreeks. De tekenreeks verandert met elke versie, omdat deze is verbeterd voor het oplossen van problemen met verschillende scenario's. Bij elke versie van de SDK heeft de tekenreeks belangrijke wijzigingen in de opmaak. Parseert de tekenreeks niet om wijzigingen die fouten veroorzaken te voorkomen. In het volgende codevoorbeeld ziet u hoe u diagnostische logboeken leest met behulp van de .NET SDK:

try
{
    ItemResponse<Book> response = await this.Container.CreateItemAsync<Book>(item: testItem);
    if (response.Diagnostics.GetClientElapsedTime() > ConfigurableSlowRequestTimeSpan)
    {
        // Log the response.Diagnostics.ToString() and add any additional info necessary to correlate to other logs 
    }
}
catch (CosmosException cosmosException)
{
    // Log the full exception including the stack trace with: cosmosException.ToString()
    
    // The Diagnostics can be logged separately if required with: cosmosException.Diagnostics.ToString()
}

// When using Stream APIs
ResponseMessage response = await this.Container.CreateItemStreamAsync(partitionKey, stream);
if (response.Diagnostics.GetClientElapsedTime() > ConfigurableSlowRequestTimeSpan || !response.IsSuccessStatusCode)
{
    // Log the diagnostics and add any additional info necessary to correlate to other logs with: response.Diagnostics.ToString()
}

Aanbevolen procedures voor HTTP-verbindingen

De .NET SDK gebruikt HttpClient om HTTP-aanvragen uit te voeren, ongeacht de connectiviteitsmodus die is geconfigureerd. Http in de directe modus wordt gebruikt voor metagegevensbewerkingen en in de gatewaymodus die wordt gebruikt voor zowel gegevensvlak- als metagegevensbewerkingen. Een van de basisprincipes van HttpClient is ervoor te zorgen dat het HttpClient kan reageren op DNS-wijzigingen in uw account door de levensduur van de poolverbinding aan te passen. Zolang gegroepeerde verbindingen open blijven, reageren ze niet op DNS-wijzigingen. Met deze instelling worden gegroepeerde verbindingen periodiek gesloten , zodat uw toepassing reageert op DNS-wijzigingen. We raden u aan deze waarde aan te passen op basis van uw connectiviteitsmodus en workload om de prestatieimpact van het vaak maken van nieuwe verbindingen te verdelen, waarbij u moet reageren op DNS-wijzigingen (beschikbaarheid). Een waarde van 5 minuten is een goede start die kan worden verhoogd als dit van invloed is op de prestaties, met name voor de gatewaymodus.

U kunt uw aangepaste HttpClient injecteren via CosmosClientOptions.HttpClientFactorybijvoorbeeld:

// Use a Singleton instance of the SocketsHttpHandler, which you can share across any HttpClient in your application
SocketsHttpHandler socketsHttpHandler = new SocketsHttpHandler();
// Customize this value based on desired DNS refresh timer
socketsHttpHandler.PooledConnectionLifetime = TimeSpan.FromMinutes(5);

CosmosClientOptions cosmosClientOptions = new CosmosClientOptions()
{
    // Pass your customized SocketHttpHandler to be used by the CosmosClient
    // Make sure `disposeHandler` is `false`
    HttpClientFactory = () => new HttpClient(socketsHttpHandler, disposeHandler: false)
};

// Use a Singleton instance of the CosmosClient
return new CosmosClient("<connection-string>", cosmosClientOptions);

Als u .NET-afhankelijkheidsinjectie gebruikt, kunt u het Singleton-proces vereenvoudigen:

SocketsHttpHandler socketsHttpHandler = new SocketsHttpHandler();
// Customize this value based on desired DNS refresh timer
socketsHttpHandler.PooledConnectionLifetime = TimeSpan.FromMinutes(5);
// Registering the Singleton SocketsHttpHandler lets you reuse it across any HttpClient in your application
services.AddSingleton<SocketsHttpHandler>(socketsHttpHandler);

// Use a Singleton instance of the CosmosClient
services.AddSingleton<CosmosClient>(serviceProvider =>
{
    SocketsHttpHandler socketsHttpHandler = serviceProvider.GetRequiredService<SocketsHttpHandler>();
    CosmosClientOptions cosmosClientOptions = new CosmosClientOptions()
    {
        HttpClientFactory = () => new HttpClient(socketsHttpHandler, disposeHandler: false)
    };

    return new CosmosClient("<connection-string>", cosmosClientOptions);
});

Aanbevolen procedures bij het gebruik van de gatewaymodus

Verhoog System.Net MaxConnections per host wanneer u de gatewaymodus gebruikt. Azure Cosmos DB-aanvragen worden uitgevoerd via HTTPS/REST wanneer u de gatewaymodus gebruikt. Ze zijn onderworpen aan de standaardverbindingslimiet per hostnaam of IP-adres. Mogelijk moet u instellen MaxConnections op een hogere waarde (van 100 tot en met 1000), zodat de clientbibliotheek meerdere gelijktijdige verbindingen met Azure Cosmos DB kan gebruiken. In .NET SDK 1.8.0 en hoger is de standaardwaarde ServicePointManager.DefaultConnectionLimit 50. Als u de waarde wilt wijzigen, kunt u instellen CosmosClientOptions.GatewayModeMaxConnectionLimit op een hogere waarde.

Best practices voor schrijfintensieve workloads

Voor workloads met zware nettoladingen kunt u de EnableContentResponseOnWrite aanvraagoptie instellen op false. De service retourneert de gemaakte of bijgewerkte resource niet meer naar de SDK. Normaal gesproken heeft de toepassing het object dat wordt gemaakt, niet nodig om het te retourneren. De headerwaarden zijn nog steeds toegankelijk, zoals een aanvraagkosten. Als u het antwoord op inhoud uitschakelt, kunt u de prestaties verbeteren, omdat de SDK geen geheugen meer hoeft toe te wijzen of de hoofdtekst van het antwoord serialiseert. Het vermindert ook het netwerkbandbreedtegebruik om de prestaties verder te helpen.

Belangrijk

false Als u deze instelling EnableContentResponseOnWrite instelt, wordt ook het antwoord van een triggerbewerking uitgeschakeld.

Aanbevolen procedures voor toepassingen met meerdere tenants

Toepassingen die het gebruik verdelen over meerdere tenants waarbij elke tenant wordt vertegenwoordigd door een andere database, container of partitiesleutel binnen hetzelfde Azure Cosmos DB-account , moeten één clientexemplaren gebruiken. Eén clientexemplaren kunnen communiceren met alle databases, containers en partitiesleutels binnen een account en het is raadzaam om het singleton-patroon te gebruiken.

Wanneer elke tenant echter wordt vertegenwoordigd door een ander Azure Cosmos DB-account, moet u een afzonderlijk clientexemplaren per account maken. Het singleton-patroon is nog steeds van toepassing op elke client (één client voor elke rekening voor de levensduur van de toepassing), maar als het volume van tenants hoog is, kan het aantal clients moeilijk te beheren zijn. Verbindingen kunnen groter worden dan de limieten van de rekenomgeving en connectiviteitsproblemen veroorzaken.

Het wordt aanbevolen in deze gevallen het volgende te doen:

  • Inzicht in de beperkingen van de rekenomgeving (CPU en verbindingsresources). We raden u aan om vm's met ten minste 4 kernen en 8 GB geheugen te gebruiken, indien mogelijk.
  • Bepaal op basis van de beperkingen van de rekenomgeving het aantal clientexemplaren (en daarom het aantal tenants) dat één rekenproces kan verwerken. U kunt een schatting maken van het aantal verbindingen dat per client wordt geopend, afhankelijk van de gekozen verbindingsmodus.
  • Evalueer tenantdistributie over exemplaren. Als elk rekenproces een bepaalde beperkte hoeveelheid tenants, taakverdeling en routering van tenants naar verschillende rekeninstanties kan afhandelen, is schalen mogelijk naarmate het aantal tenants toeneemt.
  • Voor sparse-workloads kunt u overwegen om een minst gebruikte cache te gebruiken als de structuur voor het opslaan van de clientexemplaren en clients te verwijderen voor tenants die niet binnen een tijdvenster zijn geopend. Een optie in .NET is MemoryCacheEntryOptions, waarbij RegisterPostEvictionCallback kan worden gebruikt om inactieve clients te verwijderen en SetSlidingExpiration kan worden gebruikt om de maximale tijd te definiëren voor het opslaan van inactieve verbindingen.
  • Evalueer het gebruik van de gatewaymodus om het aantal netwerkverbindingen te verminderen.
  • Wanneer u de directe modus gebruikt, kunt u CosmosClientOptions.IdleTcpConnectionTimeout en CosmosClientOptions.PortReuseMode aanpassen in de configuratie van de directe modus om ongebruikte verbindingen te sluiten en het volume van verbindingen onder controle te houden.

Volgende stappen

Voor een voorbeeldtoepassing die wordt gebruikt om Azure Cosmos DB te evalueren voor scenario's met hoge prestaties op een paar clientcomputers, raadpleegt u Prestatie- en schaaltests met Azure Cosmos DB.

Zie Partitioneren en schalen in Azure Cosmos DB voor meer informatie over het ontwerpen van uw toepassing voor schaalaanpassing en hoge prestaties.

Wilt u capaciteitsplanning uitvoeren voor een migratie naar Azure Cosmos DB? U kunt informatie over uw bestaande databasecluster gebruiken voor capaciteitsplanning.