Azure Functions Documentation

Understanding local.settings.json for Azure Functions

The local.settings.json file is crucial for configuring your Azure Functions project when running locally. It allows you to define application settings, connection strings, and other configuration values that your functions will use.

Purpose of local.settings.json

When you develop and test Azure Functions locally, you need a way to provide configuration settings that would typically be managed in Azure's application settings. local.settings.json serves this purpose. It's not deployed to Azure; instead, its values are used by the Azure Functions Core Tools to mimic the cloud environment.

File Structure

The local.settings.json file is a JSON file with a root object containing several key properties:

• IsEncrypted: A boolean indicating whether settings are encrypted.
• Values: An object containing key-value pairs for your application settings.
• ConnectionStrings: An object containing key-value pairs for your connection strings.

Here's a typical structure:

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "FUNCTIONS_WORKER_RUNTIME": "dotnet",
    "MyCustomSetting": "SomeValue",
    "API_KEY": "your-local-api-key"
  },
  "ConnectionStrings": {
    "SqlConnectionString": "Server=.;Database=MyLocalDb;Trusted_Connection=True;"
  }
}

Key Properties Explained

IsEncrypted

This boolean property indicates whether the local.settings.json file contains sensitive information that has been encrypted. If true, the Core Tools will automatically decrypt it. If false, the settings are treated as plain text.

Values

This object holds your application settings. These are typically accessed within your function code using environment variables. For example, a setting named MyCustomSetting would be accessible as an environment variable of the same name.

Common settings include:

• AzureWebJobsStorage: The storage account used by the Functions runtime for operations like trigger and output bindings. When running locally, UseDevelopmentStorage=true is common to use the Azure Storage Emulator.
• FUNCTIONS_WORKER_RUNTIME: Specifies the language worker runtime (e.g., dotnet, node, python, java).

ConnectionStrings

This object is specifically for storing connection strings for databases, service buses, or other services your functions might interact with. These are also accessed as environment variables, often with a prefix like CUSTOMCONNSTR_ in Azure, but directly by name in local.settings.json.

Using Settings in Your Code

The values defined in local.settings.json are exposed as environment variables when your function app runs locally. Here's how you might access them in different languages:

C# (.NET)

var apiKey = Environment.GetEnvironmentVariable("API_KEY");
var sqlConnectionString = Environment.GetEnvironmentVariable("SqlConnectionString");

JavaScript (Node.js)

const apiKey = process.env.API_KEY;
const sqlConnectionString = process.env.SqlConnectionString;

Python

import os
api_key = os.environ.get("API_KEY")
sql_connection_string = os.environ.get("SqlConnectionString")

Security Considerations

Never commit your local.settings.json file to source control if it contains sensitive information like passwords or API keys. Use a .gitignore file to exclude it.

For sensitive data, consider using Azure Key Vault or a secrets management solution. When deploying to Azure, these settings are managed directly in the Azure portal or through infrastructure-as-code tools.

Working with Local Storage Emulator

To use the Azure Storage Emulator for AzureWebJobsStorage, ensure it's installed and running. The setting UseDevelopmentStorage=true tells the Functions host to connect to the emulator instead of a real Azure Storage account.

Synchronizing with Azure App Settings

When you deploy your functions to Azure, you'll need to replicate the settings from local.settings.json in your Azure Function App's application settings. This can be done manually through the Azure portal, using Azure CLI commands, or by integrating with your CI/CD pipeline.

The Azure Functions Core Tools can help synchronize these settings when deploying. For example, using the func azure functionapp publish command can prompt you to sync settings.

Troubleshooting

• Ensure the JSON file is correctly formatted.
• Verify that the file is named exactly local.settings.json and is in the root of your project.
• Restart your Functions host after making changes to local.settings.json.
• Check that you are accessing the settings with the correct casing and names in your code.