Share 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 de latentie en 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.

Controlelijst

Ingeschakeld 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 voor 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, waar mogelijk om de latentie te verminderen. Schakel 2-4 regio's in en repliceer uw accounts in meerdere regio's voor de beste beschikbaarheid. Schakel servicebeheerde failover in voor productieworkloads. Als deze configuratie ontbreekt, verliest het account de beschikbaarheid van schrijfbewerkingen gedurende de hele duur van de uitval in de schrijfregio, omdat handmatige failover niet lukt vanwege een gebrek aan regioconnectiviteit. Voor meer informatie over het toevoegen van meerdere regio's met behulp van de .NET SDK, gaat u naar hier
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 failovermechanismen.
CPU Er kunnen connectiviteits-/beschikbaarheidsproblemen optreden vanwege een gebrek aan resources op uw clientcomputer. Bewaak uw CPU-gebruik op knooppunten waarop de Azure Cosmos DB-client wordt uitgevoerd 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 4-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 in op uw VM om knelpunten als gevolg van hoog verkeer te verhelpen en de latentie of CPU-jitter te verminderen. U kunt ook overwegen om een hogere virtuele machine te gebruiken waarbij het maximale CPU-gebruik lager is dan 70%.
Tijdelijke poortuitputting Voor sparse of sporadische verbindingen stellen we en IdleConnectionTimeoutPortReuseMode in op PrivatePortPool. De IdleConnectionTimeout eigenschap helpt bij het bepalen van de tijd waarna ongebruikte verbindingen worden gesloten. Dit vermindert het aantal ongebruikte verbindingen. Niet-actieve verbindingen worden standaard voor onbepaalde tijd geopend. De waarde die is ingesteld, moet groter zijn dan of gelijk zijn aan 10 minuten. We raden waarden tussen 20 minuten en 24 uur aan. Met de PortReuseMode eigenschap kan de SDK een kleine groep tijdelijke poorten gebruiken voor verschillende Azure Cosmos DB-doeleindpunten.
Async/Await gebruiken Vermijd het blokkeren van aanroepen: Task.Result, Task.Waiten Task.GetAwaiter().GetResult(). De volledige aanroepstack is asynchroon om te profiteren van asynchrone/wachtpatronen . Veel synchrone blokkeringsaanroepen leiden tot verhongering van threadpools en verminderde reactietijden.
End-to-end time-outs Als u end-to-end-time-outs wilt ophalen, moet u zowel parameters als RequestTimeoutCancellationToken parameters gebruiken. Ga voor meer informatie naar onze probleemoplossingsgids voor time-outs.
Logica voor opnieuw proberen Zie de ontwerphandleiding voor meer informatie over welke fouten opnieuw moeten worden geprobeerd en welke opnieuw worden geprobeerd door SDK's. Voor accounts die zijn geconfigureerd met meerdere regio's, zijn er enkele scenario's waarin de SDK automatisch opnieuw wordt geprobeerd in andere regio's. Voor .NET-specifieke implementatiedetails gaat u naar de SDK-bronopslagplaats.
Database-/verzamelingsnamen in cache opslaan Haal de namen van uw databases en containers op uit de configuratie of sla ze bij het begin in de cache op. Aanroepen zoals ReadDatabaseAsync of ReadDocumentCollectionAsync en CreateDatabaseQuery of CreateDocumentCollectionQuery resulteren in aanroepen van metagegevens naar de service, die de door het systeem gereserveerde RU-limiet verbruiken. CreateIfNotExist mag ook slechts eenmaal worden gebruikt voor het instellen van de database. Over het algemeen moeten deze bewerkingen niet vaak worden uitgevoerd.
Bulkondersteuning In scenario's waarin u mogelijk niet hoeft te optimaliseren voor latentie, raden we u aan bulksgewijs ondersteuning in te schakelen voor het dumpen van grote hoeveelheden gegevens.
Parallelle query's De Azure Cosmos DB SDK ondersteunt het parallel uitvoeren van query's voor een betere latentie en doorvoer van uw query's. U wordt aangeraden de MaxConcurrency eigenschap binnen de QueryRequestsOptions in te stellen op het aantal partities dat u hebt. Als u niet op de hoogte bent van het aantal partities, begint u met het gebruik int.MaxValuevan , waarmee u de beste latentie krijgt. Verlaag vervolgens het aantal totdat het voldoet aan de resourcebeperkingen van de omgeving om problemen met hoog CPU-gebruik te voorkomen. Stel ook de MaxBufferedItemCount in op het verwachte aantal geretourneerde resultaten om het aantal vooraf geïnstalleerde resultaten te beperken.
Uitstel van prestatietests Wanneer u tests uitvoert voor uw toepassing, moet u met RetryAfter intervallen uitstel implementeren. Het respecteren van de uitsteltijd zorgt ervoor dat u een minimale hoeveelheid tijd doorbrengt met wachten tussen nieuwe pogingen.
Indexeren Met het indexeringsbeleid van Azure Cosmos DB kunt u ook opgeven welke documentpaden u wilt opnemen of uitsluiten 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 .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. We raden u aan de grootte van uw documenten te verkleinen, omdat bewerkingen op 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-taakparallelbibliotheek gebruikt, maakt u honderden taken die lezen uit 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 openstaande scenario's, zoals uitzonderingen of wanneer aanvragen een verwachte latentie overschrijden.
DefaultTraceListener De DefaultTraceListener zorgt voor prestatieproblemen in productieomgevingen die hoge CPU- en I/O-knelpunten 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 bepaalde id's: '/', '\', '?', '#'. De algemene aanbeveling is om geen speciale tekens in id's zoals databasenaam, verzamelingsnaam, item-id of partitiesleutel te gebruiken 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 ene aanvraag, inclusief of er nieuwe pogingen zijn gedaan of eventuele tijdelijke fouten.

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 te voorkomen dat wijzigingen fouten veroorzaken. 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 geconfigureerde connectiviteitsmodus. In de directe modus wordt HTTP gebruikt voor metagegevensbewerkingen en in de gatewaymodus voor zowel gegevensvlak- als metagegevensbewerkingen. Een van de basisprincipes van HttpClient is ervoor te zorgen dat de HttpClient kan reageren op DNS-wijzigingen in uw account door de levensduur van de gegroepeerde verbinding aan te passen. Zolang gegroepeerde verbindingen open blijven, reageren ze niet op DNS-wijzigingen. Deze instelling dwingt af dat gegroepeerde verbindingen periodiek worden 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 impact op de prestaties van het regelmatig maken van nieuwe verbindingen te balanceren met de noodzaak om te reageren op DNS-wijzigingen (beschikbaarheid). Een waarde van 5 minuten is een goed begin dat kan worden verhoogd als dit van invloed is op de prestaties, met name voor de gatewaymodus.

