Skip to content

Latest commit

 

History

History
581 lines (384 loc) · 27.7 KB

migrate-version-1-version-4.md

File metadata and controls

581 lines (384 loc) · 27.7 KB
Raw
title description ms.service ms.topic ms.date ms.custom zone_pivot_groups
Migrate apps from Azure Functions version 1.x to 4.x
This article shows you how to migrate your existing function apps running on version 1.x of the Azure Functions runtime to be able to run on version 4.x of the runtime.
azure-functions
how-to
07/31/2023
template-how-to-pattern, devx-track-extended-java, devx-track-js, devx-track-python, devx-track-dotnet, devx-track-azurecli, ignite-2023, linux-related-content, devx-track-ts
programming-languages-set-functions

Migrate apps from Azure Functions version 1.x to version 4.x

::: zone pivot="programming-language-java"

Important

Java isn't supported by version 1.x of the Azure Functions runtime. Perhaps you're instead looking to migrate your Java app from version 3.x to version 4.x. If you're migrating a version 1.x function app, select either C# or JavaScript above.

::: zone-end

::: zone pivot="programming-language-typescript"

Important

TypeScript isn't supported by version 1.x of the Azure Functions runtime. Perhaps you're instead looking to migrate your TypeScript app from version 3.x to version 4.x. If you're migrating a version 1.x function app, select either C# or JavaScript above.

::: zone-end

::: zone pivot="programming-language-powershell"

Important

PowerShell isn't supported by version 1.x of the Azure Functions runtime. Perhaps you're instead looking to migrate your PowerShell app from version 3.x to version 4.x. If you're migrating a version 1.x function app, select either C# or JavaScript above.

::: zone-end

::: zone pivot="programming-language-python"

Important

Python isn't supported by version 1.x of the Azure Functions runtime. Perhaps you're instead looking to migrate your Python app from version 3.x to version 4.x. If you're migrating a version 1.x function app, select either C# or JavaScript above.

::: zone-end

::: zone pivot="programming-language-javascript,programming-language-csharp"

Important

Support will end for version 1.x of the Azure Functions runtime on September 14, 2026. We highly recommend that you migrate your apps to version 4.x by following the instructions in this article.

This article walks you through the process of safely migrating your function app to run on version 4.x of the Functions runtime. Because project migration instructions are language dependent, make sure to choose your development language from the selector at the top of the article.

If you are running version 1.x of the runtime in Azure Stack Hub, see Considerations for Azure Stack Hub first.

Identify function apps to migrate

Use the following PowerShell script to generate a list of function apps in your subscription that currently target version 1.x:

$Subscription = '<YOUR SUBSCRIPTION ID>' 
 
Set-AzContext -Subscription $Subscription | Out-Null

$FunctionApps = Get-AzFunctionApp

$AppInfo = @{}

foreach ($App in $FunctionApps)
{
     if ($App.ApplicationSettings["FUNCTIONS_EXTENSION_VERSION"] -like '*1*')
     {
          $AppInfo.Add($App.Name, $App.ApplicationSettings["FUNCTIONS_EXTENSION_VERSION"])
     }
}

$AppInfo

::: zone-end

::: zone pivot="programming-language-csharp"

Choose your target .NET version

On version 1.x of the Functions runtime, your C# function app targets .NET Framework.

[!INCLUDE functions-dotnet-migrate-v4-versions]

Tip

Unless your app depends on a library or API only available to .NET Framework, we recommend updating to .NET 8 on the isolated worker model. Many apps on version 1.x target .NET Framework only because that is what was available when they were created. Additional capabilities are available to more recent versions of .NET, and if your app is not forced to stay on .NET Framework due to a dependency, you should target a more recent version. .NET 8 is the fully released version with the longest support window from .NET.

Although you can choose to instead use the in-process model, this is not recommended if it can be avoided. Support will end for the in-process model on November 10, 2026, so you'll need to move to the isolated worker model before then. Doing so while migrating to version 4.x will decrease the total effort required, and the isolated worker model will give your app additional benefits, including the ability to more easily target future versions of .NET. If you are moving to the isolated worker model, the .NET Upgrade Assistant can also handle many of the necessary code changes for you.

This guide doesn't present specific examples for .NET 6. If you need to target that version, you can adapt the .NET 8 examples.

::: zone-end

