Osvědčené postupy pro sadu .NET SDK služby Azure Cosmos DB

  • Platí pro: ✅ NoSQL

Tento článek vás provede osvědčenými postupy pro používání sady .NET SDK služby Azure Cosmos DB. Pomocí těchto postupů můžete zlepšit latenci, dostupnost a zvýšit celkový výkon.

Další informace o používání sady .NET SDK od inženýra služby Azure Cosmos DB najdete v následujícím videu.

Checklist

Checkbox Předmět Description
Verze sady SDK Vždy používejte nejnovější verzi sady SDK služby Azure Cosmos DB, která je k dispozici pro optimální výkon.
Klient Singleton Pro zajištění lepšího výkonu použijte jednu instanciCosmosClient po celou dobu životnosti aplikace.
Regions Pokud je to možné, nezapomeňte aplikaci spustit ve stejné oblasti Azure jako účet služby Azure Cosmos DB, abyste snížili latenci. Povolte 2 až 4 oblasti a replikujte své účty do více oblastí, aby byla nejlepší dostupnost. Pro produkční úlohy povolte převzetí řízené službou. Při absenci této konfigurace dochází ke dočasné nedostupnosti zápisových operací po celou dobu výpadku oblasti pro zápis, protože ruční převzetí služeb při selhání se nezdaří kvůli nedostatku připojení k oblasti. Pokud chcete zjistit, jak přidat více oblastí pomocí sady .NET SDK, projděte si tento kurz.
Dostupnost a záložní řešení Nastavte ApplicationPreferredRegions nebo ApplicationRegion v sadě SDK v3 a preferredLocations v sadě SDK v2 pomocí seznamu upřednostňovaných oblastí. Během přechodu se operace zápisu posílají do aktuální zápisové oblasti a veškerá čtení se odesílají do první oblasti ze seznamu vašich upřednostňovaných oblastí. Další informace o regionálních mechanismech převzetí služeb při selhání najdete v průvodci řešením problémů s dostupností.
CPU Můžete narazit na problémy s připojením nebo dostupností kvůli nedostatku prostředků na klientském počítači. Monitorujte využití procesoru na uzlech, na kterých běží klient Azure Cosmos DB, a pokud je vysoké, škálujte nahoru/ven.
Hosting Pokud je to možné, používejte 64bitové zpracování hostitele s Windows pro zajištění nejlepšího výkonu. V případě produkčních úloh citlivých na latenci v režimu Přímý důrazně doporučujeme používat virtuální počítače s alespoň 4 jádry a pamětí 8 GB, kdykoli je to možné.
Režimy připojení Pro zajištění nejlepšího výkonu používejte přímý režim . Pokyny najdete v dokumentaci k sadě SDK V3 nebo dokumentaci k sadě SDK V2.
Sítě Pokud ke spuštění aplikace používáte virtuální počítač, povolte na svém virtuálním počítači zrychlené síťové připojení, aby se snížila latence nebo kolísání procesoru a pomohlo se s kritickými body způsobenými vysokým provozem. Můžete také zvážit použití virtuálního počítače vyšší třídy, ve kterém je maximální využití procesoru nižší než 70%.
Vyčerpání dočasných portů Pro řídké nebo sporadické spojení jsme nastavili IdleConnectionTimeout a PortReuseMode na PrivatePortPool. Tato IdleConnectionTimeout vlastnost pomáhá řídit čas, po kterém jsou nevyužitá připojení uzavřena. Tím se sníží počet nepoužívaných připojení. Ve výchozím nastavení jsou nečinná připojení trvale otevřená. Sada hodnot musí být větší nebo rovna 10 minut. Doporučujeme hodnoty mezi 20 minutami a 24 hodinami. Tato PortReuseMode vlastnost umožňuje sadě SDK používat malý fond dočasných portů pro různé cílové koncové body služby Azure Cosmos DB.
Použití async/await Vyhněte se blokování volání: Task.Result, Task.Waita Task.GetAwaiter().GetResult(). Celý zásobník volání je asynchronní, aby se daly využívat vzory async/await. Mnoho synchronních blokujících volání vede k Thread Pool starvation a zhoršení doby odezvy.
Koncové časové limity Pokud chcete získat kompletní časové limity, musíte použít parametry RequestTimeout i CancellationToken. Další informace najdete v průvodci pro řešení problémů s časovým limitem.
Logika opakování Další informace o tom, na které chyby se má znovu pokoušet a které chyby opakují sady SDK, naleznete v návrhové příručce. U účtů nakonfigurovaných s více oblastmi existují některé scénáře , kdy sada SDK automaticky opakuje pokusy v jiných oblastech. Pro podrobnosti implementace specifické pro .NET najdete ve zdrojovém úložišti sady SDK.
Ukládání názvů databází nebo kolekcí do mezipaměti Načtěte názvy svých databází a kontejnerů z konfigurace nebo je při spuštění uložte do mezipaměti. Volání jako ReadDatabaseAsync nebo ReadDocumentCollectionAsync, a CreateDatabaseQuery nebo CreateDocumentCollectionQuery mají za následek volání metadat ke službě, která spotřebovávají z limitu RU rezervovaného systémem. CreateIfNotExist pro nastavení databáze by se měla používat pouze jednou. Celkově by se tyto operace měly provádět zřídka.
Podpora pro hromadné operace Ve scénářích, kdy možná nebudete muset optimalizovat latenci, doporučujeme povolit hromadnou podporu pro ukládání velkých objemů dat.
Paralelní dotazy Sada SDK služby Azure Cosmos DB podporuje paralelní spouštění dotazů, aby se zlepšila latence a propustnost dotazů. Doporučujeme nastavit vlastnost MaxConcurrency v rámci QueryRequestsOptions na počet oddílů, které máte. Pokud neznáte počet oddílů, začněte použitím int.MaxValue, což vám poskytne nejlepší latenci. Snižujte počet, dokud nebude splňovat omezení zdrojů v daném prostředí, aby nedocházelo k nadměrnému zatížení procesoru. Nastavte MaxBufferedItemCount také očekávaný počet vrácených výsledků, abyste omezili počet předem načtených výsledků.
Strategie zpomalování při testování výkonu Při testování aplikace byste měli implementovat backoffy v RetryAfter intervalech. Dodržování odstupu pomáhá zajistit, abyste strávili minimální dobu čekáním mezi opakovanými pokusy.
Indexování Zásady indexování služby Azure Cosmos DB také umožňují určit, které cesty k dokumentu se mají zahrnout nebo vyloučit z indexování pomocí cest indexování (IndexingPolicy.IncludedPaths a IndexingPolicy.ExcludedPaths). Zajistěte, abyste vyloučili nepoužívané cesty z indexování pro rychlejší zápisy. Další informace o vytváření indexů pomocí sady SDK najdete v tématu Zásady indexování.
Velikost dokumentu Poplatek za žádost určené operace je přímo úměrný velikosti dokumentu. Doporučujeme zmenšit velikost dokumentů, protože operace s velkými dokumenty stojí více než operace s menšími dokumenty.
Zvýšení počtu vláken nebo úloh Vzhledem k tomu, že volání do služby Azure Cosmos DB se provádějí přes síť, může být potřeba měnit stupeň souběžnosti vašich požadavků, aby klientská aplikace strávila minimální dobu čekáním mezi požadavky. Pokud například používáte paralelní knihovnu úloh .NET, vytvořte pořadí stovek úloh, které čtou nebo zapisují do služby Azure Cosmos DB.
Aktivace dotazových metrik Pokud chcete více protokolování provádění back-endových dotazů, můžete povolit metriky dotazů SQL pomocí naší sady .NET SDK. Další informace o tom, jak shromažďovat metriky dotazů SQL, najdete v tématu metriky a výkon dotazů.
Protokolování sady SDK Zaznamenávejte diagnostiku Log SDK pro důležité scénáře, jako jsou výjimky nebo když požadavky překračují očekávanou latenci.
DefaultTraceListener Problémy DefaultTraceListener s výkonem v produkčních prostředích způsobují vysoké kritické body procesoru a vstupně-výstupních operací. Ujistěte se, že používáte nejnovější verze sady SDK, nebo ze své aplikace odeberte DefaultTraceListener.
Nepoužívejte žádné speciální znaky v identifikátorech. Některé znaky jsou omezené a nelze je použít v některých identifikátorech: /, \, ?, . # Obecné doporučení je nepoužívat žádné speciální znaky v identifikátorech, jako je název databáze, název kolekce, ID položky nebo klíč oddílu, aby nedošlo k neočekávanému chování.

