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, você cria aplicativos de funções 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 direcionar, ou fixar, uma versão específica do runtime do Functions, quando necessário.

Considerações

Tenha essas considerações em mente ao direcionar uma versão de runtime específica:

O plano de consumo flex só é executado na versão 4.x do runtime. Como o plano de Consumo Flex não dá suporte à configuração do aplicativo FUNCTIONS_EXTENSION_VERSION, seu aplicativo não pode especificar uma versão de runtime específica ao ser executado neste plano.
A maneira como você direciona a uma versão específica depende de você estar executando o Windows ou o Linux.
Este artigo é específico para Windows ou Linux. Escolha seu sistema operacional na parte superior do artigo.
Quando possível, sempre execute seu aplicativo na versão de runtime com suporte mais recente. Fixe seu aplicativo em uma versão específica somente se você for instruído a fazer isso 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

Quando possível, sempre execute seus aplicativos de funções na versão mais recente com suporte do runtime do Azure Functions. Se o aplicativo de funções estiver em execução em uma versão mais antiga do runtime, migre 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.

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:

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

No portal do Azure, navegue até o aplicativo de funções.
Expanda Configurações e selecione Configuração.
Na guia Configurações do runtime do Function, observe a Versão do runtime. Nesse exemplo, a versão está configurada como ~4.

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. Além disso, substitua <my_resource_group> pelo nome do grupo de recursos do 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"
  },
  
  ...
]

Selecione Abrir 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.

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 novas versões secundárias do runtime à medida que elas estiverem disponíveis. As atualizações de versão secundárias são automáticas porque novas versões secundárias provavelmente não apresentarão alterações que interrompem suas funções.

Os aplicativos do 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.

Fixar a uma versão de runtime específica reinicia seu aplicativo de funções.

Quando você especifica uma versão secundária específica (como 4.0.12345) em FUNCTIONS_EXTENSION_VERSION, você fixa o aplicativo de funções nessa versão específica do runtime até optar explicitamente por retornar às atualizações automáticas de versão. Fixe apenas em uma versão secundária específica pelo tempo necessário para resolver problemas com seu aplicativo de função que impedem que você aponte para a versão principal. Versões secundárias mais antigas são removidas regularmente do ambiente de produção. Quando seu aplicativo de funções é fixado a uma versão secundária que é removida posteriormente, seu aplicativo de funções é executado na versão mais próxima existente em vez da versão definida em FUNCTIONS_EXTENSION_VERSION. Comunicados do Serviço de Aplicativo anunciam remoções de versões menores.

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:

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

No portal do Azure, navegue até o aplicativo de funções.
Expanda Configurações e selecione Configuração.
Na guia Configurações do runtime do Function, observe a Versão do runtime. Nesse exemplo, a versão está configurada como ~4.

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.
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.
Selecione Aplicar e, em seguida, selecione Confirmar para aplicar as alterações e reiniciar o aplicativo.

Atualize a configuração de aplicativo FUNCTIONS_EXTENSION_VERSION no aplicativo de funções usando 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.

Use esse script para fixar o runtime do Azure Functions:

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

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 de runtime específica no Linux, defina uma URL de imagem base específica da versão na configuração do site linuxFxVersion 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.12. 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.

O exemplo a seguir mostra o valor linuxFxVersion necessário para fixar um aplicativo de funções do Node.js 22 à versão específica de runtime 4.14.0.3:

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

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.

Atualize a imagem gerenciada do Linux

Esta seção se aplica apenas a aplicativos existentes em Python 3.11 e Java 8, 11 ou 17 em planos Linux Elastic Premium ou Dedicado (App Service) que utilizam uma imagem gerenciada pelo Debian Bullseye. Se sua aplicação não atender a todas essas condições, você não precisa seguir esse procedimento.

A imagem gerenciada mais recente oferece um caminho temporário para que um aplicativo afetado permaneça em sua versão atual enquanto migra para uma distribuição Linux suportada. Esse procedimento não se aplica ao Flex Consumption ou a aplicativos personalizados de container. Para um aplicativo no plano Linux Consumption, migre para o plano Flex Consumption.

Esta atualização seleciona a distribuição Linux para a versão de idioma existente por meio de um valor de três partes linuxFxVersion. Ele não fixa o host das Funções a uma imagem específica DOCKER|<IMAGE_URI> .

Escolha um valor Bookworm ou Noble `linuxFxVersion`

Primeiro, determine se você pode atualizar a versão do idioma ou se precisa manter a versão atual e selecione uma distribuição Linux mais recente.

Considere atualizar o app para uma versão mais recente suportada no idioma. Após uma atualização de idioma, o aplicativo usa a imagem gerenciada padrão atual para essa versão do idioma.

