You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The [``Database.CreateContainerAsync``](/dotnet/api/microsoft.azure.cosmos.database.createcontainerasync) method will throw an exception if a database with the same name already exists.
48
48
49
49
### Create a container asynchronously if it doesn't already exist
50
50
51
51
The following example creates a container asynchronously only if it doesn't already exist on the account:
The [``Database.CreateContainerIfNotExistsAsync``](/dotnet/api/microsoft.azure.cosmos.database.createcontainerifnotexistsasync) method will only create a new container if it doesn't already exist. This method is useful for avoiding errors if you run the same code multiple times.
56
56
@@ -60,7 +60,7 @@ In all examples so far, the response from the asynchronous request was cast imme
60
60
61
61
The following example shows the **Database.CreateContainerIfNotExistsAsync** method returning a **ContainerResponse**. Once returned, you can parse response properties and then eventually get the underlying **Container** object:
The [``CosmosClient.CreateDatabaseAsync``](/dotnet/api/microsoft.azure.cosmos.cosmosclient.createdatabaseasync) method will throw an exception if a database with the same name already exists.
48
48
49
49
### Create a database asynchronously if it doesn't already exist
50
50
51
51
The following example creates a database asynchronously only if it doesn't already exist on the account:
The [``CosmosClient.CreateDatabaseIfNotExistsAsync``](/dotnet/api/microsoft.azure.cosmos.cosmosclient.createdatabaseifnotexistsasync) method will only create a new database if it doesn't already exist. This method is useful for avoiding errors if you run the same code multiple times.
56
56
@@ -60,7 +60,7 @@ In all examples so far, the response from the asynchronous request was cast imme
60
60
61
61
The following example shows the **CosmosClient.CreateDatabaseIfNotExistsAsync** method returning a **DatabaseResponse**. Once returned, you can parse response properties and then eventually get the underlying **Database** object:
The [``Container.CreateItemAsync<>``](/dotnet/api/microsoft.azure.cosmos.container.createitemasync) method will throw an exception if there's a conflict with the unique identifier of an existing item. To learn more about potential exceptions, see [``CreateItemAsync<>`` exceptions](/dotnet/api/microsoft.azure.cosmos.container.createitemasync#exceptions).
66
66
67
67
## Replace an item asynchronously
68
68
69
69
The following example replaces an existing item asynchronously:
The [``Container.ReplaceItemAsync<>``](/dotnet/api/microsoft.azure.cosmos.container.replaceitemasync) method requires the provided string for the ``id`` parameter to match the unique identifier of the ``item`` parameter.
74
74
75
75
## Create or replace an item asynchronously
76
76
77
77
The following example will create a new item or replace an existing item if an item already exists with the same unique identifier:
The [``Container.UpsertItemAsync<>``](/dotnet/api/microsoft.azure.cosmos.container.upsertitemasync) method will use the unique identifier of the ``item`` parameter to determine if there's a conflict with an existing item and to replace the item appropriately.
#### Create CosmosClient with default credential implementation
331
331
332
332
If you're testing on a local machine, or your application will run on Azure services with direct support for managed identities, obtain an OAuth token by creating a [``DefaultAzureCredential``](/dotnet/api/azure.identity.defaultazurecredential) instance.
333
333
334
334
For this example, we saved the instance in a variable of type [``TokenCredential``](/dotnet/api/azure.core.tokencredential) as that's a more generic type that's reusable across SDKs.
Create a new instance of the **CosmosClient** class with the ``COSMOS_ENDPOINT`` environment variable and the **TokenCredential** object as parameters.
#### Create CosmosClient with a custom credential implementation
343
343
344
344
If you plan to deploy the application out of Azure, you can obtain an OAuth token by using other classes in the [Azure.Identity client library for .NET](/dotnet/api/overview/azure/identity-readme). These other classes also derive from the ``TokenCredential`` class.
345
345
346
346
For this example, we create a [``ClientSecretCredential``](/dotnet/api/azure.identity.clientsecretcredential) instance by using client and tenant identifiers, along with a client secret.
You can obtain the client ID, tenant ID, and client secret when you register an application in Azure Active Directory (AD). For more information about registering Azure AD applications, see [Register an application with the Microsoft identity platform](../../active-directory/develop/quickstart-register-app.md).
351
351
352
352
Create a new instance of the **CosmosClient** class with the ``COSMOS_ENDPOINT`` environment variable and the **TokenCredential** object as parameters.
To query items in a container, call one of the following methods:
@@ -50,13 +50,13 @@ To query items in a container, call one of the following methods:
50
50
51
51
This example builds a SQL query using a simple string, retrieves a feed iterator, and then uses nested loops to iterate over results. The outer **while** loop will iterate through result pages, while the inner **foreach** loop iterates over results within a page.
The [Container.GetItemQueryIterator<>](/dotnet/api/microsoft.azure.cosmos.container.getitemqueryiterator) method returns a [``FeedIterator<>``](/dotnet/api/microsoft.azure.cosmos.feediterator-1) that is used to iterate through multi-page results. The ``HasMoreResults`` property indicates if there are more result pages left. The ``ReadNextAsync`` method gets the next page of results as an enumerable that is then used in a loop to iterate over results.
56
56
57
57
Alternatively, use the [QueryDefinition](/dotnet/api/microsoft.azure.cosmos.querydefinition) to build a SQL query with parameterized input:
> Parameterized input values can help prevent many common SQL query injection attacks.
@@ -65,7 +65,7 @@ Alternatively, use the [QueryDefinition](/dotnet/api/microsoft.azure.cosmos.quer
65
65
66
66
In this example, an [``IQueryable``<>](/dotnet/api/system.linq.iqueryable) object is used to construct a [Language Integrated Query (LINQ)](/dotnet/csharp/programming-guide/concepts/linq/). The results are then iterated over using a feed iterator.
The [Container.GetItemLinqQueryable<>](/dotnet/api/microsoft.azure.cosmos.container.getitemlinqqueryable) method constructs an ``IQueryable`` to build the LINQ query. Then the ``ToFeedIterator<>`` method is used to convert the LINQ query expression into a [``FeedIterator<>``](/dotnet/api/microsoft.azure.cosmos.feediterator-1).
The [``Database.ReadItemAsync<>``](/dotnet/api/microsoft.azure.cosmos.container.readitemasync) method reads and item and returns an object of type [``ItemResponse<>``](/dotnet/api/microsoft.azure.cosmos.itemresponse-1). The **ItemResponse<>** type inherits from the [``Response<>``](/dotnet/api/microsoft.azure.cosmos.response-1) type, which contains an implicit conversion operator to convert the object into the generic type. To learn more about implicit operators, see [user-defined conversion operators](/dotnet/csharp/language-reference/operators/user-defined-conversion-operators).
45
45
46
46
Alternatively, you can return the **ItemResponse<>** generic type and explicitly get the resource. The more general **ItemResponse<>** type also contains useful metadata about the underlying API operation. In this example, metadata about the request unit charge for this operation is gathered using the **RequestCharge** property.
The [``Container.ReadItemStreamAsync``](/dotnet/api/microsoft.azure.cosmos.container.readitemstreamasync) method returns the item as a [``Stream``](/dotnet/api/system.io.stream) without deserializing the contents.
57
57
@@ -61,7 +61,7 @@ If you aren't planning to deserialize the items directly, using the stream APIs
61
61
62
62
In this example, a list of tuples containing unique identifier and partition key pairs are used to look up and retrieve multiple items:
[``Container.ReadManyItemsAsync<>``](/dotnet/api/microsoft.azure.cosmos.container.readmanyitemsasync) returns a list of items based on the unique identifiers and partition keys you provide. This operation is typically more performant than a query since you'll effectively perform a point read operation on all items in the list.
0 commit comments