Správa závislostí Newtonsoft.Json

Overview

Sada .NET SDK služby Azure Cosmos DB má závislost na Newtonsoft.Json pro operace serializace JSON. Tato závislost se nespravuje automaticky – v projektu musíte explicitně přidat Newtonsoft.Json přímou závislost.

Sada SDK se interně zkompiluje proti Newtonsoft.Json 10.x, která má známé ohrožení zabezpečení. I když je sada SDK technicky kompatibilní s verzí 10.x a použití Newtonsoft.Json sady SDK není náchylné k nahlášenému problému se zabezpečením, přesto doporučujeme použít verzi 13.0.3 nebo vyšší , abyste se vyhnuli potenciálním problémům nebo konfliktům zabezpečení. Verze 13.x zahrnují zásadní změny, ale vzory použití sady SDK jsou s těmito změnami kompatibilní.

Important

Tato závislost se vyžaduje i při použití System.Text.Json pro uživatelem definované typy prostřednictvím CosmosClientOptions.UseSystemTextJsonSerializerWithOptions, protože interní operace sady SDK stále používají Newtonsoft.Json pro systémové typy.

Při použití sady .NET SDK služby Azure Cosmos DB v3 vždy explicitně přidejte Newtonsoft.Json jako přímou závislost verzi 13.0.3 nebo vyšší. Nepoužívejte verzi 10.x kvůli známým ohrožením zabezpečení.