Se o app precisar permanecer na versão atual do idioma, escolha o valor de imagem mais recente correspondente:

Versão do idioma	Valor de Debian Bullseye	Distribuição mais recente	Valor de imagem mais novo
Python 3.11	`Python\\|3.11\\|2.0`	Debian Bookworm	`Python\\|3.11\\|3.0`
Java 8	`Java\\|8\\|2.0`	Ubuntu Noble	`Java\\|8\\|4.0`
Java 11	`Java\\|11\\|2.0`	Ubuntu Noble	`Java\\|11\\|4.0`
Java 17	`Java\\|17\\|2.0`	Ubuntu Noble	`Java\\|17\\|4.0`

Esses valores em três partes selecionam explicitamente a imagem gerenciada do Linux para essas imagens da era Bullseye. Eles não são devolvidos pelo az functionapp list-runtimes comando.

Teste a imagem Linux gerenciada mais nova

Teste seu app e suas dependências na imagem mais nova antes de atualizar o app de produção.

Crie um aplicativo de teste separado ou crie um slot de implantação.
Implante o mesmo código e configuração que seu app de produção usa no app de teste ou no slot.
Defina o valor da imagem mais recente seguindo os passos em Atualizar o valor da imagem. Ao usar um slot, inclua --slot <SLOT_NAME> em cada comando da CLI do Azure.
Invoque cada função e verifique se o app inicia com sucesso, os gatilhos rodam como esperado e as dependências nativas ou do sistema operacional carregam corretamente.

Atualize o valor da imagem

Mudar o valor da imagem reinicia o aplicativo de funções. Atualize a produção durante uma janela de manutenção ou use um slot de implantação.

Veja o valor atual linuxFxVersion :
```
az functionapp config show --name <APP_NAME> \
  --resource-group <RESOURCE_GROUP> \
  --query linuxFxVersion --output tsv
```
Esse comando retorna o valor armazenado na configuração do site. O valor retornado pode conter apenas a linguagem e a versão do idioma, como Python|3.11, em vez do valor tripartito que identifica a distribuição Linux. Se o valor não incluir a versão da imagem, siga os passos em Verificar a distribuição Linux para confirmar que o aplicativo atualmente usa o Debian Bullseye.
Defina linuxFxVersion para o valor de imagem mais recente:
```
az functionapp config set --name <APP_NAME> \
  --resource-group <RESOURCE_GROUP> \
  --linux-fx-version "<LANGUAGE|VERSION|IMAGE_VERSION>"
```
Para Python 3.11 no Debian Bookworm, use Python|3.11|3.0. Para Java no Ubuntu Noble, use Java|8|4.0, Java|11|4.0, ou Java|17|4.0.
Espere o app reiniciar.

Verifique a distribuição Linux

Verifique tanto o valor configurado quanto a distribuição Linux que roda seu app.

Confirme o valor atualizado linuxFxVersion :
```
az functionapp config show --name <APP_NAME> \
  --resource-group <RESOURCE_GROUP> \
  --query linuxFxVersion --output tsv
```
Como você define explicitamente um valor de três partes, esse comando retorna exatamente o valor Bookworm ou Noble que você selecionou.
Abra o site Kudu do aplicativo em https://<APP_NAME>.scm.azurewebsites.net.
Selecione Ambiente e reviseKUDU_ENV, ou abra uma sessão SSH e execute:
```
cat /etc/os-release
```
Confirme que o resultado identifica o Debian Bookworm para Python 3.11 ou o Ubuntu Noble para Java 8, 11 ou 17.
Invoque cada função e confirme que gatilhos e dependências continuam funcionando como esperado.

Reverta a atualização da imagem gerenciada do Linux

Se a imagem atualizada causar um problema de compatibilidade, restaure temporariamente o valor anterior linuxFxVersion enquanto resolve o problema.

Warning

O Debian Bullseye não é mais suportado após sua data de fim de vida útil e não recebe atualizações de segurança. Use rollback apenas como mitigação temporária e retorne para uma imagem suportada o mais rápido possível.

Na tabela em Escolha um valor de Bookworm ou Noble linuxFxVersion, encontre o valor Debian Bullseye para sua versão do idioma.

Defina linuxFxVersion para esse valor do Bullseye:

az functionapp config set --name <APP_NAME> \
  --resource-group <RESOURCE_GROUP> \
  --linux-fx-version "<BULLSEYE_LINUX_FX_VERSION>"

Espere o app reiniciar e então repita as verificações em Verificar a distribuição Linux.

Próximas etapas

Notas de versão para versões do runtime

Comentários

Esta página foi útil?

Last updated on 2026-09-17