::: zone pivot="programming-language-javascript,programming-language-csharp"

Prepare for migration

If you haven't already, identify the list of apps that need to be migrated in your current Azure Subscription by using the Azure PowerShell.

Before you migrate an app to version 4.x of the Functions runtime, you should do the following tasks:

  1. Review the list of behavior changes after version 1.x. Migrating from version 1.x to version 4.x also can affect bindings.
  2. Complete the steps in Migrate your local project to migrate your local project to version 4.x.
  3. After migrating your project, fully test the app locally using version 4.x of the Azure Functions Core Tools.
  4. Update your function app in Azure to the new version. If you need to minimize downtime, consider using a staging slot to test and verify your migrated app in Azure on the new runtime version. You can then deploy your app with the updated version settings to the production slot. For more information, see Update using slots.
  5. Publish your migrated project to the updated function app.

::: zone-end

::: zone pivot="programming-language-csharp"

When you use Visual Studio to publish a version 4.x project to an existing function app at a lower version, you're prompted to let Visual Studio update the function app to version 4.x during deployment. This update uses the same process defined in Update without slots.

::: zone-end

::: zone pivot="programming-language-javascript,programming-language-csharp"

Migrate your local project

::: zone-end

::: zone pivot="programming-language-csharp"

The following sections describes the updates you must make to your C# project files to be able to run on one of the supported versions of .NET in Functions version 4.x. The updates shown are ones common to most projects. Your project code could require updates not mentioned in this article, especially when using custom NuGet packages.

Migrating a C# function app from version 1.x to version 4.x of the Functions runtime requires you to make changes to your project code. Many of these changes are a result of changes in the C# language and .NET APIs.

Choose the tab that matches your target version of .NET and the desired process model (in-process or isolated worker process).

Tip

If you are moving to an LTS or STS version of .NET using the isolated worker model, the .NET Upgrade Assistant can be used to automatically make many of the changes mentioned in the following sections.

Project file

The following example is a .csproj project file that runs on version 1.x:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net48</TargetFramework>
    <AzureFunctionsVersion>v1</AzureFunctionsVersion>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.NET.Sdk.Functions" Version="1.0.24" />
  </ItemGroup>
  <ItemGroup>
    <Reference Include="Microsoft.CSharp" />
  </ItemGroup>
  <ItemGroup>
    <None Update="host.json">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    </None>
    <None Update="local.settings.json">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
      <CopyToPublishDirectory>Never</CopyToPublishDirectory>
    </None>
  </ItemGroup>
</Project>

Use one of the following procedures to update this XML file to run in Functions version 4.x:

.NET 8

[!INCLUDE functions-dotnet-migrate-project-v4-isolated-net8]

.NET Framework 4.8

[!INCLUDE functions-dotnet-migrate-project-v4-isolated-net-framework]

.NET 8 (in-process model)

[!INCLUDE functions-dotnet-migrate-project-v4-inproc]

Package and namespace changes

Based on the model you are migrating to, you might need to update or change the packages your application references. When you adopt the target packages, you then need to update the namespace of using statements and some types you reference. You can see the effect of these namespace changes on using statements in the HTTP trigger template examples later in this article.

.NET 8

[!INCLUDE functions-dotnet-migrate-packages-v4-isolated]

.NET Framework 4.8

[!INCLUDE functions-dotnet-migrate-packages-v4-isolated]

.NET 8 (in-process model)

[!INCLUDE functions-dotnet-migrate-packages-v4-in-process]

The Notification Hubs and Mobile Apps bindings are supported only in version 1.x of the runtime. When upgrading to version 4.x of the runtime, you need to remove these bindings in favor of working with these services directly using their SDKs.

Program.cs file

In most cases, migrating requires you to add the following program.cs file to your project:

.NET 8

using Microsoft.Azure.Functions.Worker;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var host = new HostBuilder()
    .ConfigureFunctionsWebApplication()
    .ConfigureServices(services => {
        services.AddApplicationInsightsTelemetryWorkerService();
        services.ConfigureFunctionsApplicationInsights();
    })
    .Build();

host.Run();

This example includes ASP.NET Core integration to improve performance and provide a familiar programming model when your app uses HTTP triggers. If you do not intend to use HTTP triggers, you can replace the call to ConfigureFunctionsWebApplication with a call to ConfigureFunctionsWorkerDefaults. If you do so, you can remove the reference to Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore from your project file. However, for the best performance, even for functions with other trigger types, you should keep the FrameworkReference to ASP.NET Core.