U kunt uw aangepaste HttpClient injecteren via CosmosClientOptions.HttpClientFactory, bijvoorbeeld:

// 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 gedaan 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 1000), zodat de clientbibliotheek meerdere gelijktijdige verbindingen met Azure Cosmos DB kan gebruiken. In .NET SDK 1.8.0 en hoger is de standaardwaarde voor ServicePointManager.DefaultConnectionLimit 50. Als u de waarde wilt wijzigen, kunt u instellen CosmosClientOptions.GatewayModeMaxConnectionLimit op een hogere waarde.

Best practices voor werkbelastingen met veel schrijfbewerkingen

Voor workloads met zware nettoladingen stelt u de EnableContentResponseOnWrite aanvraagoptie in op false. De service retourneert de gemaakte of bijgewerkte resource niet meer naar de SDK. Normaal gesproken, omdat de toepassing het object bevat dat wordt gemaakt, heeft deze de service niet nodig om deze te retourneren. De headerwaarden zijn nog steeds toegankelijk, zoals aanvraagkosten. Het uitschakelen van de inhoudsreactie kan helpen de prestaties te verbeteren, omdat de SDK niet langer geheugen hoeft toe te wijzen of de hoofdtekst van het antwoord te serialiseren. Het vermindert ook het gebruik van de netwerkbandbreedte om de prestaties verder te verbeteren.

Belangrijk

Als u instelt EnableContentResponseOnWrite op false , 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 clientexemplaar gebruiken. Eén clientexemplaar kan communiceren met alle databases, containers en partitiesleutels binnen een account. Het wordt aanbevolen om het singleton-patroon te gebruiken.

Wanneer elke tenant echter wordt vertegenwoordigd door een ander Azure Cosmos DB-account, moet u per account een afzonderlijk clientexemplaar maken. Het singleton-patroon is nog steeds van toepassing op elke client (één client voor elk account 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.

In deze gevallen wordt het aanbevolen om het volgende te doen:

  • Inzicht in de beperkingen van de rekenomgeving (CPU en verbindingsresources). We raden u aan om waar mogelijk VM's met ten minste 4 kernen en 8 GB geheugen te gebruiken.
  • Bepaal op basis van de beperkingen van de rekenomgeving het aantal clientexemplaren (en dus 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.
  • Tenantdistributie over exemplaren evalueren. Als elk rekenproces een bepaalde beperkte hoeveelheid tenants kan afhandelen, kunnen de taakverdeling en routering van tenants naar verschillende rekeninstanties worden geschaald naarmate het aantal tenants toeneemt.
  • Voor sparse workloads kunt u overwegen om een minst vaak gebruikte cache te gebruiken als de structuur voor het opslaan van de clientexemplaren en het verwijderen van clients 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 voor het bewaren van inactieve verbindingen te definiëren.
  • Evalueer met behulp 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

Zie Prestatie- en schaaltests met Azure Cosmos DB voor een voorbeeldtoepassing die wordt gebruikt om Azure Cosmos DB te evalueren voor scenario's met hoge prestaties op enkele clientcomputers.

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

Probeert u capaciteitsplanning uit te voeren voor een migratie naar Azure Cosmos DB? U kunt informatie over uw bestaande databasecluster gebruiken voor capaciteitsplanning.