Como direcionar para versões do Azure Functions runtime

Um aplicativo de funções é executado em uma versão específica do runtime do Azure Functions. Por padrão, os aplicativos de funções são criados na versão 4.x mais recente do runtime do Functions. Seus aplicativos de funções só têm suporte ao serem executados em uma versão principal com suporte. Este artigo explica como configurar um aplicativo de funções no Azure para ser direcionado ou fixado a uma versão específica, quando necessário.

A maneira como você direciona a uma versão específica depende de você estar executando o Windows ou o Linux. Esta versão do artigo dá suporte ao Windows. Escolha seu sistema operacional na parte superior do artigo.

A maneira como você direciona a uma versão específica depende de você estar executando o Windows ou o Linux. Esta versão do artigo dá suporte ao Linux. Escolha seu sistema operacional na parte superior do artigo.

Importante

Sempre que possível, você deve executar seus aplicativos na versão mais recente do runtime do Azure Functions. Você só deve fixar seu aplicativo em uma versão específica quando receber instruções para fazê-lo devido a um problema na versão mais recente. Você sempre deve migrar para a versão do runtime mais recente assim que suas funções puderem ser executadas corretamente.

Durante o desenvolvimento local, sua versão instalada do Azure Functions Core Tools deve corresponder à versão principal do runtime usada pelo aplicativo de funções no Azure. Para obter mais informações, confira as versões do Core Tools.

Atualizar sua versão do runtime

Sempre que possível, você deve executar seus aplicativos na versão com suporte mais recente do runtime do Azure Functions. Se seu aplicativo de funções estiver executando uma versão mais antiga do runtime no momento, você deverá migrar seu aplicativo para a versão 4.x

Quando seu aplicativo tiver funções existentes, você deverá tomar precauções antes de mudar para uma versão principal de runtime posterior. Os artigos a seguir detalham as alterações interruptivas entre as versões principais, incluindo alterações interruptivas específicas da linguagem. Eles também fornecem instruções passo a passo para uma migração bem-sucedida do seu aplicativo de funções existente.

• Migrar do runtime versão 3.x para a versão 4.x
• Migrar do runtime versão 1.x para a versão 4.x

Para determinar sua versão atual do runtime, confira Ver a versão atual do runtime.

Exibir a versão de runtime atual

Você pode ver a versão do runtime atual do seu aplicativo de funções de uma das maneiras a seguir:

Portal

Use o procedimento a seguir para exibir e atualizar a versão de runtime usada no momento por um aplicativo de funções.

1. No portal do Azure, navegue até o aplicativo de funções.

2. Em Configurações, escolha Configuração. Na guia Configurações do runtime de funções, localize a Versão de runtime. Observe a versão de runtime específica. No exemplo a seguir, a versão é definida como ~4.

   

CLI do Azure

Você pode ver a FUNCTIONS_EXTENSION_VERSION a partir da CLI do Azure.

Usando a CLI do Azure, exiba a versão de runtime atual com o comando az functionapp config appsettings list.

az functionapp config appsettings list --name <function_app> \
--resource-group <my_resource_group>

Nesse código, substitua <function_app> pelo nome de seu aplicativo de funções. Substitua também <my_resource_group> pelo nome do grupo de recursos para seu aplicativo de funções.

Você verá FUNCTIONS_EXTENSION_VERSION na seguinte saída, que foi truncada para maior clareza:

[
  {
    "name": "FUNCTIONS_EXTENSION_VERSION",
    "slotSetting": false,
    "value": "~4"
  },
  {
    "name": "FUNCTIONS_WORKER_RUNTIME",
    "slotSetting": false,
    "value": "dotnet"
  },
  
  ...
]

Escolha Abrir o Cloud Shell no exemplo de código anterior para executar o comando no Azure Cloud Shell. Você também pode executar a CLI do Azure localmente para executar esse comando. Ao executar localmente, você deve primeiro executar az login para entrar.

PowerShell