[!INCLUDE functions-dotnet-migrate-isolated-program-cs]

.NET Framework 4.8

using Microsoft.Extensions.Hosting;
using Microsoft.Azure.Functions.Worker;

namespace Company.FunctionApp
{
    internal class Program
    {
        static void Main(string[] args)
        {
            FunctionsDebugger.Enable();

            var host = new HostBuilder()
                .ConfigureFunctionsWorkerDefaults()
                .ConfigureServices(services => {
                    services.AddApplicationInsightsTelemetryWorkerService();
                    services.ConfigureFunctionsApplicationInsights();
                })
                .Build();
            host.Run();
        }
    }
}

[!INCLUDE functions-dotnet-migrate-isolated-program-cs]

.NET 8 (in-process model)

A program.cs file isn't required when running in-process.

host.json file

Settings in the host.json file apply at the function app level, both locally and in Azure. In version 1.x, your host.json file is either empty or it contains some settings that apply to all functions in the function app. For more information, see Host.json v1. If your host.json file has setting values, review the host.json v2 format for any changes.

To run on version 4.x, you must add "version": "2.0" to the host.json file. You should also consider adding logging to your configuration, as in the following examples:

.NET 8

:::code language="json" source="~/functions-quickstart-templates//Functions.Templates/ProjectTemplate_v4.x/CSharp-Isolated/host.json":::

The host.json file only controls logging from the Functions host runtime, and in the isolated worker model, some of these logs come from your application directly, giving you more control. See Managing log levels in the isolated worker model for details on how to filter these logs.

.NET Framework 4.8

:::code language="json" source="~/functions-quickstart-templates/Functions.Templates/ProjectTemplate_v4.x/CSharp-Isolated/host.json":::

The host.json file only controls logging from the Functions host runtime, and in the isolated worker model, some of these logs come from your application directly, giving you more control. See Managing log levels in the isolated worker model for details on how to filter these logs.

.NET 8 (in-process model)

:::code language="json" source="~/functions-quickstart-templates/Functions.Templates/ProjectTemplate_v4.x/CSharp/host.json":::

local.settings.json file

The local.settings.json file is only used when running locally. For information, see Local settings file. In version 1.x, the local.settings.json file has only two required values:

:::code language="json" source="~/functions-quickstart-templates-v1/Functions.Templates/ProjectTemplate/local.settings.json":::

When you migrate to version 4.x, make sure that your local.settings.json file has at least the following elements:

.NET 8

:::code language="json" source="~/functions-quickstart-templates/Functions.Templates/ProjectTemplate_v4.x/CSharp-Isolated/local.settings.json":::

Note

When migrating from running in-process to running in an isolated worker process, you need to change the FUNCTIONS_WORKER_RUNTIME value to "dotnet-isolated".

.NET Framework 4.8

:::code language="json" source="~/functions-quickstart-templates/Functions.Templates/ProjectTemplate_v4.x/CSharp-Isolated/local.settings.json":::

Note

When migrating from running in-process to running in an isolated worker process, you need to change the FUNCTIONS_WORKER_RUNTIME value to "dotnet-isolated".

.NET 8 (in-process model)

{
    "IsEncrypted": false,
    "Values": {
        "AzureWebJobsStorage": "AzureWebJobsStorageConnectionStringValue",
        "FUNCTIONS_WORKER_RUNTIME": "dotnet",
        "FUNCTIONS_INPROC_NET8_ENABLED": "1"
    }
}

Note

When choosing to target .NET 8 using the in-process model, you need to set the FUNCTIONS_WORKER_RUNTIME value to "dotnet" and set the FUNCTIONS_INPROC_NET8_ENABLED value to "1".

Class name changes

Some key classes changed names between version 1.x and version 4.x. These changes are a result either of changes in .NET APIs or in differences between in-process and isolated worker process. The following table indicates key .NET classes used by Functions that could change when migrating:

.NET 8

Version 1.x .NET 8
FunctionName (attribute) Function (attribute)
TraceWriter ILogger<T>, ILogger
HttpRequestMessage HttpRequestData, HttpRequest (using ASP.NET Core integration)
HttpResponseMessage HttpResponseData, IActionResult (using ASP.NET Core integration)

