Create your first durable function in C#

Durable Functions is an extension of Azure Functions that lets you write stateful functions in a serverless environment. The extension manages state, checkpoints, and restarts for you.

In this article, you learn how to use Visual Studio Code to locally create and test a "hello world" durable function. This function orchestrates and chains-together calls to other functions. You then publish the function code to Azure. These tools are available as part of the VS Code Azure Functions extension.

Screenshot shows a Visual Studio Code window with a durable function.

Prerequisites

To complete this tutorial:

If you don't have an Azure subscription, create a free account before you begin.

Create your local project

In this section, you use Visual Studio Code to create a local Azure Functions project.

  1. In Visual Studio Code, press F1 (or Ctrl/Cmd+Shift+P) to open the command palette. In the command palette, search for and select Azure Functions: Create New Project....

    Create a function project

  2. Choose an empty folder location for your project and choose Select.

  3. Following the prompts, provide the following information:

    Prompt Value Description
    Select a language for your function app project C# Create a local C# Functions project.
    Select a version Azure Functions v3 You only see this option when the Core Tools aren't already installed. In this case, Core Tools are installed the first time you run the app.
    Select a template for your project's first function Skip for now
    Select how you would like to open your project Open in current window Reopens VS Code in the folder you selected.

Visual Studio Code installs the Azure Functions Core Tools, if needed. It also creates a function app project in a folder. This project contains the host.json and local.settings.json configuration files.

Add functions to the app

The following steps use a template to create the durable function code in your project.

  1. In the command palette, search for and select Azure Functions: Create Function....

  2. Following the prompts, provide the following information:

    Prompt Value Description
    Select a template for your function DurableFunctionsOrchestration Create a Durable Functions orchestration
    Provide a function name HelloOrchestration Name of the class in which functions are created
    Provide a namespace Company.Function Namespace for the generated class
  3. When VS Code prompts you to select a storage account, choose Select storage account. Following the prompts, provide the following information to create a new storage account in Azure.

    Prompt Value Description
    Select subscription name of your subscription Select your Azure subscription
    Select a storage account Create a new storage account
    Enter the name of the new storage account unique name Name of the storage account to create
    Select a resource group unique name Name of the resource group to create
    Select a location region Select a region close to you

A class containing the new functions is added to the project. VS Code also adds the storage account connection string to local.settings.json and a reference to the Microsoft.Azure.WebJobs.Extensions.DurableTask NuGet package to the .csproj project file.

Open the new HelloOrchestration.cs file to view the contents. This durable function is a simple function chaining example with the following methods:

Method FunctionName Description
RunOrchestrator HelloOrchestration Manages the durable orchestration. In this case, the orchestration starts, creates a list, and adds the result of three functions calls to the list. When the three function calls are complete, it returns the list.
SayHello HelloOrchestration_Hello The function returns a hello. It is the function that contains the business logic that is being orchestrated.
HttpStart HelloOrchestration_HttpStart An HTTP-triggered function that starts an instance of the orchestration and returns a check status response.

Now that you've created your function project and a durable function, you can test it on your local computer.

Test the function locally

Azure Functions Core Tools lets you run an Azure Functions project on your local development computer. You're prompted to install these tools the first time you start a function from Visual Studio Code.

  1. To test your function, set a breakpoint in the SayHello activity function code and press F5 to start the function app project. Output from Core Tools is displayed in the Terminal panel.

    Note

    Refer to the Durable Functions Diagnostics for more information on debugging.

  2. In the Terminal panel, copy the URL endpoint of your HTTP-triggered function.

    Azure local output

  3. Using a tool like Postman or cURL, send an HTTP POST request to the URL endpoint.

    The response is the initial result from the HTTP function letting us know the durable orchestration has started successfully. It is not yet the end result of the orchestration. The response includes a few useful URLs. For now, let's query the status of the orchestration.

  4. Copy the URL value for statusQueryGetUri and paste it in the browser's address bar and execute the request. Alternatively you can also continue to use Postman to issue the GET request.

    The request will query the orchestration instance for the status. You should get an eventual response, which shows us the instance has completed, and includes the outputs or results of the durable function. It looks like:

    {
        "name": "HelloOrchestration",
        "instanceId": "9a528a9e926f4b46b7d3deaa134b7e8a",
        "runtimeStatus": "Completed",
        "input": null,
        "customStatus": null,
        "output": [
            "Hello Tokyo!",
            "Hello Seattle!",
            "Hello London!"
        ],
        "createdTime": "2020-03-18T21:54:49Z",
        "lastUpdatedTime": "2020-03-18T21:54:54Z"
    }
    
  5. To stop debugging, press Shift + F5 in VS Code.

