Skip to content

Latest commit

 

History

History
122 lines (90 loc) · 14.4 KB

functions-develop-local.md

File metadata and controls

122 lines (90 loc) · 14.4 KB
title description ms.topic ms.date
Develop and run Azure Functions locally
Learn how to code and test Azure Functions on your local computer before you run them on Azure Functions.
conceptual
09/22/2022

Code and test Azure Functions locally

While you're able to develop and test Azure Functions in the Azure portal, many developers prefer a local development experience. When you use Functions, using your favorite code editor and development tools to create and test functions on your local computer becomes easier. Your local functions can connect to live Azure services, and you can debug them on your local computer using the full Functions runtime.

This article provides links to specific development environments for your preferred language. It also provides some shared guidance for local development, such as working with the local.settings.json file.

Local development environments

The way in which you develop functions on your local computer depends on your language and tooling preferences. The environments in the following table support local development:

Environment Languages Description
Visual Studio Code C# (in-process)
C# (isolated worker process)
JavaScript
PowerShell
Python		 The Azure Functions extension for VS Code adds Functions support to VS Code. Requires the Core Tools. Supports development on Linux, macOS, and Windows, when using version 2.x of the Core Tools. To learn more, see Create your first function using Visual Studio Code.
Command prompt or terminal C# (in-process)
C# (isolated worker process)
JavaScript
PowerShell
Python		 Azure Functions Core Tools provides the core runtime and templates for creating functions, which enable local development. Version 2.x supports development on Linux, macOS, and Windows. All environments rely on Core Tools for the local Functions runtime.
Visual Studio C# (in-process)
C# (isolated worker process)		 The Azure Functions tools are included in the Azure development workload of Visual Studio, starting with Visual Studio 2019. Lets you compile functions in a class library and publish the .dll to Azure. Includes the Core Tools for local testing. To learn more, see Develop Azure Functions using Visual Studio.
Maven (various) Java Maven archetype supports Core Tools to enable development of Java functions. Version 2.x supports development on Linux, macOS, and Windows. To learn more, see Create your first function with Java and Maven. Also supports development using Eclipse and IntelliJ IDEA.

[!INCLUDE Don't mix development environments]

Each of these local development environments lets you create function app projects and use predefined function templates to create new functions. Each uses the Core Tools so that you can test and debug your functions against the real Functions runtime on your own machine just as you would any other app. You can also publish your function app project from any of these environments to Azure.

Local settings file

The local.settings.json file stores app settings and settings used by local development tools. Settings in the local.settings.json file are used only when you're running your project locally. When you publish your project to Azure, be sure to also add any required settings to the app settings for the function app.

Important

Because the local.settings.json may contain secrets, such as connection strings, you should never store it in a remote repository. Tools that support Functions provide ways to synchronize settings in the local.settings.json file with the app settings in the function app to which your project is deployed.

The local settings file has this structure:

{
  "IsEncrypted": false,
  "Values": {
    "FUNCTIONS_WORKER_RUNTIME": "<language worker>",
    "AzureWebJobsStorage": "<connection-string>",
    "MyBindingConnection": "<binding-connection-string>",
    "AzureWebJobs.HttpExample.Disabled": "true"
  },
  "Host": {
    "LocalHttpPort": 7071,
    "CORS": "*",
    "CORSCredentials": false
  },
  "ConnectionStrings": {
    "SQLConnectionString": "<sqlclient-connection-string>"
  }
}

These settings are supported when you run projects locally:

Setting Description
IsEncrypted When this setting is set to true, all values are encrypted with a local machine key. Used with func settings commands. Default value is false. You might want to encrypt the local.settings.json file on your local computer when it contains secrets, such as service connection strings. The host automatically decrypts settings when it runs. Use the func settings decrypt command before trying to read locally encrypted settings.
Values Collection of application settings used when a project is running locally. These key-value (string-string) pairs correspond to application settings in your function app in Azure, like AzureWebJobsStorage. Many triggers and bindings have a property that refers to a connection string app setting, like Connection for the Blob storage trigger. For these properties, you need an application setting defined in the Values array. See the subsequent table for a list of commonly used settings.
Values must be strings and not JSON objects or arrays. Setting names can't include a double underline (__) and shouldn't include a colon (:). Double underline characters are reserved by the runtime, and the colon is reserved to support dependency injection.
Host Settings in this section customize the Functions host process when you run projects locally. These settings are separate from the host.json settings, which also apply when you run projects in Azure.
LocalHttpPort Sets the default port used when running the local Functions host (func host start and func run). The --port command-line option takes precedence over this setting. For example, when running in Visual Studio IDE, you may change the port number by navigating to the "Project Properties -> Debug" window and explicitly specifying the port number in a host start --port <your-port-number> command that can be supplied in the "Application Arguments" field.
CORS Defines the origins allowed for cross-origin resource sharing (CORS). Origins are supplied as a comma-separated list with no spaces. The wildcard value (*) is supported, which allows requests from any origin.
CORSCredentials When set to true, allows withCredentials requests.
ConnectionStrings A collection. Don't use this collection for the connection strings used by your function bindings. This collection is used only by frameworks that typically get connection strings from the ConnectionStrings section of a configuration file, like Entity Framework. Connection strings in this object are added to the environment with the provider type of System.Data.SqlClient. Items in this collection aren't published to Azure with other app settings. You must explicitly add these values to the Connection strings collection of your function app settings. If you're creating a SqlConnection in your function code, you should store the connection string value with your other connections in Application Settings in the portal.

The following application settings can be included in the Values array when running locally:

Setting Values Description
AzureWebJobsStorage Storage account connection string, or
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.
When you have the Azurite Emulator installed locally and you set AzureWebJobsStorage to UseDevelopmentStorage=true, Core Tools uses the emulator. For more information, see Local storage emulator.
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.
FUNCTIONS_WORKER_RUNTIME dotnet
dotnet-isolated
node
java
powershell
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 reference.
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.

Synchronize settings

When you develop your functions locally, any local settings required by your app must also be present in app settings of the function app to which your code is deployed. You may also need to download current settings from the function app to your local project. While you can manually configure app settings in the Azure portal, the following tools also let you synchronize app settings with local settings in your project:

Triggers and bindings

When you develop your functions locally, you need to take trigger and binding behaviors into consideration. The easiest way to test bindings during local development is to use connection strings that target live Azure services. You can target live services by adding the appropriate connection string settings in the Values array in the local.settings.json file. When you do this, local executions during testing impact live service data. Because of this, consider setting-up separate services to use during development and testing, and then switch to difference services during production. You can also use a local storage emulator.

Local storage emulator

During local development, you can use the local Azurite emulator when testing functions with Azure Storage bindings (Queue Storage, Blob Storage, and Table Storage), without having to connect to remote storage services. Azurite integrates with Visual Studio Code and Visual Studio, and you can also run it from the command prompt using npm. For more information, see Use the Azurite emulator for local Azure Storage development.

The following setting in the Values collection of the local.settings.json file tells the local Functions host to use Azurite for the default AzureWebJobsStorage connection:

"AzureWebJobsStorage": "UseDevelopmentStorage=true"

With this setting in place, any Azure Storage trigger or binding that uses AzureWebJobsStorage as its connection connects to Azurite when running locally. During local execution, you must have Azurite installed and running. The emulator is useful during development, but you should test with an actual storage connection before deployment. When you publish your project, don't publish this setting. You need to instead use an Azure Storage connection string in the same settings in your function app in Azure.

Next steps