Debugging your function locally

Using the Visual Studio debugger (or the Visual Studio Code debugger), you can debug your function locally as you do for any other program written in .NET: you can insert breakpoints, run the software step by step, or use the debug console.

The issue, when you debug an Azure Function, is that your function, generally, doesn't live alone: it writes data to Blob storage, reads items from a storage queue, or inserts documents into a Cosmos DB database.

The question is: how can you emulate the binding endpoints?

Of course, if you have an internet connection, you can use Azure resources (for example, Blob storage) directly but your debug experience will not be the best. On the other hand, if you haven't got an internet connection (for example, you need to debug your function while you are on a flight), you won't have access to the Azure resources you need and you won't be able to debug your code.

Fortunately, you can emulate some of the resources involved in the function bindings using Microsoft Azure Storage Emulator or Azure Cosmos Emulator.

Microsoft Azure Storage Emulator provides you with a local environment that emulates the services exposed by Queue, Table, and Blob storage.

At the time of writing this book, the Microsoft Azure Storage Emulator runs only on Windows, but there is an open source version called Azurite (https://github.com/azure/azurite) that runs on Linux.

Microsoft Azure Storage Emulator uses a local Microsoft SQL instance (SQL Server 2012 Express LocalDB) and the filesystem to emulate the Azure storage services. Microsoft Azure Storage Emulator is a command-line tool, generally installed in the C:\Program Files (x86)\Microsoft SDKs\Azure\Storage Emulator folder, and supports a set of commands that allow you to configure the tool as you want. You can retrieve the command list by running AzureStorageEmulator.exe:

You can start the emulator using the init command and configure it to use your specific version of SQL Server:

AzureStorageEmulator.exe init -server MySQLServer -sqlinstance MySQLInstance

With the previous command, for example, you start the emulator using the instance of SQL Database called MySQLInstance hosted in the MySQLServer server.

To use the emulator in your Azure Function, you simply set the AzureWebJobsStorage value in local.settings.json to UseDevelopmentStorage=true. Setting this value, once you start your local debugging, the Azure Functions runtime starts the emulator (if it isn't running yet).

Microsoft Azure Cosmos Emulator provides a local environment that emulates Azure Cosmos DB services. Using Azure Cosmos Emulator, you can debug an Azure Function with Cosmos DB binding locally, without creating a Cosmos DB instance in your Azure subscription. When you're satisfied with how your application is working in Azure Cosmos Emulator, you can switch to using an Azure Cosmos account in the cloud.

Azure Cosmos Emulator uses local resources to emulate some Cosmos DB features, but not all the features that you can find in Azure Cosmos DB instances are implemented. For example, features such as global replication, single-digit millisecond latency for reads/writes, and tunable consistency levels are not implemented.

Azure Cosmos Emulator runs only on Windows systems. If you need to run the emulator on other operating systems, you can install it in a Docker container (more info at https://github.com/Azure/azure-cosmos-db-emulator-docker).

Generally, Azure Cosmos Emulator is installed on C:\Program Files\Azure Cosmos DB Emulator and, like Microsoft Azure Storage Emulator, it provides a CLI that allows you to configure, as you want, the emulator. To get all the possible options supported by the emulator, you can run the following command:

C:\Program Files\Azure Cosmos DB Emulator>CosmosDB.Emulator.exe /?

If you run the emulator with the default settings, it uses the %LocalAppdata%\CosmosDBEmulator folder to store the data and provides you with a web UI on port 8081 (https://localhost:8081/_explorer/index.html):

The console is opened automatically when you start the emulator and provides you with information about the connection string and the primary key to connect to the instance from your function and allows you to make queries in the Cosmos DB local instance (using the Explorer tab on the left).

Unfortunately, for the other types of binding (for example, SendGrid or Twilio), there aren't emulators. So, in those scenarios, you can debug your function locally, but you must use the online services.