Para verificar o runtime do Azure Functions, use o seguinte cmdlet:

Get-AzFunctionAppSetting -Name "<FUNCTION_APP>" -ResourceGroupName "<RESOURCE_GROUP>"

Substitua <FUNCTION_APP> pelo nome do aplicativo de funções e <RESOURCE_GROUP>. O valor atual da configuração FUNCTIONS_EXTENSION_VERSION é retornado na tabela de hash.

Como fixar em uma versão específica

O Azure Functions permite que você use a configuração da FUNCTIONS_EXTENSION_VERSION do aplicativo para direcioná-lo para a versão do runtime usada por um determinado aplicativo de funções. Se você especificar apenas a versão principal (~4), o aplicativo de funções será atualizado automaticamente para as novas versões secundárias do runtime sempre que se tornarem disponíveis. As atualizações de versão secundárias são feitas automaticamente porque as novas versões secundárias não devem introduzir alterações interruptivas.

Os aplicativos Linux usam a configuração de linuxFxVersion do site junto com a FUNCTIONS_EXTENSION_VERSION para determinar a imagem de base correta do Linux na qual executar suas funções. Quando você cria um novo aplicativo de funções no Linux, o runtime escolhe automaticamente a imagem de base correta para você com base na versão do runtime da sua pilha de linguagens.

A fixação em uma versão do runtime específica fará com que seu aplicativo de funções seja reiniciado.

Quando você especifica uma versão secundária específica (como 4.0.12345) no FUNCTIONS_EXTENSION_VERSION, o aplicativo de funções é fixado nessa versão específica do runtime até que você escolha explicitamente retornar para as atualizações automáticas. Você só deve fixar seu aplicativo de funções em uma versão secundária específica por um tempo suficiente para resolver quaisquer problemas com seu aplicativo que estejam impedindo você de direcioná-lo para a versão principal. Versões secundárias mais antigas são removidas regularmente do ambiente de produção. Quando você estiver fixado em uma versão secundária que for removida, seu aplicativo de funções passará a ser executado na versão existente mais próxima, em vez da versão definida em FUNCTIONS_EXTENSION_VERSION. As remoções de versão secundária são anunciadas nos comunicados do Serviço de Aplicativo.

Observação

Quando você tentar publicar a partir do Visual Studio em um aplicativo fixado em uma versão secundária específica do runtime, uma caixa de diálogo solicitará que você atualize para a versão mais recente ou cancele a publicação. Para evitar essa verificação quando você precisar usar uma versão secundária específica, adicione a propriedade <DisableFunctionExtensionVersionUpdate>true</DisableFunctionExtensionVersionUpdate> no seu arquivo .csproj.

Use um desses métodos para fixar seu aplicativo temporariamente em uma versão específica do runtime:

Portal

Use o procedimento a seguir para exibir e atualizar a versão de runtime usada no momento por um aplicativo de funções.

1. No portal do Azure, navegue até o aplicativo de funções.

2. Em Configurações, escolha Configuração. Na guia Configurações do runtime de funções, localize a Versão de runtime. Observe a versão de runtime específica. No exemplo a seguir, a versão é definida como ~4.

   

3. Para fixar seu aplicativo em uma versão secundária específica, selecione Configurações do aplicativo> FUNCTIONS_EXTENSION_VERSION, altere o Valor para a versão secundária necessária e selecione OK.

4. Selecione Salvar>Continuar para aplicar as alterações e reiniciar o aplicativo.

CLI do Azure

É possível atualizar a configuração FUNCTIONS_EXTENSION_VERSION o aplicativo de funções com o comando az functionapp config appsettings set.

az functionapp config appsettings set --name <FUNCTION_APP> \
--resource-group <RESOURCE_GROUP> \
--settings FUNCTIONS_EXTENSION_VERSION=<VERSION>