.NET Framework 4.8

Version 1.x .NET Framework 4.8
FunctionName (attribute) Function (attribute)
TraceWriter ILogger<T>, ILogger
HttpRequestMessage HttpRequestData
HttpResponseMessage HttpResponseData

.NET 8 (in-process model)

Version 1.x .NET 6 (in-process)
FunctionName (attribute) FunctionName (attribute)
TraceWriter ILogger<T>, ILogger
HttpRequestMessage HttpRequest
HttpResponseMessage IActionResult

There might also be class name differences in bindings. For more information, see the reference articles for the specific bindings.

Other code changes

.NET 8 (isolated)

This section highlights other code changes to consider as you work through the migration. These changes are not needed by all applications, but you should evaluate if any are relevant to your scenarios. Make sure to check Behavior changes after version 1.x for additional changes you might need to make to your project.

[!INCLUDE functions-dotnet-migrate-isolated-other-code-changes]

.NET 8 (in-process model)

Make sure to check Behavior changes after version 1.x for additional changes you might need to make to your project.

.NET Framework 4.8

This section highlights other code changes to consider as you work through the migration. These changes are not needed by all applications, but you should evaluate if any are relevant to your scenarios. Make sure to check Behavior changes after version 1.x for additional changes you might need to make to your project.

[!INCLUDE functions-dotnet-migrate-isolated-other-code-changes]

HTTP trigger template

Most of the code changes between version 1.x and version 4.x can be seen in HTTP triggered functions. The HTTP trigger template for version 1.x looks like the following example:

using System.Linq;
using System.Net;
using System.Net.Http;
using System.Threading.Tasks;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Azure.WebJobs.Host;

namespace Company.Function
{
    public static class HttpTriggerCSharp
    {
        [FunctionName("HttpTriggerCSharp")]
        public static async Task<HttpResponseMessage> 
            Run([HttpTrigger(AuthorizationLevel.AuthLevelValue, "get", "post", 
            Route = null)]HttpRequestMessage req, TraceWriter log)
        {
            log.Info("C# HTTP trigger function processed a request.");

            // parse query parameter
            string name = req.GetQueryNameValuePairs()
                .FirstOrDefault(q => string.Compare(q.Key, "name", true) == 0)
                .Value;
            
            if (name == null)
            {
                // Get request body
                dynamic data = await req.Content.ReadAsAsync<object>();
                name = data?.name;
            }
            
            return name == null
                ? req.CreateResponse(HttpStatusCode.BadRequest, 
                    "Please pass a name on the query string or in the request body")
                : req.CreateResponse(HttpStatusCode.OK, "Hello " + name);
        }
    }
}

In version 4.x, the HTTP trigger template looks like the following example:

.NET 8

using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.Functions.Worker;
using Microsoft.Extensions.Logging;

namespace Company.Function
{
    public class HttpTriggerCSharp
    {
        private readonly ILogger<HttpTriggerCSharp> _logger;

        public HttpTriggerCSharp(ILogger<HttpTriggerCSharp> logger)
        {
            _logger = logger;
        }

        [Function("HttpTriggerCSharp")]
        public IActionResult Run(
            [HttpTrigger(AuthorizationLevel.Function, "get")] HttpRequest req)
        {
            _logger.LogInformation("C# HTTP trigger function processed a request.");

            return new OkObjectResult($"Welcome to Azure Functions, {req.Query["name"]}!");
        }
    }
}

.NET Framework 4.8

using Microsoft.Azure.Functions.Worker;
using Microsoft.Azure.Functions.Worker.Http;
using Microsoft.Extensions.Logging;
using System.Net;

namespace Company.Function
{
    public class HttpTriggerCSharp
    {
        private readonly ILogger<HttpTriggerCSharp> _logger;

        public HttpTriggerCSharp(ILogger<HttpTriggerCSharp> logger)
        {
            _logger = logger;
        }

        [Function("HttpTriggerCSharp")]
        public HttpResponseData Run([HttpTrigger(AuthorizationLevel.Function, "get")] HttpRequestData req)
        {
            _logger.LogInformation("C# HTTP trigger function processed a request.");

            var response = req.CreateResponse(HttpStatusCode.OK);
            response.Headers.Add("Content-Type", "text/plain; charset=utf-8");

            response.WriteString($"Welcome to Azure Functions, {req.Query["name"]}!");

            return response;
        }
    }
}

