| title | description | ms.assetid | ms.topic | ms.date | ms.devlang | ms.custom |
|---|---|---|---|---|---|---|
Guidance for developing Azure Functions |
Learn the Azure Functions concepts and techniques that you need to develop functions in Azure, across all programming languages and bindings. |
d8efe41a-bef8-4167-ba97-f3e016fcd39e |
conceptual |
11/11/2022 |
csharp |
ignite-2022 |
In Azure Functions, specific functions share a few core technical concepts and components, regardless of the language or binding you use. Before you jump into learning details specific to a given language or binding, be sure to read through this overview that applies to all of them.
This article assumes that you've already read the Azure Functions overview.
A function is the primary concept in Azure Functions. A function contains two important pieces - your code, which can be written in various languages, and some config, the function.json file. For compiled languages, this config file is generated automatically from annotations in your code. For scripting languages, you must provide the config file yourself.
The function.json file defines the function's trigger, bindings, and other configuration settings. Every function has one and only one trigger. The runtime uses this config file to determine the events to monitor and how to pass data into and return data from a function execution. The following is an example function.json file.
{
"disabled":false,
"bindings":[
// ... bindings here
{
"type": "bindingType",
"direction": "in",
"name": "myParamName",
// ... more depending on binding
}
]
}For more information, see Azure Functions triggers and bindings concepts.
The bindings property is where you configure both triggers and bindings. Each binding shares a few common settings and some settings, which are specific to a particular type of binding. Every binding requires the following settings:
| Property | Values | Type | Comments |
|---|---|---|---|
| type | Name of binding. For example, queueTrigger. |
string | |
| direction | in, out |
string | Indicates whether the binding is for receiving data into the function or sending data from the function. |
| name | Function identifier. For example, myQueue. |
string | The name that is used for the bound data in the function. For C#, this is an argument name; for JavaScript, it's the key in a key/value list. |
A function app provides an execution context in Azure in which your functions run. As such, it's the unit of deployment and management for your functions. A function app is composed of one or more individual functions that are managed, deployed, and scaled together. All of the functions in a function app share the same pricing plan, deployment method, and runtime version. Think of a function app as a way to organize and collectively manage your functions. To learn more, see How to manage a function app.
Note
All functions in a function app must be authored in the same language. In previous versions of the Azure Functions runtime, this wasn't required.
[!INCLUDE functions-folder-structure]
The above is the default (and recommended) folder structure for a Function app. If you wish to change the file location of a function's code, modify the scriptFile section of the function.json file. We also recommend using package deployment to deploy your project to your function app in Azure. You can also use existing tools like continuous integration and deployment and Azure DevOps.
Note
If deploying a package manually, make sure to deploy your host.json file and function folders directly to the wwwroot folder. Do not include the wwwroot folder in your deployments. Otherwise, you end up with wwwroot\wwwroot folders.
Function apps can be authored and published using a variety of tools, including Visual Studio, Visual Studio Code, IntelliJ, Eclipse, and the Azure Functions Core Tools. For more information, see Code and test Azure Functions locally.
The Functions editor built into the Azure portal lets you update your code and your function.json file directly inline. This is recommended only for small changes or proofs of concept - best practice is to use a local development tool like VS Code.
When multiple triggering events occur faster than a single-threaded function runtime can process them, the runtime may invoke the function multiple times in parallel. If a function app is using the Consumption hosting plan, the function app could scale out automatically. Each instance of the function app, whether the app runs on the Consumption hosting plan or a regular App Service hosting plan, might process concurrent function invocations in parallel using multiple threads. The maximum number of concurrent function invocations in each function app instance varies based on the type of trigger being used as well as the resources used by other functions within the function app.
You can configure the version of the Functions runtime using the FUNCTIONS_EXTENSION_VERSION app setting. For example, the value "~4" indicates that your function app uses 4.x as its major version. Function apps are upgraded to each new minor version as they're released. For more information, including how to view the exact version of your function app, see How to target Azure Functions runtime versions.
The code for Azure Functions is open source and stored in GitHub repositories:
- Azure Functions
- Azure Functions host
- Azure Functions portal
- Azure Functions templates
- Azure WebJobs SDK
- Azure WebJobs SDK Extensions
Here's a table of all supported bindings.
[!INCLUDE dynamic compute]
Having issues with errors coming from the bindings? Review the Azure Functions Binding Error Codes documentation.
Your function project references connection information by name from its configuration provider. It doesn't directly accept the connection details, allowing them to be changed across environments. For example, a trigger definition might include a connection property. This might refer to a connection string, but you can't set the connection string directly in a function.json. Instead, you would set connection to the name of an environment variable that contains the connection string.
The default configuration provider uses environment variables. These might be set by Application Settings when running in the Azure Functions service, or from the local settings file when developing locally.
When the connection name resolves to a single exact value, the runtime identifies the value as a connection string, which typically includes a secret. The details of a connection string are defined by the service to which you wish to connect.
However, a connection name can also refer to a collection of multiple configuration items, useful for configuring identity-based connections. Environment variables can be treated as a collection by using a shared prefix that ends in double underscores __. The group can then be referenced by setting the connection name to this prefix.
For example, the connection property for an Azure Blob trigger definition might be Storage1. As long as there's no single string value configured by an environment variable named Storage1, an environment variable named Storage1__blobServiceUri could be used to inform the blobServiceUri property of the connection. The connection properties are different for each service. Refer to the documentation for the component that uses the connection.
Note
When using Azure App Configuration or Key Vault to provide settings for Managed Identity connections, setting names should use a valid key separator such as : or / in place of the __ to ensure names are resolved correctly.
For example, Storage1:blobServiceUri.
Some connections in Azure Functions can be configured to use an identity instead of a secret. Support depends on the extension using the connection. In some cases, a connection string may still be required in Functions even though the service to which you're connecting supports identity-based connections. For a tutorial on configuring your function apps with managed identities, see the creating a function app with identity-based connections tutorial.
Note
When running in a Consumption or Elastic Premium plan, your app uses the WEBSITE_AZUREFILESCONNECTIONSTRING and WEBSITE_CONTENTSHARE settings when connecting to Azure Files on the storage account used by your function app. Azure Files doesn't support using managed identity when accessing the file share. For more information, see Azure Files supported authentication scenarios
The following components support identity-based connections:
[!INCLUDE functions-identity-based-connections-configuration]
Choose a tab below to learn about permissions for each component:
[!INCLUDE functions-blob-permissions]
[!INCLUDE functions-queue-permissions]
[!INCLUDE functions-table-permissions]
[!INCLUDE functions-event-hubs-permissions]
[!INCLUDE functions-service-bus-permissions]
[!INCLUDE functions-cosmos-permissions]
You need to create a role assignment that provides access to Azure SignalR Service data plane REST APIs. We recommend you to use the built-in role SignalR Service Owner. Management roles like Owner aren't sufficient.
[!INCLUDE functions-durable-permissions]
[!INCLUDE functions-azurewebjobsstorage-permissions]
An identity-based connection for an Azure service accepts the following common properties, where <CONNECTION_NAME_PREFIX> is the value of your connection property in the trigger or binding definition:
| Property | Environment variable template | Description |
|---|---|---|---|
| Token Credential | <CONNECTION_NAME_PREFIX>__credential | Defines how a token should be obtained for the connection. This setting should be set to managedidentity if your deployed Azure Function intends to use managed identity authentication. This value is only valid when a managed identity is available in the hosting environment. |
| Client ID | <CONNECTION_NAME_PREFIX>__clientId | When credential is set to managedidentity, this property can be set to specify the user-assigned identity to be used when obtaining a token. The property accepts a client ID corresponding to a user-assigned identity assigned to the application. It is invalid to specify both a Resource ID and a client ID. If not specified, the system-assigned identity is used. This property is used differently in local development scenarios, when credential shouldn't be set. |
| Resource ID | <CONNECTION_NAME_PREFIX>__managedIdentityResourceId | When credential is set to managedidentity, this property can be set to specify the resource Identifier to be used when obtaining a token. The property accepts a resource identifier corresponding to the resource ID of the user-defined managed identity. It's invalid to specify both a resource ID and a client ID. If neither are specified, the system-assigned identity is used. This property is used differently in local development scenarios, when credential shouldn't be set.
Additional options may be supported for a given connection type. Refer to the documentation for the component making the connection.
Note
Local development with identity-based connections requires updated versions of the Azure Functions Core Tools. You can check your currently installed version by running func -v. For Functions v3, use version 3.0.3904 or later. For Functions v4, use version 4.0.3904 or later.
When you're running your function project locally, the above configuration tells the runtime to use your local developer identity. The connection attempts to get a token from the following locations, in order:
- A local cache shared between Microsoft applications
- The current user context in Visual Studio
- The current user context in Visual Studio Code
- The current user context in the Azure CLI
If none of these options are successful, an error occurs.
Your identity may already have some role assignments against Azure resources used for development, but those roles may not provide the necessary data access. Management roles like Owner aren't sufficient. Double-check what permissions are required for connections for each component, and make sure that you have them assigned to yourself.
In some cases, you may wish to specify use of a different identity. You can add configuration properties for the connection that point to the alternate identity based on a client ID and client Secret for an Azure Active Directory service principal. This configuration option is not supported when hosted in the Azure Functions service. To use an ID and secret on your local machine, define the connection with the following additional properties:
| Property | Environment variable template | Description |
|---|---|---|
| Tenant ID | <CONNECTION_NAME_PREFIX>__tenantId |
The Azure Active Directory tenant (directory) ID. |
| Client ID | <CONNECTION_NAME_PREFIX>__clientId |
The client (application) ID of an app registration in the tenant. |
| Client secret | <CONNECTION_NAME_PREFIX>__clientSecret |
A client secret that was generated for the app registration. |
Here's an example of local.settings.json properties required for identity-based connection to Azure Blobs:
{
"IsEncrypted": false,
"Values": {
"<CONNECTION_NAME_PREFIX>__blobServiceUri": "<blobServiceUri>",
"<CONNECTION_NAME_PREFIX>__queueServiceUri": "<queueServiceUri>",
"<CONNECTION_NAME_PREFIX>__tenantId": "<tenantId>",
"<CONNECTION_NAME_PREFIX>__clientId": "<clientId>",
"<CONNECTION_NAME_PREFIX>__clientSecret": "<clientSecret>"
}
}The Azure Functions host uses the AzureWebJobsStorage connection for core behaviors such as coordinating singleton execution of timer triggers and default app key storage. This can be configured to use an identity as well.
Caution
Other components in Functions rely on AzureWebJobsStorage for default behaviors. You should not move it to an identity-based connection if you are using older versions of extensions that do not support this type of connection, including triggers and bindings for Azure Blobs, Event Hubs, and Durable Functions. Similarly, AzureWebJobsStorage is used for deployment artifacts when using server-side build in Linux Consumption, and if you enable this, you will need to deploy via an external deployment package.
In addition, some apps reuse AzureWebJobsStorage for other storage connections in their triggers, bindings, and/or function code. Make sure that all uses of AzureWebJobsStorage are able to use the identity-based connection format before changing this connection from a connection string.
To use an identity-based connection for AzureWebJobsStorage, configure the following app settings:
| Setting | Description | Example value |
|---|---|---|
AzureWebJobsStorage__blobServiceUri |
The data plane URI of the blob service of the storage account, using the HTTPS scheme. | https://<storage_account_name>.blob.core.windows.net |
AzureWebJobsStorage__queueServiceUri |
The data plane URI of the queue service of the storage account, using the HTTPS scheme. | https://<storage_account_name>.queue.core.windows.net |
AzureWebJobsStorage__tableServiceUri |
The data plane URI of a table service of the storage account, using the HTTPS scheme. | https://<storage_account_name>.table.core.windows.net |
Common properties for identity-based connections may also be set as well.
If you're configuring AzureWebJobsStorage using a storage account that uses the default DNS suffix and service name for global Azure, following the https://<accountName>.blob/queue/file/table.core.windows.net format, you can instead set AzureWebJobsStorage__accountName to the name of your storage account. The endpoints for each storage service will be inferred for this account. This won't work if the storage account is in a sovereign cloud or has a custom DNS.
| Setting | Description | Example value |
|---|---|---|
AzureWebJobsStorage__accountName |
The account name of a storage account, valid only if the account isn't in a sovereign cloud and doesn't have a custom DNS. This syntax is unique to AzureWebJobsStorage and can't be used for other identity-based connections. |
<storage_account_name> |
[!INCLUDE functions-azurewebjobsstorage-permissions]
[!INCLUDE Reporting Issues]
For more information, see the following resources: