Skip to content

Commit 02bd687

Browse files
ttorblettorble
authored
Merge pull request #248541 from jcocchi/add-functions-migration-guide
Cosmos DB: add migration guide for cosmos db Azure Functions extension
2 parents 0908dc2 + 8e37a16 commit 02bd687

File tree

3 files changed

+218
-1
lines changed

3 files changed

+218
-1
lines changed

‎articles/azure-functions/TOC.yml

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -756,6 +756,9 @@
756756
- name: Output
757757
href: functions-bindings-cosmosdb-v2-output.md
758758
displayName: Azure Cosmos DB
759+
- name: Migrate Azure Cosmos DB extension 3.x to 4.x
760+
href: migrate-cosmos-db-version-3-version-4.md
761+
displayName: Azure Cosmos DB
759762
- name: Azure Data Explorer
760763
items:
761764
- name: Overview

‎articles/azure-functions/migrate-cosmos-db-version-3-version-4.md

Lines changed: 214 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,214 @@
1+
---
2+
title: Migrate Azure Cosmos DB extension version 3.x to 4.x
3+
description: This article shows you how to upgrade your existing function apps using the Azure Cosmos DB extension version 3.x to be able to use version 4.x of the extension.
4+
ms.service: azure-functions
5+
ms.topic: how-to
6+
ms.date: 08/16/2023
7+
zone_pivot_groups: programming-languages-set-functions-lang-workers
8+
---
9+
10+
# Migrate apps from Azure Cosmos DB extension version 3.x to version 4.x
11+
12+
This article highlights considerations for upgrading your existing Azure Functions applications that use the Azure Cosmos DB extension version 3.x to use the newer [extension version 4.x](./functions-bindings-cosmosdb-v2.md?tabs=extensionv4). Migrating from version 3.x to version 4.x of the Azure Cosmos DB extension has breaking changes for your application.
13+
14+
> [!IMPORTANT]
15+
> On August 31, 2024 the Azure Cosmos DB extension version 3.x will be retired. The extension and all applications using the extension will continue to function, but Azure Cosmos DB will cease to provide further maintenance and support for this extension. We recommend migrating to the latest version 4.x of the extension.
16+
17+
This article walks you through the process of migrating your function app to run on version 4.x of the Azure Cosmos DB extension. Because project upgrade instructions are language dependent, make sure to choose your development language from the selector at the [top of the article](#top).
18+
19+
::: zone pivot="programming-language-csharp"
20+
21+
## Update the extension version
22+
23+
.NET Functions use bindings that are installed in the project as NuGet packages. Depending on your Functions process model, the NuGet package to update varies.
24+
25+
|Functions process model |Azure Cosmos DB extension |Recommended version |
26+
|------------------------|--------------------------|--------------------|
27+
|[In-process model](./functions-dotnet-class-library.md)|[Microsoft.Azure.WebJobs.Extensions.CosmosDB](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.CosmosDB) |>= 4.3.0 |
28+
|[Isolated worker model](./dotnet-isolated-process-guide.md) |[Microsoft.Azure.Functions.Worker.Extensions.CosmosDB](https://www.nuget.org/packages/Microsoft.Azure.Functions.Worker.Extensions.CosmosDB)|>= 4.4.1 |
29+
30+
Update your `.csproj` project file to use the latest extension version for your process model. The following `.csproj` file uses version 4 of the Azure Cosmos DB extension.
31+
32+
### [In-process model](#tab/in-process)
33+
34+
```xml
35+
<Project Sdk="Microsoft.NET.Sdk">
36+
<PropertyGroup>
37+
<TargetFramework>net7.0</TargetFramework>
38+
<AzureFunctionsVersion>v4</AzureFunctionsVersion>
39+
</PropertyGroup>
40+
<ItemGroup>
41+
<PackageReference Include="Microsoft.Azure.WebJobs.Extensions.CosmosDB" Version="4.3.0" />
42+
<PackageReference Include="Microsoft.NET.Sdk.Functions" Version="4.1.1" />
43+
</ItemGroup>
44+
<ItemGroup>
45+
<None Update="host.json">
46+
<CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
47+
</None>
48+
<None Update="local.settings.json">
49+
<CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
50+
<CopyToPublishDirectory>Never</CopyToPublishDirectory>
51+
</None>
52+
</ItemGroup>
53+
</Project>
54+
```
55+
56+
### [Isolated worker model](#tab/isolated-worker)
57+
58+
```xml
59+
<Project Sdk="Microsoft.NET.Sdk">
60+
<PropertyGroup>
61+
<TargetFramework>net7.0</TargetFramework>
62+
<AzureFunctionsVersion>v4</AzureFunctionsVersion>
63+
<OutputType>Exe</OutputType>
64+
</PropertyGroup>
65+
<ItemGroup>
66+
<PackageReference Include="Microsoft.Azure.Functions.Worker" Version="1.14.1" />
67+
<PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.CosmosDB" Version="4.4.1" />
68+
<PackageReference Include="Microsoft.Azure.Functions.Worker.Sdk" Version="1.10.0" />
69+
</ItemGroup>
70+
<ItemGroup>
71+
<None Update="host.json">
72+
<CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
73+
</None>
74+
<None Update="local.settings.json">
75+
<CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
76+
<CopyToPublishDirectory>Never</CopyToPublishDirectory>
77+
</None>
78+
</ItemGroup>
79+
</Project>
80+
```
81+
82+
---
83+
84+
::: zone-end
85+
::: zone pivot="programming-language-javascript,programming-language-python,programming-language-java,programming-language-powershell"
86+
87+
## Update the extension bundle
88+
89+
By default, [extension bundles](./functions-bindings-register.md#extension-bundles) are used by non-.NET function apps to install binding extensions. The Azure Cosmos DB version 4 extension is part of the Microsoft Azure Functions version 4 extension bundle.
90+
91+
To update your application to use the latest extension bundle, update your `host.json`. The following `host.json` file uses version 4 of the Microsoft Azure Functions extension bundle.
92+
93+
```json
94+
{
95+
"version": "2.0",
96+
"extensionBundle": {
97+
"id": "Microsoft.Azure.Functions.ExtensionBundle",
98+
"version": "[4.*, 5.0.0)"
99+
}
100+
}
101+
```
102+
103+
::: zone-end
104+
105+
::: zone pivot="programming-language-csharp"
106+
107+
## Rename the binding attributes
108+
109+
Both [in-process](functions-dotnet-class-library.md) and [isolated process](dotnet-isolated-process-guide.md) C# libraries use the [CosmosDBTriggerAttribute](https://github.com/Azure/azure-webjobs-sdk-extensions/blob/master/src/WebJobs.Extensions.CosmosDB/Trigger/CosmosDBTriggerAttribute.cs) to define the function.
110+
111+
The following table only includes attributes that were renamed or were removed from the version 3 extension. For a full list of attributes available in the version 4 extension, visit the [attribute reference](./functions-bindings-cosmosdb-v2-trigger.md?tabs=extensionv4#attributes).
112+
113+
|Version 3 attribute property |Version 4 attribute property |Version 4 attribute description |
114+
|-----------------------------|-----------------------------|--------------------------------|
115+
|**ConnectionStringSetting** |**Connection** | The name of an app setting or setting collection that specifies how to connect to the Azure Cosmos DB account being monitored. For more information, see [Connections](./functions-bindings-cosmosdb-v2-trigger.md#connections).|
116+
|**CollectionName** |**ContainerName** | The name of the container being monitored. |
117+
|**LeaseConnectionStringSetting** |**LeaseConnection** | (Optional) The name of an app setting or setting collection that specifies how to connect to the Azure Cosmos DB account that holds the lease container. <br><br> When not set, the `Connection` value is used. This parameter is automatically set when the binding is created in the portal. The connection string for the leases container must have write permissions.|
118+
|**LeaseCollectionName** |**LeaseContainerName** | (Optional) The name of the container used to store leases. When not set, the value `leases` is used. |
119+
|**CreateLeaseCollectionIfNotExists** |**CreateLeaseContainerIfNotExists** | (Optional) When set to `true`, the leases container is automatically created when it doesn't already exist. The default value is `false`. When using Azure AD identities if you set the value to `true`, creating containers isn't [an allowed operation](../cosmos-db/nosql/troubleshoot-forbidden.md#non-data-operations-are-not-allowed) and your Function won't be able to start.|
120+
|**LeasesCollectionThroughput** |**LeasesContainerThroughput** | (Optional) Defines the number of Request Units to assign when the leases container is created. This setting is only used when `CreateLeaseContainerIfNotExists` is set to `true`. This parameter is automatically set when the binding is created using the portal. |
121+
|**LeaseCollectionPrefix** |**LeaseContainerPrefix** | (Optional) When set, the value is added as a prefix to the leases created in the Lease container for this function. Using a prefix allows two separate Azure Functions to share the same Lease container by using different prefixes. |
122+
|**UseMultipleWriteLocations** |*Removed* | This attribute is no longer needed as it's automatically detected. |
123+
|**UseDefaultJsonSerialization** |*Removed* | This attribute is no longer needed as you can fully customize the serialization using built in support in the [Azure Cosmos DB version 3 .NET SDK](../cosmos-db/nosql/migrate-dotnet-v3.md#customize-serialization). |
124+
|**CheckpointInterval**|*Removed* | This attribute has been removed in the version 4 extension. |
125+
|**CheckpointDocumentCount** |*Removed* | This attribute has been removed in the version 4 extension. |
126+
127+
::: zone-end
128+
::: zone pivot="programming-language-javascript,programming-language-python,programming-language-java,programming-language-powershell"
129+
130+
## Rename the binding attributes
131+
132+
Update your binding configuration properties in the `function.json` file.
133+
134+
The following table only includes attributes that changed or were removed from the version 3.x extension. For a full list of attributes available in the version 4 extension, visit the [attribute reference](./functions-bindings-cosmosdb-v2-trigger.md#attributes).
135+
136+
|Version 3 attribute property |Version 4 attribute property |Version 4 attribute description |
137+
|-----------------------------|-----------------------------|--------------------------------|
138+
|**connectionStringSetting** |**connection** | The name of an app setting or setting collection that specifies how to connect to the Azure Cosmos DB account being monitored. For more information, see [Connections](./functions-bindings-cosmosdb-v2-trigger.md#connections).|
139+
|**collectionName** |**containerName** | The name of the container being monitored. |
140+
|**leaseConnectionStringSetting** |**leaseConnection** | (Optional) The name of an app setting or setting collection that specifies how to connect to the Azure Cosmos DB account that holds the lease container. <br><br> When not set, the `connection` value is used. This parameter is automatically set when the binding is created in the portal. The connection string for the leases container must have write permissions.|
141+
|**leaseCollectionName** |**leaseContainerName** | (Optional) The name of the container used to store leases. When not set, the value `leases` is used. |
142+
|**createLeaseCollectionIfNotExists** |**createLeaseContainerIfNotExists** | (Optional) When set to `true`, the leases container is automatically created when it doesn't already exist. The default value is `false`. When using Azure AD identities if you set the value to `true`, creating containers isn't [an allowed operation](../cosmos-db/nosql/troubleshoot-forbidden.md#non-data-operations-are-not-allowed) and your Function won't be able to start.|
143+
|**leasesCollectionThroughput** |**leasesContainerThroughput** | (Optional) Defines the number of Request Units to assign when the leases container is created. This setting is only used when `createLeaseContainerIfNotExists` is set to `true`. This parameter is automatically set when the binding is created using the portal. |
144+
|**leaseCollectionPrefix** |**leaseContainerPrefix** | (Optional) When set, the value is added as a prefix to the leases created in the Lease container for this function. Using a prefix allows two separate Azure Functions to share the same Lease container by using different prefixes. |
145+
|**useMultipleWriteLocations** |*Removed* | This attribute is no longer needed as it's automatically detected. |
146+
|**checkpointInterval**|*Removed* | This attribute has been removed in the version 4 extension. |
147+
|**checkpointDocumentCount** |*Removed* | This attribute has been removed in the version 4 extension. |
148+
149+
::: zone-end
150+
151+
::: zone pivot="programming-language-csharp"
152+
153+
## Modify your function code
154+
155+
The Azure Functions extension version 4 is built on top of the Azure Cosmos DB .NET SDK version 3, which removed support for the [`Document` class](../cosmos-db/nosql/migrate-dotnet-v3.md#major-name-changes-from-v2-sdk-to-v3-sdk). Instead of receiving a list of `Document` objects with each function invocation, which you must then deserialize into your own object type, you can now directly receive a list of objects of your own type.
156+
157+
This example refers to a simple `ToDoItem` type.
158+
159+
```cs
160+
namespace CosmosDBSamples
161+
{
162+
// Customize the model with your own desired properties
163+
public class ToDoItem
164+
{
165+
public string id { get; set; }
166+
public string Description { get; set; }
167+
}
168+
}
169+
```
170+
171+
Changes to the attribute names must be made directly in the code when defining your Function.
172+
173+
```cs
174+
using System.Collections.Generic;
175+
using Microsoft.Azure.WebJobs;
176+
using Microsoft.Azure.WebJobs.Host;
177+
using Microsoft.Extensions.Logging;
178+
179+
namespace CosmosDBSamples
180+
{
181+
public static class CosmosTrigger
182+
{
183+
[FunctionName("CosmosTrigger")]
184+
public static void Run([CosmosDBTrigger(
185+
databaseName: "databaseName",
186+
containerName: "containerName",
187+
Connection = "CosmosDBConnectionSetting",
188+
LeaseContainerName = "leases",
189+
CreateLeaseContainerIfNotExists = true)]IReadOnlyList<ToDoItem> input, ILogger log)
190+
{
191+
if (input != null && input.Count > 0)
192+
{
193+
log.LogInformation("Documents modified " + input.Count);
194+
log.LogInformation("First document Id " + input[0].id);
195+
}
196+
}
197+
}
198+
}
199+
```
200+
201+
::: zone-end
202+
::: zone pivot="programming-language-javascript,programming-language-python,programming-language-java,programming-language-powershell"
203+
204+
## Modify your function code
205+
206+
After you update your `host.json` to use the correct extension bundle version and modify your `function.json` to use the correct attribute names, there are no further code changes required.
207+
208+
::: zone-end
209+
210+
## Next steps
211+
212+
- [Run a function when an Azure Cosmos DB document is created or modified (Trigger)](./functions-bindings-cosmosdb-v2-trigger.md)
213+
- [Read an Azure Cosmos DB document (Input binding)](./functions-bindings-cosmosdb-v2-input.md)
214+
- [Save changes to an Azure Cosmos DB document (Output binding)](./functions-bindings-cosmosdb-v2-output.md)

‎includes/functions-cosmosdb-attributes-v4.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ ms.author: glenga
1010
|**Connection** | The name of an app setting or setting collection that specifies how to connect to the Azure Cosmos DB account being monitored. For more information, see [Connections](#connections).|
1111
|**DatabaseName** | The name of the Azure Cosmos DB database with the container being monitored. |
1212
|**ContainerName** | The name of the container being monitored. |
13-
|**LeaseConnection** | (Optional) The name of an app setting or setting container that specifies how to connect to the Azure Cosmos DB account that holds the lease container. <br><br> When not set, the `Connection` value is used. This parameter is automatically set when the binding is created in the portal. The connection string for the leases container must have write permissions.|
13+
|**LeaseConnection** | (Optional) The name of an app setting or setting collection that specifies how to connect to the Azure Cosmos DB account that holds the lease container. <br><br> When not set, the `Connection` value is used. This parameter is automatically set when the binding is created in the portal. The connection string for the leases container must have write permissions.|
1414
|**LeaseDatabaseName** | (Optional) The name of the database that holds the container used to store leases. When not set, the value of the `databaseName` setting is used. |
1515
|**LeaseContainerName** | (Optional) The name of the container used to store leases. When not set, the value `leases` is used. |
1616
|**CreateLeaseContainerIfNotExists** | (Optional) When set to `true`, the leases container is automatically created when it doesn't already exist. The default value is `false`. When using Azure AD identities if you set the value to `true`, creating containers is not [an allowed operation](../articles/cosmos-db/sql/troubleshoot-forbidden.md#non-data-operations-are-not-allowed) and your Function won't be able to start.|

0 commit comments

Comments
 (0)