After you've verified that the function runs correctly on your local computer, it's time to publish the project to Azure.

Sign in to Azure

Before you can publish your app, you must sign in to Azure.

  1. If you aren't already signed in, choose the Azure icon in the Activity bar, then in the Azure: Functions area, choose Sign in to Azure.... If you don't already have one, you can Create a free Azure account. Students can create a free Azure account for Students.

    Sign in to Azure within VS Code

    If you're already signed in, go to the next section.

  2. When prompted in the browser, choose your Azure account and sign in using your Azure account credentials.

  3. After you've successfully signed in, you can close the new browser window. The subscriptions that belong to your Azure account are displayed in the Side bar.

Publish the project to Azure

In this section, you create a function app and related resources in your Azure subscription and then deploy your code.

Important

Publishing to an existing function app overwrites the content of that app in Azure.

  1. Choose the Azure icon in the Activity bar, then in the Azure: Functions area, choose the Deploy to function app... button.

    Publish your project to Azure

  2. Provide the following information at the prompts:

    • Select folder: Choose a folder from your workspace or browse to one that contains your function app. You won't see this if you already have a valid function app opened.

    • Select subscription: Choose the subscription to use. You won't see this if you only have one subscription.

    • Select Function App in Azure: Choose - Create new Function App. (Don't choose the Advanced option, which isn't covered in this article.)

    • Enter a globally unique name for the function app: Type a name that is valid in a URL path. The name you type is validated to make sure that it's unique in Azure Functions.

    • Select a location for new resources: For better performance, choose a region near you.

  3. When completed, the following Azure resources are created in your subscription, using names based on your function app name:

    • A resource group, which is a logical container for related resources.
    • A standard Azure Storage account, which maintains state and other information about your projects.
    • A consumption plan, which defines the underlying host for your serverless function app.
    • A function app, which provides the environment for executing your function code. A function app lets you group functions as a logical unit for easier management, deployment, and sharing of resources within the same hosting plan.
    • An Application Insights instance connected to the function app, which tracks usage of your serverless function.

    A notification is displayed after your function app is created and the deployment package is applied.

  4. Select View Output in this notification to view the creation and deployment results, including the Azure resources that you created. If you miss the notification, select the bell icon in the lower right corner to see it again.

    Create complete notification

Test your function in Azure

  1. Copy the URL of the HTTP trigger from the Output panel. The URL that calls your HTTP-triggered function should be in the following format:

    https://<functionappname>.azurewebsites.net/api/HelloOrchestration_HttpStart

  2. Paste this new URL for the HTTP request into your browser's address bar. You should get the same status response as before when using the published app.

Next steps

You have used Visual Studio Code to create and publish a C# durable function app.

In this article, you learn how to Visual Studio 2019 to locally create and test a "hello world" durable function. This function orchestrates and chains-together calls to other functions. You then publish the function code to Azure. These tools are available as part of the Azure development workload in Visual Studio 2019.

Screenshot shows a Visual Studio 2019 window with a durable function.

Prerequisites

To complete this tutorial:

  • Install Visual Studio 2019. Make sure that the Azure development workload is also installed. Visual Studio 2017 also supports Durable Functions development, but the UI and steps differ.

  • Verify you have the Azure Storage Emulator installed and running.

If you don't have an Azure subscription, create a free account before you begin.

Create a function app project

The Azure Functions template creates a project that can be published to a function app in Azure. A function app lets you group functions as a logical unit for easier management, deployment, scaling, and sharing of resources.

  1. In Visual Studio, select New > Project from the File menu.

  2. In the Create a new project dialog, search for functions, choose the Azure Functions template, and select Next.

    New project dialog to create a function in Visual Studio

  3. Type a Project name for your project, and select OK. The project name must be valid as a C# namespace, so don't use underscores, hyphens, or any other nonalphanumeric characters.

  4. In Create a new Azure Functions Application, use the settings specified in the table that follows the image.

    Create a new Azure Functions Application dialog in Visual Studio

    Setting Suggested value Description
    Version Azure Functions 3.0
    (.NET Core)
    Creates a function project that uses the version 3.0 runtime of Azure Functions, which supports .NET Core 3.1. For more information, see How to target Azure Functions runtime version.
    Template Empty Creates an empty function app.
    Storage account Storage Emulator A storage account is required for durable function state management.
  5. Select Create to create an empty function project. This project has the basic configuration files needed to run your functions.

Add functions to the app

The following steps use a template to create the durable function code in your project.

  1. Right-click the project in Visual Studio and select Add > New Azure Function.

    Add new function

  2. Verify Azure Function is selected from the add menu, type a name for your C# file, and then select Add.

  3. Select the Durable Functions Orchestration template and then select Ok

    Select durable template