Pro projekty typu Standard .csproj

<ItemGroup>
  <PackageReference Include="Microsoft.Azure.Cosmos" Version="3.47.0" />
  <PackageReference Include="Newtonsoft.Json" Version="13.0.4" />
</ItemGroup>

Pro projekty využívající správu centrálních balíčků

Pokud váš projekt používá Directory.Packages.props:

<Project>
  <ItemGroup>
    <PackageVersion Include="Microsoft.Azure.Cosmos" Version="3.47.0" />
    <PackageVersion Include="Newtonsoft.Json" Version="13.0.4" />
  </ItemGroup>
</Project>

Řešení potíží s konflikty verzí

Chybějící referenční položka Newtonsoft.Json

Pokud dojde k chybě sestavení, například:

The Newtonsoft.Json package must be explicitly referenced with version >= 10.0.2. Please add a reference to Newtonsoft.Json or set the 'AzureCosmosDisableNewtonsoftJsonCheck' property to 'true' to bypass this check.

Tato chyba je záměrně generována cíli sestavení sady Cosmos DB SDK, aby se zajistilo, že závislost je správně nakonfigurovaná.

Řešení pro aplikace:

Přidejte explicitní odkaz na Newtonsoft.Json, jak je znázorněno v části Doporučená konfigurace výše.

Řešení pro knihovny:

Pokud vytváříte knihovnu (ne aplikaci) a chcete odložit závislost Newtonsoft.Json na uživatele vaší knihovny, můžete tuto kontrolu obejít nastavením vlastnosti MSBuild v .csproj:

<PropertyGroup>
  <AzureCosmosDisableNewtonsoftJsonCheck>true</AzureCosmosDisableNewtonsoftJsonCheck>
</PropertyGroup>

Warning

Tento obchvat použijte pouze při vytváření knihoven, kde koncoví uživatelé poskytnou závislost Newtonsoft.Json. Pro aplikace vždy přidejte explicitní odkaz.

Konflikty verzí balíčku

Pokud dojde k chybám sestavení, například:

error NU1109: Detected package downgrade: Newtonsoft.Json from 13.0.4 to centrally defined 13.0.3

