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ção são criados na versão 4.x mais recente do runtime do Functions. Seus aplicativos de função só têm suporte quando são 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 suas funções na versão com suporte mais recente do runtime do Azure Functions. Você só deve fixar seu aplicativo em uma versão específica se receber instruções para fazê-lo devido a um problema com a versão mais recente. Sempre mude para a versão do runtime mais recente assim que suas funções puderem ser executadas corretamente.

Durante o desenvolvimento local, sua versão do Azure Functions Core Tools instalada precisa 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 do Azure

Para ver e atualizar a versão do runtime sendo usada atualmente por um aplicativo de funções, siga essas etapas:

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

2. Expanda Configuraçõese selecione Configuração.

3. Na guia Configurações do runtime do Functions, observe a Versão do runtime. Nesse exemplo, a versão está configurada como ~4.

   

CLI do Azure

Você pode ver a configuração FUNCTIONS_EXTENSION_VERSION do aplicativo na CLI do Azure.

Usando a CLI do Azure, veja a versão atual do runtime 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á a FUNCTIONS_EXTENSION_VERSION no seguinte resultado parcial:

[
  {
    "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 do Azure

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 uma versão específica

O Azure Functions permite que você use a configuração 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 à medida que se tornarem disponíveis. As atualizações de versão secundárias são feitas automaticamente porque novas versões secundárias provavelmente não irão introduzir alterações capazes de interromper suas funções.

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) emFUNCTIONS_EXTENSION_VERSION, o aplicativo de funções é fixado nessa versão específica do runtime até que você escolha voltar para as atualizações de versão automáticas explicitamente. 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 estiver fixado em uma versão secundária e esta for removida posteriormente, 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 do Azure

Para ver e atualizar a versão do runtime sendo usada atualmente por um aplicativo de funções, siga essas etapas:

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

2. Expanda Configuraçõese selecione Configuração.

3. Na guia Configurações do runtime do Functions, observe a Versão do runtime. Nesse exemplo, a versão está configurada como ~4.

   

3. Para fixar seu aplicativo em uma versão secundária específica, expanda Configurações e, a seguir, selecione Variáveis de ambiente no painel do lado esquerdo.

4. Na guia Configurações do aplicativo, selecione FUNCTIONS_EXTENSION_VERSION, altere Valor para a sua versão secundária obrigatória e, a seguir, selecione Aplicar.

5. Selecione Aplicar e, em seguida, selecione Confirmar para aplicar as alterações e reiniciar o aplicativo.

CLI do Azure

Você pode atualizar a configuração FUNCTIONS_EXTENSION_VERSION do aplicativo no 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 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 do Azure

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 mostra o valor 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, você não pode definir linuxFxVersion no portal nem usando o Azure PowerShell:

• Para ver a versão atual de runtime, use 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. Além disso, substitua <my_resource_group> pelo nome do grupo de recursos do 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. Além disso, substitua <RESOURCE_GROUP> pelo nome do grupo de recursos do 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

Notas de versão para versões do runtime