Skip to content

Commit f391bf3

Browse files
PMEds28PMEds28
authored
Merge pull request #264334 from ggailey777/versions-cleanup
[Functions] Update how to set version
2 parents 793ad9c + 831bef6 commit f391bf3

12 files changed

+134
-179
lines changed

‎articles/azure-functions/disable-function.md

Lines changed: 23 additions & 77 deletions
Original file line numberDiff line numberDiff line change
@@ -2,21 +2,25 @@
22
title: How to disable functions in Azure Functions
33
description: Learn how to disable and enable functions in Azure Functions.
44
ms.topic: conceptual
5-
ms.date: 12/01/2022
5+
ms.date: 03/12/2024
66
ms.custom: devx-track-csharp
77
---
88

99
# How to disable functions in Azure Functions
1010

11-
This article explains how to disable a function in Azure Functions. To *disable* a function means to make the runtime ignore the automatic trigger that's defined for the function. This lets you prevent a specific function from running without stopping the entire function app.
11+
This article explains how to disable a function in Azure Functions. To *disable* a function means to make the runtime ignore the event intended to trigger the function. This ability lets you prevent a specific function from running without having to modify and republish the entire function app.
1212

13-
The recommended way to disable a function is with an app setting in the format `AzureWebJobs.<FUNCTION_NAME>.Disabled` set to `true`. You can create and modify this application setting in several ways, including by using the [Azure CLI](/cli/azure/) and from your function's **Overview** tab in the [Azure portal](https://portal.azure.com).
13+
You can disable a function in place by creating an app setting in the format `AzureWebJobs.<FUNCTION_NAME>.Disabled` set to `true`. You can create and modify this application setting in several ways, including by using the [Azure CLI](/cli/azure/), [Azure PowerShell](/powershell/azure/), and from your function's **Overview** tab in the [Azure portal](https://portal.azure.com).
14+
15+
Changes to application settings cause your function app to restart. For more information, see [App settings reference for Azure Functions](functions-app-settings.md).
1416

1517
## Disable a function
1618

17-
# [Portal](#tab/portal)
19+
Use one of these modes to create an app setting that disables an example function named `QueueTrigger`:
20+
21+
### [Portal](#tab/portal)
1822

19-
Use the **Enable** and **Disable** buttons on the function's **Overview** page. These buttons work by changing the value of the `AzureWebJobs.<FUNCTION_NAME>.Disabled` app setting. This function-specific setting is created the first time it's disabled.
23+
Use the **Enable** and **Disable** buttons on the function's **Overview** page. These buttons work by changing the value of the `AzureWebJobs.QueueTrigger.Disabled` app setting. The function-specific app setting is created the first time a function is disabled.
2024

2125
![Function state switch](media/disable-function/function-state-switch.png)
2226

