Create your first durable function in TypeScript
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 the Visual Studio Code Azure Functions extension to locally create and test a "hello world" durable function. This function will orchestrate and chain together calls to other functions. You then publish the function code to Azure.
Important
The content of this article changes based on your choice of the Node.js programming model in the selector at the top of the page. The v4 model is generally available and is designed to have a more flexible and intuitive experience for JavaScript and TypeScript developers. Learn more about the differences between v3 and v4 in the migration guide.
Prerequisites
To complete this tutorial:
- Install Visual Studio Code.
- Install the Azure Functions VS Code extension
- Install the Azure Functions VS Code extension version
1.10.4
or above.
- Make sure you have the latest version of the Azure Functions Core Tools.
- Make sure you have Azure Functions Core Tools version
v4.0.5382
or above.
- Durable Functions require an Azure storage account. You need an Azure subscription.
- Make sure that you have version 16.x+ of Node.js installed.
- Make sure that you have version 18.x+ of Node.js installed.
- Make sure that you have TypeScript v4.x+ installed.
If you don't have an Azure subscription, create an Azure free account before you begin.
Create your local project
In this section, you use Visual Studio Code to create a local Azure Functions project.
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...
.Choose an empty folder location for your project and choose Select.
Following the prompts, provide the following information:
Prompt Value Description Select a language for your function app project TypeScript Create a local Node.js Functions project using TypeScript. Select a JavaScript programming model Model V3 Choose the V3 programming model. Select a version Azure Functions v4 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.
Following the prompts, provide the following information:
Prompt Value Description Select a language for your function app project TypeScript Create a local Node.js Functions project using TypeScript. Select a JavaScript programming model Model V4 Choose the V4 programming model. Select a version Azure Functions v4 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.
A package.json
file and a tsconfig.json
file are also created in the root folder.
Install the Durable Functions npm package
To work with Durable Functions in a Node.js function app, you use a library called durable-functions
.
To use the V4 programming model, you need to install the preview v3.x
version of durable-functions
.
- Use the View menu or Ctrl + Shift + ` to open a new terminal in VS Code.
- Install the
durable-functions
npm package by runningnpm install durable-functions
in the root directory of the function app.
- Install the
durable-functions
npm package preview version by runningnpm install durable-functions@preview
in the root directory of the function app.
Creating your functions
The most basic Durable Functions app contains three functions:
- Orchestrator function - describes a workflow that orchestrates other functions.
- Activity function - called by the orchestrator function, performs work, and optionally returns a value.
- Client function - a regular Azure Function that starts an orchestrator function. This example uses an HTTP triggered function.
Orchestrator function
You use a template to create the durable function code in your project.
In the command palette, search for and select
Azure Functions: Create Function...
.Following the prompts, provide the following information:
Prompt Value Description Select a template for your function Durable Functions orchestrator Create a Durable Functions orchestration Choose a durable storage type. Azure Storage (Default) Select the storage backend used for Durable Functions. Provide a function name HelloOrchestrator Name of your durable function
You've added an orchestrator to coordinate activity functions. Open HelloOrchestrator/index.ts to see the orchestrator function. Each call to context.df.callActivity
invokes an activity function named Hello
.
Next, you'll add the referenced Hello
activity function.
Activity function
In the command palette, search for and select
Azure Functions: Create Function...
.Following the prompts, provide the following information:
Prompt Value Description Select a template for your function Durable Functions activity Create an activity function Provide a function name Hello Name of your activity function
You've added the Hello
activity function that is invoked by the orchestrator. Open Hello/index.ts to see that it's taking a name as input and returning a greeting. An activity function is where you perform "the real work" in your workflow: work such as making a database call or performing some non-deterministic computation.
Finally, you'll add an HTTP triggered function that starts the orchestration.
Client function (HTTP starter)
In the command palette, search for and select
Azure Functions: Create Function...
.Following the prompts, provide the following information:
Prompt Value Description Select a template for your function Durable Functions HTTP starter Create an HTTP starter function Provide a function name DurableFunctionsHttpStart Name of your activity function Authorization level Anonymous For demo purposes, allow the function to be called without authentication
You've added an HTTP triggered function that starts an orchestration. Open DurableFunctionsHttpStart/index.ts to see that it uses client.startNew
to start a new orchestration. Then it uses client.createCheckStatusResponse
to return an HTTP response containing URLs that can be used to monitor and manage the new orchestration.
You now have a Durable Functions app that can be run locally and deployed to Azure.
One of the benefits of the V4 Programming Model is the flexibility of where you write your functions. In the V4 Model, you can use a single template to create all three functions in one file in your project.
In the command palette, search for and select
Azure Functions: Create Function...
.Following the prompts, provide the following information:
Prompt Value Description Select a template for your function Durable Functions orchestrator Create a file with a Durable Functions orchestration, an Activity function, and a Durable Client starter function. Choose a durable storage type Azure Storage (Default) Select the storage backend used for Durable Functions. Provide a function name hello Name used for your durable functions
Open src/functions/hello.ts to view the functions you created.
You've created an orchestrator called helloOrchestrator
to coordinate activity functions. Each call to context.df.callActivity
invokes an activity function called hello
.
You've also added the hello
activity function that is invoked by the orchestrator. In the same file, you can see that it's taking a name as input and returning a greeting. An activity function is where you perform "the real work" in your workflow: work such as making a database call or performing some non-deterministic computation.
Lastly, you've also added an HTTP triggered function that starts an orchestration. In the same file, you can see that it uses client.startNew
to start a new orchestration. Then it uses client.createCheckStatusResponse
to return an HTTP response containing URLs that can be used to monitor and manage the new orchestration.
You now have a Durable Functions app that can be run locally and deployed to Azure.
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.
- To test your function, set a breakpoint in the
Hello
activity function code (Hello/index.ts). Press F5 or selectDebug: Start Debugging
from the command palette to start the function app project. Output from Core Tools is displayed in the Terminal panel.
- To test your function, set a breakpoint in the
hello
activity function code (src/functions/hello.ts). Press F5 or selectDebug: Start Debugging
from the command palette 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.
Durable Functions requires an Azure Storage account to run. 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 In the Terminal panel, copy the URL endpoint of your HTTP-triggered function.
The response is the initial result from the HTTP function letting you 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.
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 queries 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": "HelloOrchestrator", "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" }
{ "name": "helloOrchestrator", "instanceId": "6ba3f77933b1461ea1a3828c013c9d56", "runtimeStatus": "Completed", "input": "", "customStatus": null, "output": [ "Hello, Tokyo", "Hello, Seattle", "Hello, Cairo" ], "createdTime": "2023-02-13T23:02:21Z", "lastUpdatedTime": "2023-02-13T23:02:25Z" }
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.
If you aren't already signed in, choose the Azure icon in the Activity bar. Then in the Resources area, choose Sign in to Azure....
If you're already signed in and can see your existing subscriptions, go to the next section. If you don't yet have an Azure account, choose Create an Azure Account.... Students can choose Create an Azure for Students Account....
When prompted in the browser, choose your Azure account and sign in using your Azure account credentials. If you create a new account, you can sign in after your account is created.
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 sidebar.
Create the function app in Azure
In this section, you create a function app and related resources in your Azure subscription.
Choose the Azure icon in the Activity bar. Then in the Resources area, select the + icon and choose the Create Function App in Azure option.
Provide the following information at the prompts:
Prompt Selection Select subscription Choose the subscription to use. You won't see this prompt when you have only one subscription visible under Resources. 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 runtime stack Choose the language version on which you've been running locally. Select a location for new resources For better performance, choose a region near you. The extension shows the status of individual resources as they're being created in Azure in the Azure: Activity Log panel.
When the creation is complete, the following Azure resources are created in your subscription. The resources are named 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 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 App Service plan, which defines the underlying host for your function app.
- An Application Insights instance connected to the function app, which tracks usage of your functions in the app.
A notification is displayed after your function app is created and the deployment package is applied.
Tip
By default, the Azure resources required by your function app are created based on the function app name you provide. By default, they're also created in the same new resource group with the function app. If you want to either customize the names of these resources or reuse existing resources, you need to publish the project with advanced create options instead.
Deploy the project to Azure
Important
Deploying to an existing function app always overwrites the contents of that app in Azure.
Choose the Azure icon in the Activity bar, then in the Workspace area, select your project folder and select the Deploy... button.
Select Deploy to Function App..., choose the function app you just created, and select Deploy.
After deployment completes, select View Output 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.
Test your function in Azure
Note
To use the V4 node programming model, make sure your app is running on at least version 4.25 of the Azure Functions runtime.
- Copy the URL of the HTTP trigger from the Output panel. The URL that calls your HTTP-triggered function should be in this format:
http://<functionappname>.azurewebsites.net/api/orchestrators/HelloOrchestrator
- Copy the URL of the HTTP trigger from the Output panel. The URL that calls your HTTP-triggered function should be in this format:
http://<functionappname>.azurewebsites.net/api/orchestrators/helloOrchestrator
- 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 JavaScript durable function app.
Feedback
Submit and view feedback for