| title | description | ms.service | ms.topic | ms.date | ms.custom | recommendations |
|---|---|---|---|---|---|---|
Guide for running C# Azure Functions in an isolated process |
Learn how to use a .NET isolated process to run your C# functions in Azure, which supports .NET 5.0 and later versions. |
azure-functions |
conceptual |
07/06/2022 |
template-concept |
false |
This article is an introduction to using C# to develop .NET isolated process functions, which run out-of-process in Azure Functions. Running out-of-process lets you decouple your function code from the Azure Functions runtime. Isolated process C# functions run on .NET 6.0, .NET 7.0, and .NET Framework 4.8 (preview support). In-process C# class library functions aren't supported on .NET 7.0.
| Getting started | Concepts | Samples |
|---|---|---|
Previously Azure Functions has only supported a tightly integrated mode for .NET functions, which run as a class library in the same process as the host. This mode provides deep integration between the host process and the functions. For example, .NET class library functions can share binding APIs and types. However, this integration also requires a tighter coupling between the host process and the .NET function. For example, .NET functions running in-process are required to run on the same version of .NET as the Functions runtime. To enable you to run outside these constraints, you can now choose to run in an isolated process. This process isolation also lets you develop functions that use current .NET releases (such as .NET 7.0), not natively supported by the Functions runtime. Both isolated process and in-process C# class library functions run on .NET 6.0. To learn more, see Supported versions.
Because these functions run in a separate process, there are some feature and functionality differences between .NET isolated function apps and .NET class library function apps.
When your .NET functions run out-of-process, you can take advantage of the following benefits:
- Fewer conflicts: because the functions run in a separate process, assemblies used in your app won't conflict with different version of the same assemblies used by the host process.
- Full control of the process: you control the start-up of the app and can control the configurations used and the middleware started.
- Dependency injection: because you have full control of the process, you can use current .NET behaviors for dependency injection and incorporating middleware into your function app.
[!INCLUDE functions-dotnet-supported-versions]
A .NET isolated function project is basically a .NET console app project that targets a supported .NET runtime. The following are the basic files required in any .NET isolated project:
- host.json file.
- local.settings.json file.
- C# project file (.csproj) that defines the project and dependencies.
- Program.cs file that's the entry point for the app.
- Any code files defining your functions.
For complete examples, see the .NET 6 isolated sample project and the .NET Framework 4.8 isolated sample project.
Note
To be able to publish your isolated function project to either a Windows or a Linux function app in Azure, you must set a value of dotnet-isolated in the remote FUNCTIONS_WORKER_RUNTIME application setting. To support zip deployment and running from the deployment package on Linux, you also need to update the linuxFxVersion site config setting to DOTNET-ISOLATED|7.0. To learn more, see Manual version updates on Linux.
When your functions run out-of-process, your .NET project uses a unique set of packages, which implement both core functionality and binding extensions.
The following packages are required to run your .NET functions in an isolated process:
Because functions that run in a .NET isolated process use different binding types, they require a unique set of binding extension packages.
You'll find these extension packages under Microsoft.Azure.Functions.Worker.Extensions.
When using .NET isolated functions, you have access to the start-up of your function app, which is usually in Program.cs. You're responsible for creating and starting your own host instance. As such, you also have direct access to the configuration pipeline for your app. When you run your functions out-of-process, you can much more easily add configurations, inject dependencies, and run your own middleware.
The following code shows an example of a HostBuilder pipeline:
:::code language="csharp" source="~/azure-functions-dotnet-worker/samples/FunctionApp/Program.cs" id="docsnippet_startup":::
This code requires using Microsoft.Extensions.DependencyInjection;.
A HostBuilder is used to build and return a fully initialized IHost instance, which you run asynchronously to start your function app.
:::code language="csharp" source="~/azure-functions-dotnet-worker/samples/FunctionApp/Program.cs" id="docsnippet_host_run":::
Important
If your project targets .NET Framework 4.8, you also need to add FunctionsDebugger.Enable(); before creating the HostBuilder. It should be the first line of your Main() method. See Debugging when targeting .NET Framework for more information.
The ConfigureFunctionsWorkerDefaults method is used to add the settings required for the function app to run out-of-process, which includes the following functionality:
- Default set of converters.
- Set the default JsonSerializerOptions to ignore casing on property names.
- Integrate with Azure Functions logging.
- Output binding middleware and features.
- Function execution middleware.
- Default gRPC support.
:::code language="csharp" source="~/azure-functions-dotnet-worker/samples/FunctionApp/Program.cs" id="docsnippet_configure_defaults" :::
Having access to the host builder pipeline means that you can also set any app-specific configurations during initialization. You can call the ConfigureAppConfiguration method on HostBuilder one or more times to add the configurations required by your function app. To learn more about app configuration, see Configuration in ASP.NET Core.
These configurations apply to your function app running in a separate process. To make changes to the functions host or trigger and binding configuration, you'll still need to use the host.json file.
Dependency injection is simplified, compared to .NET class libraries. Rather than having to create a startup class to register services, you just have to call ConfigureServices on the host builder and use the extension methods on IServiceCollection to inject specific services.
The following example injects a singleton service dependency:
:::code language="csharp" source="~/azure-functions-dotnet-worker/samples/FunctionApp/Program.cs" id="docsnippet_dependency_injection" :::
This code requires using Microsoft.Extensions.DependencyInjection;. To learn more, see Dependency injection in ASP.NET Core.
.NET isolated also supports middleware registration, again by using a model similar to what exists in ASP.NET. This model gives you the ability to inject logic into the invocation pipeline, and before and after functions execute.
The ConfigureFunctionsWorkerDefaults extension method has an overload that lets you register your own middleware, as you can see in the following example.
:::code language="csharp" source="~/azure-functions-dotnet-worker/samples/CustomMiddleware/Program.cs" id="docsnippet_middleware_register" :::
The UseWhen extension method can be used to register a middleware which gets executed conditionally. A predicate which returns a boolean value needs to be passed to this method and the middleware will be participating in the invocation processing pipeline if the return value of the predicate is true.
The following extension methods on FunctionContext make it easier to work with middleware in the isolated model.
| Method | Description |
|---|---|
GetHttpRequestDataAsync |
Gets the HttpRequestData instance when called by an HTTP trigger. This method returns an instance of ValueTask<HttpRequestData?>, which is useful when you want to read message data, such as request headers and cookies. |
GetHttpResponseData |
Gets the HttpResponseData instance when called by an HTTP trigger. |
GetInvocationResult |
Gets an instance of InvocationResult, which represents the result of the current function execution. Use the Value property to get or set the value as needed. |
GetOutputBindings |
Gets the output binding entries for the current function execution. Each entry in the result of this method is of type OutputBindingData. You can use the Value property to get or set the value as needed. |
BindInputAsync |
Binds an input binding item for the requested BindingMetadata instance. For example, you can use this method when you have a function with a BlobInput input binding that needs to be accessed or updated by your middleware. |
The following is an example of a middleware implementation which reads the HttpRequestData instance and updates the HttpResponseData instance during function execution. This middleware checks for the presence of a specific request header(x-correlationId), and when present uses the header value to stamp a response header. Otherwise, it generates a new GUID value and uses that for stamping the response header.
:::code language="csharp" source="~/azure-functions-dotnet-worker/samples/CustomMiddleware/StampHttpHeaderMiddleware.cs" id="docsnippet_middleware_example_stampheader" :::
For a more complete example of using custom middleware in your function app, see the custom middleware reference sample.
.NET isolated passes a FunctionContext object to your function methods. This object lets you get an ILogger instance to write to the logs by calling the GetLogger method and supplying a categoryName string. To learn more, see Logging.
Bindings are defined by using attributes on methods, parameters, and return types. A function method is a method with a Function attribute and a trigger attribute applied to an input parameter, as shown in the following example:
:::code language="csharp" source="~/azure-functions-dotnet-worker/samples/Extensions/Queue/QueueFunction.cs" id="docsnippet_queue_trigger" :::
The trigger attribute specifies the trigger type and binds input data to a method parameter. The previous example function is triggered by a queue message, and the queue message is passed to the method in the myQueueItem parameter.
The Function attribute marks the method as a function entry point. The name must be unique within a project, start with a letter and only contain letters, numbers, _, and -, up to 127 characters in length. Project templates often create a method named Run, but the method name can be any valid C# method name.
Because .NET isolated projects run in a separate worker process, bindings can't take advantage of rich binding classes, such as ICollector<T>, IAsyncCollector<T>, and CloudBlockBlob. There's also no direct support for types inherited from underlying service SDKs, such as DocumentClient and BrokeredMessage. Instead, bindings rely on strings, arrays, and serializable types, such as plain old class objects (POCOs).
For HTTP triggers, you must use HttpRequestData and HttpResponseData to access the request and response data. This is because you don't have access to the original HTTP request and response objects when running out-of-process.
For a complete set of reference samples for using triggers and bindings when running out-of-process, see the binding extensions reference sample.
A function can have zero or more input bindings that can pass data to a function. Like triggers, input bindings are defined by applying a binding attribute to an input parameter. When the function executes, the runtime tries to get data specified in the binding. The data being requested is often dependent on information provided by the trigger using binding parameters.
To write to an output binding, you must apply an output binding attribute to the function method, which defined how to write to the bound service. The value returned by the method is written to the output binding. For example, the following example writes a string value to a message queue named myqueue-output by using an output binding:
:::code language="csharp" source="~/azure-functions-dotnet-worker/samples/Extensions/Queue/QueueFunction.cs" id="docsnippet_queue_output_binding" :::
The data written to an output binding is always the return value of the function. If you need to write to more than one output binding, you must create a custom return type. This return type must have the output binding attribute applied to one or more properties of the class. The following example from an HTTP trigger writes to both the HTTP response and a queue output binding:
:::code language="csharp" source="~/azure-functions-dotnet-worker/samples/Extensions/MultiOutput/MultiOutput.cs" id="docsnippet_multiple_outputs":::
The response from an HTTP trigger is always considered an output, so a return value attribute isn't required.
HTTP triggers translates the incoming HTTP request message into an HttpRequestData object that is passed to the function. This object provides data from the request, including Headers, Cookies, Identities, URL, and optional a message Body. This object is a representation of the HTTP request object and not the request itself.
Likewise, the function returns an HttpResponseData object, which provides data used to create the HTTP response, including message StatusCode, Headers, and optionally a message Body.
The following code is an HTTP trigger
:::code language="csharp" source="~/azure-functions-dotnet-worker/samples/Extensions/Http/HttpFunction.cs" id="docsnippet_http_trigger" :::
In .NET isolated, you can write to logs by using an ILogger instance obtained from a FunctionContext object passed to your function. Call the GetLogger method, passing a string value that is the name for the category in which the logs are written. The category is usually the name of the specific function from which the logs are written. To learn more about categories, see the monitoring article.
The following example shows how to get an ILogger and write logs inside a function:
:::code language="csharp" source="~/azure-functions-dotnet-worker/samples/Extensions/Http/HttpFunction.cs" id="docsnippet_logging" :::
Use various methods of ILogger to write various log levels, such as LogWarning or LogError. To learn more about log levels, see the monitoring article.
An ILogger is also provided when using dependency injection.
If your isolated project targets .NET Framework 4.8, the current preview scope requires manual steps to enable debugging. These steps are not required if using another target framework.
Your app should start with a call to FunctionsDebugger.Enable(); as its first operation. This occurs in the Main() method before initializing a HostBuilder. Your Program.cs file should look similar to the following:
using System;
using System.Diagnostics;
using Microsoft.Extensions.Hosting;
using Microsoft.Azure.Functions.Worker;
using NetFxWorker;
namespace MyDotnetFrameworkProject
{
internal class Program
{
static void Main(string[] args)
{
FunctionsDebugger.Enable();
var host = new HostBuilder()
.ConfigureFunctionsWorkerDefaults()
.Build();
host.Run();
}
}
}Next, you need to manually attach to the process using a .NET Framework debugger. Visual Studio doesn't do this automatically for isolated process .NET Framework apps yet, and the "Start Debugging" operation should be avoided.
In your project directory (or its build output directory), run:
func host start --dotnet-isolated-debug
This will start your worker, and the process will stop with the following message:
Azure Functions .NET Worker (PID: <process id>) initialized in debug mode. Waiting for debugger to attach...
Where <process id> is the ID for your worker process. You can now use Visual Studio to manually attach to the process. For instructions on this operation, see How to attach to a running process.
Once the debugger is attached, the process execution will resume and you will be able to debug.
This section describes the current state of the functional and behavioral differences running on out-of-process compared to .NET class library functions running in-process:
| Feature/behavior | In-process | Out-of-process |
|---|---|---|
| .NET versions | .NET Core 3.1 .NET 6.0 |
.NET 6.0 .NET 7.0 (Preview) .NET Framework 4.8 (Preview) |
| Core packages | Microsoft.NET.Sdk.Functions | Microsoft.Azure.Functions.Worker Microsoft.Azure.Functions.Worker.Sdk |
| Binding extension packages | Microsoft.Azure.WebJobs.Extensions.* | Under Microsoft.Azure.Functions.Worker.Extensions.* |
| Logging | ILogger passed to the function | ILogger obtained from FunctionContext |
| Cancellation tokens | Supported | Not supported |
| Output bindings | Out parameters | Return values |
| Output binding types | IAsyncCollector, DocumentClient, BrokeredMessage, and other client-specific types |
Simple types, JSON serializable types, and arrays. |
| Multiple output bindings | Supported | Supported |
| HTTP trigger | HttpRequest/ObjectResult | HttpRequestData/HttpResponseData |
| Durable Functions | Supported | Supported (public preview) |
| Imperative bindings | Supported | Not supported |
| function.json artifact | Generated | Not generated |
| Configuration | host.json | host.json and custom initialization |
| Dependency injection | Supported | Supported |
| Middleware | Not supported | Supported |
| Cold start times | Typical | Longer, because of just-in-time start-up. Run on Linux instead of Windows to reduce potential delays. |
| ReadyToRun | Supported | TBD |
| Application Insights dependencies | Supported | Not Supported |
Because your isolated process app runs outside the Functions runtime, you need to attach the remote debugger to a separate process. To learn more about debugging using Visual Studio, see Remote Debugging.