Solution:

  1. Určete požadovanou verzi kontrolou, které balíčky potřebují novější verze:

    dotnet list package --include-transitive | Select-String "Newtonsoft.Json"

  2. Aktualizujte centralizovanou verzi balíčku tak, aby odpovídala nebo překročila nejvyšší požadovanou verzi:

    <PackageVersion Include="Newtonsoft.Json" Version="13.0.4" />

  3. Vyčištění a opětovné sestavení:

    dotnet clean
dotnet restore
dotnet build

Kompatibilita verzí

Následující tabulka uvádí minimální doporučené zabezpečené verze Newtonsoft.Json pro každou verzi sady SDK služby Cosmos DB. I když sada SDK může technicky pracovat s verzí 10.x, tyto verze by se nikdy neměly používat kvůli ohrožením zabezpečení.

Verze sady SDK služby Cosmos DB Minimální zabezpečená verze Doporučeno
3.47.0+ 13.0.3 13.0.4
3.54.0+ 13.0.4 13.0.4

Tip

Pokud používáte .NET Aspire 13.0.0 nebo novější, ujistěte se, že Newtonsoft.Json je ve verzi 13.0.4, abyste se vyhnuli konfliktům s komponentami Azure od Aspire.

Osvědčené postupy

  • Vždy přidat jako přímou závislost – sada SDK tuto závislost automaticky nespravuje za vás.
  • Použití verze 13.0.3 nebo vyšší – nikdy nepoužívejte 10.x bez ohledu na technickou kompatibilitu kvůli známým ohrožením zabezpečení
  • Vyžadováno i v případě System.Text.Json – Musíte zahrnout Newtonsoft.Json i při použití UseSystemTextJsonSerializerWithOptions, protože sada SDK ho interně používá pro systémové typy.
  • Explicitně připnout verzi – Nespoléhejte na přechodné řešení závislostí.
  • Upozornění monitorování – Zacházení s upozorněními downgradu balíčku NuGet (NU1109) jako s chybami v kanálech CI/CD

Zachytávání diagnostiky

Všechny odpovědi v sadě SDK, včetně CosmosException, obsahují vlastnost Diagnostics. Tato vlastnost zaznamenává všechny informace související s jedním požadavkem, včetně toho, jestli došlo k opakovaným pokusům nebo přechodným selháním.

Výsledek diagnostiky je vrácen jako řetězec. Řetězec se mění s každou verzí, protože se vylepšuje pro řešení problémů v různých scénářích. U každé verze sady SDK bude řetězec obsahovat zásadní změny formátování. Nepřepracovávejte řetězec, abyste se vyhnuli zásadním změnám. Následující ukázka kódu ukazuje, jak číst diagnostické protokoly pomocí sady .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()
}

Osvědčené postupy pro připojení HTTP

Sada .NET SDK používá HttpClient k provádění požadavků HTTP bez ohledu na nakonfigurovaný režim připojení.

  • V přímém režimu se protokol HTTP používá pro operace s metadaty.
  • V režimu brány se protokol HTTP používá pro operace roviny dat i metadat.

Jedním ze základních principů HttpClient je zajistit, že HttpClient může reagovat na změny DNS ve vašem účtu přizpůsobením délky životnosti připojení ve fondu. Pokud jsou připojení ve fondu otevřená, nereagují na změny DNS. Toto nastavení způsobí pravidelné uzavírání připojení v poolu a zajistí, že vaše aplikace reaguje na změny DNS. Naším doporučením je přizpůsobit tuto hodnotu podle vašeho režimu připojení a úlohy, abyste vyvážit výkon častých vytváření nových připojení a museli reagovat na změny DNS (dostupnost). Hodnota 5 minut by byla dobrým začátkem a v případě vlivu na výkon ji lze zvýšit, zejména pro režim brány.

Vlastního klienta HttpClient můžete propojit například takto pomocí CosmosClientOptions.HttpClientFactory:

// 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);

Pokud používáte injektování závislostí .NET, můžete proces vytváření singletonu zjednodušit.

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);
});

Osvědčené postupy při používání režimu brány

