Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Documentation: Adds additional remarks to CosmosClient #3891

Merged
6 commits merged into from
Jun 8, 2023
Merged

Documentation: Adds additional remarks to CosmosClient #3891

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
4cac2d4
CosmosClient documentation improvements
rinatmini Jun 2, 2023
f2a0fba
Cref fix
rinatmini Jun 2, 2023
f411f35
Link fix
rinatmini Jun 5, 2023
dbcc8f6
Documentation fix
rinatmini Jun 8, 2023
a587fe8
Typo fix
rinatmini Jun 8, 2023
9793ca9
Merge branch 'master' into users/rinatmini/cosmosclientdocfix
ealsur Jun 8, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 19 additions & 1 deletion Microsoft.Azure.Cosmos/src/CosmosClient.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -92,6 +92,9 @@ namespace Microsoft.Azure.Cosmos
/// ]]>
/// </code>
/// </example>
/// <remarks>
/// The returned not-initialized reference doesn't guarantee credentials or connectivity validations because creation doesn't make any network calls
/// </remarks>
/// <seealso cref="CosmosClientOptions"/>
/// <seealso cref="Fluent.CosmosClientBuilder"/>
/// <seealso href="https://docs.microsoft.com/azure/cosmos-db/performance-tips">Performance Tips</seealso>
Expand Down Expand Up @@ -179,6 +182,9 @@ protected CosmosClient()
/// ]]>
/// </code>
/// </example>
/// <remarks>
/// The returned reference doesn't guarantee credentials or connectivity validations because creation doesn't make any network calls.
/// </remarks>
/// <seealso cref="CosmosClientOptions"/>
/// <seealso cref="Fluent.CosmosClientBuilder"/>
/// <seealso href="https://docs.microsoft.com/azure/cosmos-db/performance-tips">Performance Tips</seealso>
Expand Down Expand Up @@ -221,6 +227,9 @@ public CosmosClient(
/// ]]>
/// </code>
/// </example>
/// <remarks>
/// The returned reference doesn't guarantee credentials or connectivity validations because creation doesn't make any network calls.
/// </remarks>
/// <seealso cref="CosmosClientOptions"/>
/// <seealso cref="Fluent.CosmosClientBuilder"/>
/// <seealso href="https://docs.microsoft.com/azure/cosmos-db/performance-tips">Performance Tips</seealso>
Expand Down Expand Up @@ -274,7 +283,10 @@ public CosmosClient(
/// <seealso cref="Fluent.CosmosClientBuilder"/>
/// <seealso href="https://docs.microsoft.com/azure/cosmos-db/performance-tips">Performance Tips</seealso>
/// <seealso href="https://docs.microsoft.com/azure/cosmos-db/troubleshoot-dot-net-sdk">Diagnose and troubleshoot issues</seealso>
/// <remarks>AzureKeyCredential enables changing/updating master-key/ResourceToken whle CosmosClient is still in use.</remarks>
/// <remarks>
/// AzureKeyCredential enables changing/updating master-key/ResourceToken whle CosmosClient is still in use.
/// The returned reference doesn't guarantee credentials or connectivity validations because creation doesn't make any network calls.
/// </remarks>
public CosmosClient(
string accountEndpoint,
AzureKeyCredential authKeyOrResourceTokenCredential,
Expand All @@ -292,6 +304,9 @@ public CosmosClient(
/// of the application which enables efficient connection management and performance. Please refer to the
/// <see href="https://docs.microsoft.com/azure/cosmos-db/performance-tips">performance guide</see>.
/// </summary>
/// <remarks>
/// The returned reference doesn't guarantee credentials or connectivity validations because creation doesn't make any network calls.
/// </remarks>
/// <param name="accountEndpoint">The cosmos service endpoint to use.</param>
/// <param name="tokenCredential"><see cref="TokenCredential"/>The token to provide AAD token for authorization.</param>
/// <param name="clientOptions">(Optional) client options</param>
Expand Down Expand Up @@ -368,6 +383,9 @@ internal CosmosClient(
/// ]]>
/// </code>
/// </example>
/// <remarks>
/// The returned reference doesn't guarantee credentials or connectivity validations because initialization doesn't make any network calls.
sourabh1007 marked this conversation as resolved.
Show resolved Hide resolved
/// </remarks>
public static async Task<CosmosClient> CreateAndInitializeAsync(string accountEndpoint,
string authKeyOrResourceToken,
IReadOnlyList<(string databaseId, string containerId)> containers,
Expand Down
13 changes: 13 additions & 0 deletions Microsoft.Azure.Cosmos/src/Fluent/CosmosClientBuilder.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -167,9 +167,13 @@ public CosmosClientBuilder(

/// <summary>
/// A method to create the cosmos client
/// CosmosClient is thread-safe. Its recommended to maintain a single instance of CosmosClient per lifetime
ealsur marked this conversation as resolved.
Show resolved Hide resolved
/// of the application which enables efficient connection management and performance. Please refer to the
/// <see href="https://learn.microsoft.com/azure/cosmos-db/nosql/performance-tips-dotnet-sdk-v3">performance guide</see>.
/// </summary>
/// <remarks>
/// Setting this property after sending any request won't have any effect.
/// The returned reference doesn't guarantee credentials or connectivity validations because creation doesn't make any network calls.
/// </remarks>
/// <returns>An instance of <see cref="CosmosClient"/>.</returns>
public CosmosClient Build()
Expand All @@ -191,6 +195,11 @@ public CosmosClient Build()

/// <summary>
/// A method to create the cosmos client and initialize the provided containers.
/// In addition to that it initializes the client with containers provided i.e The SDK warms up the caches and
ealsur marked this conversation as resolved.
Show resolved Hide resolved
/// connections before the first call to the service is made. Use this to obtain lower latency while startup of your application.
/// CosmosClient is thread-safe. Its recommended to maintain a single instance of CosmosClient per lifetime
/// of the application which enables efficient connection management and performance. Please refer to the
/// <see href="https://learn.microsoft.com/azure/cosmos-db/nosql/performance-tips-dotnet-sdk-v3">performance guide</see>.
/// </summary>
/// <param name="containers">Containers to be initialized identified by it's database name and container name.</param>
/// <param name="cancellationToken">(Optional) Cancellation Token</param>
Expand All @@ -214,9 +223,13 @@ public Task<CosmosClient> BuildAndInitializeAsync(IReadOnlyList<(string database

/// <summary>
/// A method to create the cosmos client
/// CosmosClient is thread-safe. Its recommended to maintain a single instance of CosmosClient per lifetime
/// of the application which enables efficient connection management and performance. Please refer to the
/// <see href="https://learn.microsoft.com/azure/cosmos-db/nosql/performance-tips-dotnet-sdk-v3">performance guide</see>.
/// </summary>
/// <remarks>
/// Setting this property after sending any request won't have any effect.
/// The returned reference doesn't guarantee credentials or connectivity validations because creation doesn't make any network calls.
/// </remarks>
internal virtual CosmosClient Build(DocumentClient documentClient)
{
Expand Down