@@ -25,7 +29,7 @@ Even when you publish to your function app from a local project, you can still u
2529
> [!NOTE]
2630
> Disabled functions can still be run by calling the REST endpoint using a master key. To learn more, see [Run a disabled function](#run-a-disabled-function). This means that a disabled function still runs when started from the **Test/Run** window in the portal using the **master (Host key)**.
2731
28-
# [Azure CLI](#tab/azurecli)
32+
### [Azure CLI](#tab/azurecli)
2933

3034
In the Azure CLI, you use the [`az functionapp config appsettings set`](/cli/azure/functionapp/config/appsettings#az-functionapp-config-appsettings-set) command to create and modify the app setting. The following command disables a function named `QueueTrigger` by creating an app setting named `AzureWebJobs.QueueTrigger.Disabled` and setting it to `true`.
3135

@@ -43,7 +47,7 @@ az functionapp config appsettings set --name <myFunctionApp> \
4347
--settings AzureWebJobs.QueueTrigger.Disabled=false
4448
```
4549

46-
# [Azure PowerShell](#tab/powershell)
50+
### [Azure PowerShell](#tab/powershell)
4751

4852
The [`Update-AzFunctionAppSetting`](/powershell/module/az.functions/update-azfunctionappsetting) command adds or updates an application setting. The following command disables a function named `QueueTrigger` by creating an app setting named `AzureWebJobs.QueueTrigger.Disabled` and setting it to `true`.
4953

@@ -58,19 +62,19 @@ Update-AzFunctionAppSetting -Name <FUNCTION_APP_NAME> -ResourceGroupName <RESOUR
5862
```
5963
---
6064

61-
## Functions in a slot
65+
## Disable functions in a slot
6266

63-
By default, app settings also apply to apps running in deployment slots. You can, however, override the app setting used by the slot by setting a slot-specific app setting. For example, you might want a function to be active in production but not during deployment testing, such as a timer triggered function.
67+
By default, app settings also apply to apps running in deployment slots. You can, however, override the app setting used by the slot by setting a slot-specific app setting. For example, you might want a function to be active in production but not during deployment testing. It's common to disable timer triggered functions in slots to prevent simultaneous executions.
6468

6569
To disable a function only in the staging slot:
6670

67-
# [Portal](#tab/portal)
71+
### [Portal](#tab/portal)
6872

69-
Navigate to the slot instance of your function app by selecting **Deployment slots** under **Deployment**, choosing your slot, and selecting **Functions** in the slot instance. Choose your function, then use the **Enable** and **Disable** buttons on the function's **Overview** page. These buttons work by changing the value of the `AzureWebJobs.<FUNCTION_NAME>.Disabled` app setting. This function-specific setting is created the first time it's disabled.
73+
Navigate to the slot instance of your function app by selecting **Deployment slots** under **Deployment**, choosing your slot, and selecting **Functions** in the slot instance. Choose your function, then use the **Enable** and **Disable** buttons on the function's **Overview** page. These buttons work by changing the value of the `AzureWebJobs.<FUNCTION_NAME>.Disabled` app setting. This function-specific setting is created the first time you disable the function.
7074

71-
You can also directly add the app setting named `AzureWebJobs.<FUNCTION_NAME>.Disabled` with value of `true` in the **Configuration** for the slot instance. When you add a slot-specific app setting, make sure to check the **Deployment slot setting** box. This maintains the setting value with the slot during swaps.
75+
You can also directly add the app setting named `AzureWebJobs.<FUNCTION_NAME>.Disabled` with value of `true` in the **Configuration** for the slot instance. When you add a slot-specific app setting, make sure to check the **Deployment slot setting** box. This option maintains the setting value with the slot during swaps.
7276

73-
# [Azure CLI](#tab/azurecli)
77+
### [Azure CLI](#tab/azurecli)
7478

7579
```azurecli-interactive
7680
az functionapp config appsettings set --name <FUNCTION_APP_NAME> \
@@ -85,7 +89,7 @@ az functionapp config appsettings set --name <myFunctionApp> \
8589
--slot-settings AzureWebJobs.QueueTrigger.Disabled=false
8690
```
8791

88-
# [Azure PowerShell](#tab/powershell)
92+
### [Azure PowerShell](#tab/powershell)
8993

9094
Azure PowerShell currently doesn't support this functionality.
9195

@@ -101,86 +105,28 @@ You can still cause a disabled function to run by supplying the [master key](fun
101105

102106
To learn more about the master key, see [Obtaining keys](functions-bindings-http-webhook-trigger.md#obtaining-keys). To learn more about calling non-HTTP triggered functions, see [Manually run a non HTTP-triggered function](functions-manually-run-non-http.md).
103107

104-
## local.settings.json
108+
## Disable functions locally
105109

106-
Functions can be disabled in the same way when running locally. To disable a function named `HttpExample`, add an entry to the Values collection in the local.settings.json file, as follows:
110+
Functions can be disabled in the same way when running locally. To disable a function named `QueueTrigger`, add an entry to the Values collection in the local.settings.json file, as follows:
107111

108112
```json
109113
{
110114
"IsEncrypted": false,
111115
"Values": {
112116
"FUNCTIONS_WORKER_RUNTIME": "python",
113117
"AzureWebJobsStorage": "UseDevelopmentStorage=true",
114-
"AzureWebJobs.HttpExample.Disabled": true
118+
"AzureWebJobs.QueueTrigger.Disabled": true
115119
}
116120
}
117121
```
118122

119-
## Other methods
120-
121-
While the application setting method is recommended for all languages and all runtime versions, there are several other ways to disable functions. These methods, which vary by language and runtime version, are maintained for backward compatibility.
122-
123-
### C# class libraries
124-
125-
In a class library function, you can also use the `Disable` attribute to prevent the function from being triggered. This attribute lets you customize the name of the setting used to disable the function. Use the version of the attribute that lets you define a constructor parameter that refers to a Boolean app setting, as shown in the following example:
126-
127-
```csharp
128-
public static class QueueFunctions
129-
{
130-
[Disable("MY_TIMER_DISABLED")]
131-
[FunctionName("QueueTrigger")]
132-
public static void QueueTrigger(
133-
[QueueTrigger("myqueue-items")] string myQueueItem,
134-
TraceWriter log)
135-
{
136-
log.Info($"C# function processed: {myQueueItem}");
137-
}
138-
}
139-
```
140-
141-
This method lets you enable and disable the function by changing the app setting, without recompiling or redeploying. Changing an app setting causes the function app to restart, so the disabled state change is recognized immediately.
142-
143-
There's also a constructor for the parameter that doesn't accept a string for the setting name. This version of the attribute isn't recommended. If you use this version, you must recompile and redeploy the project to change the function's disabled state.
144-
145-
### Functions 1.x - scripting languages
146-
147-
In version 1.x, you can also use the `disabled` property of the *function.json* file to tell the runtime not to trigger a function. This method only works for scripting languages such as C# script and JavaScript. The `disabled` property can be set to `true` or to the name of an app setting:
148-
149-
```json
150-
{
151-
"bindings": [
152-
{
153-
"type": "queueTrigger",
154-
"direction": "in",
155-
"name": "myQueueItem",
156-
"queueName": "myqueue-items",
157-
"connection":"MyStorageConnectionAppSetting"
158-
}
159-
],
160-
"disabled": true
161-
}
162-
```
163-
or
164-
165-
```json
166-
"bindings": [
167-
...
168-
],
169-
"disabled": "IS_DISABLED"
170-
```
171-
172-
In the second example, the function is disabled when there's an app setting that is named IS_DISABLED and is set to `true` or 1.
173-
174-
>[!IMPORTANT]
175-
>The portal uses application settings to disable v1.x functions. When an application setting conflicts with the function.json file, an error can occur. You should remove the `disabled` property from the function.json file to prevent errors.
176-
177123
## Considerations
178124

179125
Keep the following considerations in mind when you disable functions:
180126

181-
+ When you disable an HTTP triggered function by using the methods described in this article, the endpoint may still by accessible when running on your local computer and [in the portal](#run-a-disabled-function).
127+
+ When you disable an HTTP triggered function by using the methods described in this article, the endpoint can still be accessed when running on your local computer and [in the portal](#run-a-disabled-function).
182128

183-
+ At this time, function names that contain a hyphen (`-`) can't be disabled when running on Linux plan. If you need to disable your functions when running on Linux plan, don't use hyphens in your function names.
129+
+ At this time, function names that contain a hyphen (`-`) can't be disabled when running on Linux. If you plan to disable your functions when running on Linux, don't use hyphens in your function names.
184130

185131
## Next steps
186132

‎articles/azure-functions/functions-bindings-azure-data-explorer.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -82,7 +82,7 @@ Azure Data Explorer bindings for Azure Functions aren't available for the v3 ver
8282
## Functions runtime
8383

8484
> [!NOTE]
85-
> Python language support for the Azure Data Explorer bindings extension is available starting with v4.6.0 or later of the [Functions runtime](set-runtime-version.md#view-and-update-the-current-runtime-version). You might need to update your installation of Azure Functions [Core Tools](functions-run-local.md) for local development.
85+
> Python language support for the Azure Data Explorer bindings extension is available starting with v4.6.0 or later of the [Functions runtime](set-runtime-version.md#manual-version-updates-on-linux). You might need to update your installation of Azure Functions [Core Tools](functions-run-local.md) for local development.
8686
8787
## Install the bundle
8888

‎articles/azure-functions/functions-develop-local.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -85,7 +85,7 @@ The following application settings can be included in the **`Values`** array whe
8585
| Setting | Values | Description |
8686
|-----|-----|-----|
8787
|**`AzureWebJobsStorage`**| Storage account connection string, or<br/>`UseDevelopmentStorage=true`| Contains the connection string for an Azure storage account. Required when using triggers other than HTTP. For more information, see the [`AzureWebJobsStorage`] reference.<br/>When you have the [Azurite Emulator](../storage/common/storage-use-azurite.md) installed locally and you set [`AzureWebJobsStorage`] to `UseDevelopmentStorage=true`, Core Tools uses the emulator. For more information, see [Local storage emulator](#local-storage-emulator).|
88-
|**`AzureWebJobs.<FUNCTION_NAME>.Disabled`**| `true`\|`false` | To disable a function when running locally, add `"AzureWebJobs.<FUNCTION_NAME>.Disabled": "true"` to the collection, where `<FUNCTION_NAME>` is the name of the function. To learn more, see [How to disable functions in Azure Functions](disable-function.md#localsettingsjson). |
88+
|**`AzureWebJobs.<FUNCTION_NAME>.Disabled`**| `true`\|`false` | To disable a function when running locally, add `"AzureWebJobs.<FUNCTION_NAME>.Disabled": "true"` to the collection, where `<FUNCTION_NAME>` is the name of the function. To learn more, see [How to disable functions in Azure Functions](disable-function.md#disable-functions-locally). |
8989
|**`FUNCTIONS_WORKER_RUNTIME`** | `dotnet`<br/>`dotnet-isolated`<br/>`node`<br/>`java`<br/>`powershell`<br/>`python`| Indicates the targeted language of the Functions runtime. Required for version 2.x and higher of the Functions runtime. This setting is generated for your project by Core Tools. To learn more, see the [`FUNCTIONS_WORKER_RUNTIME`](functions-app-settings.md#functions_worker_runtime) reference.|
9090
| **`FUNCTIONS_WORKER_RUNTIME_VERSION`** | `~7` |Indicates to use PowerShell 7 when running locally. If not set, then PowerShell Core 6 is used. This setting is only used when running locally. The PowerShell runtime version is determined by the `powerShellVersion` site configuration setting, when it runs in Azure, which can be [set in the portal](functions-reference-powershell.md#changing-the-powershell-version). |
9191

‎articles/azure-functions/functions-reference-powershell.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -415,7 +415,7 @@ Support for PowerShell 7.0 in Azure Functions has ended on 3 December 2022. To u
415415
416416
### Changing the PowerShell version
417417

418-
Support for PowerShell 7.0 in Azure Functions has ended on 3 December 2022. To upgrade your Function App to PowerShell 7.2, ensure the value of FUNCTIONS_EXTENSION_VERSION is set to ~4. To learn how to do this, see [View and update the current runtime version](set-runtime-version.md#view-and-update-the-current-runtime-version).
418+
Support for PowerShell 7.0 in Azure Functions has ended on 3 December 2022. To upgrade your Function App to PowerShell 7.2, ensure the value of FUNCTIONS_EXTENSION_VERSION is set to ~4. To learn how to do this, see [View and update the current runtime version](set-runtime-version.md#view-the-current-runtime-version).
419419

420420

421421
Use the following steps to change the PowerShell version used by your function app. You can do this either in the Azure portal or by using PowerShell.

‎articles/azure-functions/functions-versions.md

Lines changed: 4 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@ This article details some of the differences between supported versions, how you
3131

3232
## Languages
3333

34-
All functions in a function app must share the same language. You choose the language of functions in your function app when you create the app. The language of your function app is maintained in the [FUNCTIONS\_WORKER\_RUNTIME](functions-app-settings.md#functions_worker_runtime) setting, and shouldn't be changed when there are existing functions.
34+
All functions in a function app must share the same language. You choose the language of functions in your function app when you create the app. The language of your function app is maintained in the [FUNCTIONS\_WORKER\_RUNTIME](functions-app-settings.md#functions_worker_runtime) setting, and can't be changed when there are existing functions.
3535

3636
[!INCLUDE [functions-supported-languages](../../includes/functions-supported-languages.md)]
3737

@@ -41,14 +41,11 @@ For information about the language versions of previously supported versions of
4141

4242
The version of the Functions runtime used by published apps in Azure is dictated by the [`FUNCTIONS_EXTENSION_VERSION`](functions-app-settings.md#functions_extension_version) application setting. In some cases and for certain languages, other settings can apply.
4343

44-
By default, function apps created in the Azure portal, by the Azure CLI, or from Visual Studio tools are set to version 4.x. You can modify this version if needed. You can only downgrade the runtime version to 1.x after you create your function app but before you add any functions. Moving to a later version is allowed even with apps that have existing functions.
44+
By default, function apps created in the Azure portal, by the Azure CLI, or from Visual Studio tools are set to version 4.x. You can modify this version if needed. You can only downgrade the runtime version to 1.x after you create your function app but before you add any functions. Updating to a later major version is allowed even with apps that have existing functions.
4545

4646
### Migrating existing function apps
4747

48-
When your app has existing functions, you must take precautions before moving to a later runtime version. The following articles detail breaking changes between versions, including language-specific breaking changes. They also provide you with step-by-step instructions for a successful migration of your existing function app.
49-
50-
+ [Migrate from runtime version 3.x to version 4.x](./migrate-version-3-version-4.md)
51-
+ [Migrate from runtime version 1.x to version 4.x](./migrate-version-1-version-4.md)
48+
[!INCLUDE [functions-migrate-apps](../../includes/functions-migrate-apps.md)]
5249

5350
### Changing version of apps in Azure
5451

@@ -60,7 +57,7 @@ The following major runtime version values are used:
6057
| `~1` | 1.x |
6158

6259
>[!IMPORTANT]
63-
> Don't arbitrarily change this app setting, because other app setting changes and changes to your function code might be required. You should instead change this setting in the **Function runtime settings** tab of the function app **Configuration** in the Azure portal when you are ready to make a major version upgrade. For existing function apps, [follow the migration instructions](#migrating-existing-function-apps).
60+
> Don't arbitrarily change this app setting, because other app setting changes and changes to your function code might be required. For existing function apps, [follow the migration instructions](#migrating-existing-function-apps).
6461
6562
### Pinning to a specific minor version
6663

0 commit comments

Comments
 (0)