Pro zvolený režim brány zvyšte hodnotu System.Net MaxConnections pro každý hostitel. Požadavky služby Azure Cosmos DB se provádějí přes PROTOKOL HTTPS/REST při použití režimu brány. Podléhají výchozímu limitu počtu připojení na každý název hostitele nebo IP adresu. Možná budete muset nastavit MaxConnections vyšší hodnotu (od 100 do 1 000), aby klientská knihovna mohla používat více souběžných připojení ke službě Azure Cosmos DB. V sadě .NET SDK 1.8.0 a novějších je výchozí hodnota ServicePointManager.DefaultConnectionLimit 50. Pokud chcete hodnotu změnit, můžete ji nastavit CosmosClientOptions.GatewayModeMaxConnectionLimit na vyšší hodnotu.

Osvědčené postupy pro úlohy náročné na zápis

Pro úlohy, které mají vysoké zatížení vytvářením, nastavte možnost EnableContentResponseOnWrite na false. Služba už nevrací vytvořený nebo aktualizovaný prostředek do sady SDK. Za normálních okolností, protože aplikace má objekt, který se vytváří, nepotřebuje, aby jí služba objekt vracela. Hodnoty hlaviček jsou stále přístupné, například poplatek za požadavek. Zakázání odpovědi na obsah může přispět ke zlepšení výkonu, protože sada SDK už nemusí přidělovat paměť nebo serializovat tělo odpovědi. Snižuje také využití šířky pásma sítě a tím dále zvyšuje výkon.

Important

Nastavení EnableContentResponseOnWrite na false také zakáže odpověď z operace spouště.

Osvědčené postupy pro aplikace s více tenanty

Aplikace, které distribuují využití mezi více tenantů, ve kterých je každý tenant reprezentován jinou databází, kontejnerem nebo klíčem oddílu ve stejném účtu služby Azure Cosmos DB, by měly používat jednu instanci klienta. Jedna instance klienta může interagovat se všemi databázemi, kontejnery a klíči oddílů v rámci účtu, a je osvědčeným postupem použít jediný vzor.

Pokud je ale každý tenant reprezentovaný jiným účtem služby Azure Cosmos DB, je potřeba vytvořit samostatnou instanci klienta pro každý účet. Singleton vzor stále platí pro každého klienta (po celou dobu životnosti aplikace jeden klient pro každý účet), ale pokud je velký počet uživatelů, může být obtížné spravovat počet klientů. Připojení můžou zvýšit limity výpočetního prostředí a způsobit problémy s připojením.

V těchto případech se doporučuje:

  • Seznamte se s omezeními výpočetního prostředí (prostředky procesoru a připojení). Pokud je to možné, doporučujeme používat virtuální počítače s alespoň 4 jádry a 8 GB paměti.
  • Na základě omezení výpočetního prostředí určete počet instancí klienta (a proto počet tenantů), které dokáže zpracovat jedna výpočetní instance. Počet připojení, která se otevřou pro jednotlivé klienty, můžete odhadnout v závislosti na zvoleném režimu připojení.
  • Vyhodnoťte distribuci tenantů napříč instancemi. Pokud každá výpočetní instance dokáže úspěšně zpracovat určité omezené množství tenantů, vyrovnávání zatížení a směrování tenantů do různých výpočetních instancí by umožnilo škálování s rostoucím počtem tenantů.
  • U řídkých úloh zvažte použití mezipaměti Least Frequently Used jako struktury pro uložení instancí klienta a vyřazení klientů pro tenanty, kteří nejsou přistupováni v daném časovém rámci. Jednou z možností v .NET je MemoryCacheEntryOptions, kde RegisterPostEvictionCallback lze použít k vyřazení neaktivních klientů a SetSlidingExpiration lze použít k definování maximální doby uchovávání neaktivních připojení.
  • Vyhodnoťte použití režimu brány, abyste snížili počet síťových připojení.
  • Při použití režimu Direct zvažte úpravu CosmosClientOptions.IdleTcpConnectionTimeout a CosmosClientOptions.PortReuseModev konfiguraci přímého režimu tak, aby se zavřela nepoužitá připojení a zachovala objem připojení pod kontrolou.

Další kroky

Pokoušíte se naplánovat kapacitu migrace do služby Azure Cosmos DB? Informace o stávajícím databázovém clusteru můžete použít k plánování kapacity.

  • Poslední aktualizace v