.NET 8 (in-process model)

:::code language="csharp" source="~/functions-quickstart-templates/Functions.Templates/Templates/HttpTrigger-CSharp/HttpTriggerCSharp.cs":::

::: zone-end

::: zone pivot="programming-language-javascript"

To update your project to Azure Functions 4.x:

  1. Update your local installation of Azure Functions Core Tools to version 4.x.

  2. Move to one of the Node.js versions supported on version 4.x.

  3. Add both version and extensionBundle elements to the host.json, so that it looks like the following example:

    [!INCLUDE functions-extension-bundles-json-v3]

    The extensionBundle element is required because after version 1.x, bindings are maintained as external packages. For more information, see Extension bundles.

  4. Update your local.settings.json file so that it has at least the following elements:

    {
    "IsEncrypted": false,
    "Values": {
        "AzureWebJobsStorage": "UseDevelopmentStorage=true",
        "FUNCTIONS_WORKER_RUNTIME": "node"
    }
}

    The AzureWebJobsStorage setting can be either the Azurite storage emulator or an actual Azure storage account. For more information, see Local storage emulator. ::: zone-end

::: zone pivot="programming-language-javascript,programming-language-csharp"

[!INCLUDE functions-migrate-v4]

::: zone-end

Behavior changes after version 1.x

This section details changes made after version 1.x in both trigger and binding behaviors as well as in core Functions features and behaviors.

Changes in triggers and bindings

Starting with version 2.x, you must install the extensions for specific triggers and bindings used by the functions in your app. The only exception for this HTTP and timer triggers, which don't require an extension. For more information, see Register and install binding extensions.

There are also a few changes in the function.json or attributes of the function between versions. For example, the Event Hubs path property is now eventHubName. See the existing binding table for links to documentation for each binding.

Changes in features and functionality

A few features were removed, updated, or replaced after version 1.x. This section details the changes you see in later versions after having used version 1.x.

In version 2.x, the following changes were made:

  • Keys for calling HTTP endpoints are always stored encrypted in Azure Blob storage. In version 1.x, keys were stored in Azure Files by default. When you migrate an app from version 1.x to version 2.x, existing secrets that are in Azure Files are reset.

  • The version 2.x runtime doesn't include built-in support for webhook providers. This change was made to improve performance. You can still use HTTP triggers as endpoints for webhooks.

  • To improve monitoring, the WebJobs dashboard in the portal, which used the AzureWebJobsDashboard setting is replaced with Azure Application Insights, which uses the APPINSIGHTS_INSTRUMENTATIONKEY setting. For more information, see Monitor Azure Functions.

  • All functions in a function app must share the same language. When you create a function app, you must choose a runtime stack for the app. The runtime stack is specified by the FUNCTIONS_WORKER_RUNTIME value in application settings. This requirement was added to improve footprint and startup time. When developing locally, you must also include this setting in the local.settings.json file.

  • The default timeout for functions in an App Service plan is changed to 30 minutes. You can manually change the timeout back to unlimited by using the functionTimeout setting in host.json.

  • HTTP concurrency throttles are implemented by default for Consumption plan functions, with a default of 100 concurrent requests per instance. You can change this behavior in the maxConcurrentRequests setting in the host.json file.

  • Because of .NET Core limitations, support for F# script (.fsx files) functions has been removed. Compiled F# functions (.fs) are still supported.

  • The URL format of Event Grid trigger webhooks has been changed to follow this pattern: https://{app}/runtime/webhooks/{triggerName}.

  • The names of some pre-defined custom metrics were changed after version 1.x. Duration was replaced with MaxDurationMs, MinDurationMs, and AvgDurationMs. Success Rate was also renamed to Success Rate.

Considerations for Azure Stack Hub

App Service on Azure Stack Hub does not support version 4.x of Azure Functions. When you are planning a migration off of version 1.x in Azure Stack Hub, you can choose one of the following options:

  • Migrate to version 4.x hosted in public cloud Azure Functions using the instructions in this article. Instead of upgrading your existing app, you would create a new app using version 4.x and then deploy your modified project to it.
  • Switch to WebJobs hosted on an App Service plan in Azure Stack Hub.

Next steps

[!div class="nextstepaction"] Learn more about Functions versions