Substitua <FUNCTION_APP> pelo nome do seu aplicativo de funções e <RESOURCE_GROUP> pelo nome do grupo de recursos para o seu aplicativo de funções. Além disso, substitua <VERSION> pela versão secundária específica para a qual você precisa direcionar temporariamente.

Escolha Experimentar no exemplo de código anterior para executar o comando no Azure Cloud Shell. Você também pode executar a CLI do Azure localmente para executar esse comando. Ao executar localmente, você deve primeiro executar az login para entrar.

PowerShell

Use esse script para fixar o runtime do Azure Functions:

Update-AzFunctionAppSetting -Name "<FUNCTION_APP>" -ResourceGroupName "<RESOURCE_GROUP>" -AppSetting @{"FUNCTIONS_EXTENSION_VERSION" = "<VERSION>"} -Force

Substitua <FUNCTION_APP> pelo nome do seu aplicativo de funções e <RESOURCE_GROUP> pelo nome do grupo de recursos para o seu aplicativo de funções. Além disso, substitua <VERSION> pela versão secundária específica para a qual você precisa direcionar temporariamente. Você pode verificar o valor atualizado da configuração FUNCTIONS_EXTENSION_VERSION na tabela de hash retornada.

O aplicativo de funções é reiniciado depois que a alteração é feita na configuração do aplicativo.

Para fixar seu aplicativo de funções em uma versão do runtime do Linux específica, defina uma URL de imagem de base específica da versão na configuração de linuxFxVersion do site no formato DOCKER|<PINNED_VERSION_IMAGE_URI>.

Importante

Os aplicativos de função fixados no Linux não recebem as atualizações regulares de segurança e funcionalidade de host. Exceto se recomendado por um profissional de suporte, use a configuração FUNCTIONS_EXTENSION_VERSION e um valor linuxFxVersion padrão para a linguagem e a versão como, por exemplo, Python|3.9. Para valores válidos, consulte o artigo de referência linuxFxVersion.

Atualmente, não há suporte para fixação em um runtime específico para aplicativos de funções do Linux em execução em um plano de Consumo.

A tabela a seguir fornece um exemplo do valor da linuxFxVersion necessário para fixar um aplicativo de funções Node.js 16 em uma versão do runtime específica, 4.14.0.3:

DOCKER|mcr.microsoft.com/azure-functions/node:4.14.0.3-node16

Quando necessário, um profissional de suporte poderá fornecer a você um URI de imagem base válido para o seu aplicativo.

Use os seguintes comandos da CLI do Azure para exibir e definir o linuxFxVersion. Atualmente, não é possível definir linuxFxVersion no portal ou usando o Azure PowerShell.

• Para exibir a versão atual de runtime, use com o comando az functionapp config show.

  az functionapp config show --name <function_app> \
  --resource-group <my_resource_group> --query 'linuxFxVersion' -o tsv
  

  Nesse código, substitua <function_app> pelo nome de seu aplicativo de funções. Substitua também <my_resource_group> pelo nome do grupo de recursos para seu aplicativo de funções. O valor atual de linuxFxVersion é retornado.

• Para atualizar a configuração linuxFxVersion no aplicativo de funções, use o comando az functionapp config set.

  az functionapp config set --name <FUNCTION_APP> \
  --resource-group <RESOURCE_GROUP> \
  --linux-fx-version <LINUX_FX_VERSION>
  

  Substitua <FUNCTION_APP> pelo nome do aplicativo de funções. Substitua também <RESOURCE_GROUP> pelo nome do grupo de recursos para seu aplicativo de funções. Por fim, substitua <LINUX_FX_VERSION> pelo valor de uma imagem específica fornecida a você por um profissional de suporte.

Você pode executar esses comandos a partir do Azure Cloud Shell escolhendo Abrir o Cloud Shell nos exemplos de código anteriores. Você também pode usar a CLI do Azure localmente para executar esse comando após a execução de az login para entrar.

O aplicativo de funções é reiniciado depois que a alteração é feita na configuração do site.

Próximas etapas

Consulte as notas de versão para versões de runtime