Local Settings for Azure Functions

Configure and manage settings for your Azure Functions during local development.

Key Concept: Local settings are crucial for mimicking the Azure environment on your development machine, allowing for efficient testing and debugging without deploying to the cloud.

Understanding `local.settings.json`

The primary configuration file for local Azure Functions development is local.settings.json. This file allows you to define application settings, connection strings, and other environment-specific configurations.

File Structure

The local.settings.json file typically has the following structure:

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "FUNCTIONS_WORKER_RUNTIME": "dotnet",
    "MyCustomSetting": "MyValue",
    "CosmosDbConnectionString": "AccountEndpoint=http://localhost:8080/...",
    "ServiceBusConnectionString": "Endpoint=sb://..."
  },
  "Host": {
    "LocalDevelopmentStorageConnectionString": "UseDevelopmentStorage=true"
  }
}

Key Properties

IsEncrypted: Indicates whether the settings in the Values section are encrypted. In local development, this is typically false.
Values: A dictionary containing your application settings and connection strings. These are accessible to your functions via environment variables.
Host: Contains settings specific to the Functions host, such as LocalDevelopmentStorageConnectionString.

Common Settings

`AzureWebJobsStorage`

This setting defines the connection string for the Azure Storage account that the Functions host uses for its operations, such as managing triggers, queues, and blobs. For local development, you can often use the Azure Storage Emulator:

"AzureWebJobsStorage": "UseDevelopmentStorage=true"

Alternatively, you can point it to a real Azure Storage account for more accurate testing:

"AzureWebJobsStorage": "DefaultEndpointsProtocol=https;AccountName=your_storage_account;AccountKey=your_account_key;EndpointSuffix=core.windows.net"

`FUNCTIONS_WORKER_RUNTIME`

Specifies the runtime for your functions. Common values include dotnet, node, python, java, and powershell.

"FUNCTIONS_WORKER_RUNTIME": "dotnet"

Custom Application Settings

You can define any custom key-value pairs for your application settings. These are useful for storing API keys, configuration parameters, or endpoint URLs.

"MyApiUrl": "https://api.example.com/v1",
"SubscriptionId": "abcdef12-3456-7890-abcd-ef1234567890"

Connection Strings

Store connection strings for services like Azure Cosmos DB, Azure SQL Database, Azure Service Bus, or any other external dependencies.

"CosmosDbConnectionString": "AccountEndpoint=https://your-cosmosdb-account.documents.azure.com:443/;AccountKey=your_cosmos_db_key;",
"ServiceBusConnectionString": "Endpoint=sb://your-namespace.servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=your_service_bus_key"

Tip: It's a best practice to avoid hardcoding sensitive information directly in your code. Use local.settings.json for local development and Azure Key Vault or App Settings in Azure for production.

Accessing Settings in Your Functions

Settings defined in the Values section of local.settings.json are automatically loaded as environment variables. You can access them using the standard methods for your language:

C# Example

using Microsoft.Azure.WebJobs;
using Microsoft.Extensions.Logging;
using System;

public static class MyFunction
{
    [FunctionName("MyHttpTrigger")]
    public static void Run(
        [HttpTrigger(AuthorizationLevel.Function, "get", "post", Route = null)] HttpRequest req,
        ILogger log)
    {
        log.LogInformation("C# HTTP trigger function processed a request.");

        string customSetting = Environment.GetEnvironmentVariable("MyCustomSetting");
        string apiUrl = Environment.GetEnvironmentVariable("MyApiUrl");

        log.LogInformation($"Custom Setting: {customSetting}");
        log.LogInformation($"API URL: {apiUrl}");

        // ... function logic
    }
}

Node.js Example

module.exports = async function (context, req) {
    context.log('JavaScript HTTP trigger function processed a request.');

    const customSetting = process.env.MyCustomSetting;
    const apiUrl = process.env.MyApiUrl;

    context.log(`Custom Setting: ${customSetting}`);
    context.log(`API URL: ${apiUrl}`);

    // ... function logic
};

Working with Secrets and Encryption

For sensitive information like API keys or passwords, it is highly recommended to encrypt them. The Azure Functions Core Tools support encrypting your local.settings.json file.

To encrypt:

func settings encrypt

This will update the IsEncrypted property to true and encrypt the values in the Values section. The Core Tools will prompt you for a master key password if one is not already set.

Important: Never commit your unencrypted local.settings.json file containing sensitive information to source control. Use a separate, unencrypted file (e.g., appsettings.Development.json) for non-sensitive local settings or store secrets securely.

Local Storage Emulator

When you set AzureWebJobsStorage to UseDevelopmentStorage=true, your functions will connect to the Azure Storage Emulator. This emulator provides local implementations of Azure Storage services (Blob Storage, Table Storage, Queue Storage).

Ensure the Azure Storage Emulator is installed and running on your development machine. You can typically find it as part of the Azure SDK for .NET or as a standalone download.

Troubleshooting

Settings not loading: Ensure local.settings.json is in the root of your Function App project. Restart your Functions host after making changes.
Connection issues: Verify that your connection strings are correct and that any required local emulators (like the Storage Emulator) are running.
Encryption errors: Make sure you have a master key set up if you are using encryption.