A new durable function is added to the app. Open the new .cs file to view the contents. This durable function is a simple function chaining example with the following methods:

Method FunctionName Description
RunOrchestrator <file-name> Manages the durable orchestration. In this case, the orchestration starts, creates a list, and adds the result of three functions calls to the list. When the three function calls are complete, it returns the list.
SayHello <file-name>_Hello The function returns a hello. It is the function that contains the business logic that is being orchestrated.
HttpStart <file-name>_HttpStart An HTTP-triggered function that starts an instance of the orchestration and returns a check status response.

Now that you've created your function project and a durable function, you can test it on your local computer.

Test the function locally

Azure Functions Core Tools lets you run an Azure Functions project on your local development computer. You are prompted to install these tools the first time you start a function from Visual Studio.

  1. To test your function, press F5. If prompted, accept the request from Visual Studio to download and install Azure Functions Core (CLI) tools. You may also need to enable a firewall exception so that the tools can handle HTTP requests.

  2. Copy the URL of your function from the Azure Functions runtime output.

    Azure local runtime

  3. Paste the URL for the HTTP request into your browser's address bar and execute the request. The following shows the response in the browser to the local GET request returned by the function:

    Screenshot shows a browser window with statusQueryGetUri called out.

    The response is the initial result from the HTTP function letting us know the durable orchestration has started successfully. It is not yet the end result of the orchestration. The response includes a few useful URLs. For now, let's query the status of the orchestration.

  4. Copy the URL value for statusQueryGetUri and pasting it in the browser's address bar and execute the request.

    The request will query the orchestration instance for the status. You should get an eventual response that looks like the following. This output shows us the instance has completed, and includes the outputs or results of the durable function.

    {
        "instanceId": "d495cb0ac10d4e13b22729c37e335190",
        "runtimeStatus": "Completed",
        "input": null,
        "customStatus": null,
        "output": [
            "Hello Tokyo!",
            "Hello Seattle!",
            "Hello London!"
        ],
        "createdTime": "2019-11-02T07:07:40Z",
        "lastUpdatedTime": "2019-11-02T07:07:52Z"
    }
    
  5. To stop debugging, press Shift + F5.

After you have verified that the function runs correctly on your local computer, it's time to publish the project to Azure.

Publish the project to Azure

You must have a function app in your Azure subscription before you can publish your project. You can create a function app right from Visual Studio.

  1. In Solution Explorer, right-click the project and select Publish.

  2. In Target, select Azure Select Azure target

  3. In Specific target, select Azure Function App (Windows)

    Select Azure Function App

  4. In Function Instance, select Create a new Azure Function... and then use the values specified in the following table:

    Setting Value Description
    Name Globally unique name Name that uniquely identifies your new function app. Accept this name or enter a new name. Valid characters are: a-z, 0-9, and -.
    Subscription Your subscription The Azure subscription to use. Accept this subscription or select a new one from the drop-down list.
    Resource group Name of your resource group The resource group in which to create your function app. Select an existing resource group from the drop-down list or choose New to create a new resource group.
    Plan Type Consumption When you publish your project to a function app that runs in a Consumption plan, you pay only for executions of your functions app. Other hosting plans incur higher costs.
    Location Location of the app service Choose a Location in a region near you or other services your functions access.
    Azure Storage General-purpose storage account An Azure Storage account is required by the Functions runtime. Select New to configure a general-purpose storage account. You can also choose an existing account that meets the storage account requirements.

    Create App Service dialog

  5. Select Create to create a function app and its related resources in Azure.

  6. In the Functions instance, make sure that Run from package file is checked. Your function app is deployed using Zip Deploy with Run-From-Package mode enabled. This is the recommended deployment method for your functions project, since it results in better performance.

    Finish profile creation

  7. Select Finish, and on the Publish page, select Publish to deploy the package containing your project files to your new function app in Azure.

    After the deployment completes the root URL of the function app in Azure is shown in the Publish tab.

  8. In the Publish tab, choose Manage in Cloud Explorer. This opens the new function app Azure resource in Cloud Explorer.

    Publish success message

    Cloud Explorer lets you use Visual Studio to view the contents of the site, start and stop the function app, and browse directly to function app resources on Azure and in the Azure portal.

Test your function in Azure

  1. Copy the base URL of the function app from the Publish profile page. Replace the localhost:port portion of the URL you used when testing the function locally with the new base URL.

    The URL that calls your durable function HTTP trigger should be in the following format:

    https://<APP_NAME>.azurewebsites.net/api/<FUNCTION_NAME>_HttpStart

  2. Paste this new URL for the HTTP request into your browser's address bar. You should get the same status response as before when using the published app.

Next steps

You have used Visual Studio to create and publish a C# durable function app.