Pacotes de extensão do Azure Functions

Este artigo explica como os pacotes de extensão permitem que seu código de função use todos os gatilhos e associações suportados pelo Azure Functions. Você também aprende sobre os níveis de suporte e as políticas para seus aplicativos quando usa pacotes de extensões.

Este artigo aplica-se apenas aos programadores do Azure Functions que utilizam linguagens non-.NET. Para saber como adicionar extensões de vinculação diretamente aos seus aplicativos de função C#, consulte Registrar extensões de vinculação do Azure Functions.

Overview

Os pacotes de extensões adicionam um conjunto predefinido de extensões de vinculação compatíveis ao seu aplicativo de função. Um pacote contém todas as extensões de vinculação atualmente suportadas pelo Functions. Os pacotes de extensão são versionados. Cada versão contém um conjunto específico de versões de extensão de vinculação que são verificadas para funcionar em conjunto.

Você deve sempre usar a versão mais recente do pacote em seu aplicativo, quando possível.

Quando você cria um projeto do Azure Functions a partir de um modelo de non-.NET, os pacotes de extensão já estão habilitados no arquivo do host.json aplicativo.

Definir uma referência de pacote de extensão

Você define uma referência de pacote de funcionalidades adicionais no arquivo de host.json projeto adicionando uma secção extensionBundle, como neste exemplo:

{
    "version": "2.0",
    "extensionBundle": {
        "id": "Microsoft.Azure.Functions.ExtensionBundle",
        "version": "[4.0.0, 5.0.0)"
    }
}

Neste exemplo, o version valor de instrui o host Functions a usar uma versão de [4.0.0, 5.0.0) pacote que seja pelo menos 4.0.0 , mas menor que 5.0.0, que inclui todas as versões potenciais do 4.x. Essa notação mantém efetivamente seu aplicativo na versão secundária mais recente disponível do pacote de extensão v4.x.

As propriedades seguintes estão disponíveis em extensionBundle:

Versões do pacote

Esta tabela lista todas as Microsoft.Azure.Functions.ExtensionBundle versões e o estado de suporte atual:

^* As versões de pacote preteridas podem incluir versões de extensão de vinculação preteridas. Para uma ótima capacidade de suporte e confiabilidade, você deve atualizar para a versão 4.x do pacote.

Por padrão, os pacotes de extensão são definidos por meio de intervalos de versões, o que garante que a versão secundária mais recente do pacote seja usada. Selecione um link de versão na tabela para revisar o extensions.json arquivo que define o pacote mais recente para essa versão principal.

Considerações para pacotes de extensão

Tenha estas considerações em mente ao trabalhar com pacotes de extensão:

• Quando possível, deve definir um version valor de intervalo da host.json tabela anterior, como [4.0.0, 5.0.0), em vez de definir um intervalo personalizado.
• Use o intervalo de versões mais recente para obter o melhor desempenho do aplicativo e acesso aos recursos mais recentes.
• No caso improvável de não poder usar um pacote de extensões, você deve, em vez disso, instalar explicitamente extensões.
• Ao atualizar as extensões usadas por uma aplicação implantada, o Functions descarrega novas versões das extensões a partir do endpoint cdn.functions.azure.com. Para que as atualizações de extensão sejam bem-sucedidas, o cdn.functions.azure.com ponto de extremidade deve estar acessível ao seu aplicativo de função.

Atualizar pacotes de extensão

É importante manter a versão do pacote atualizada para que os seus aplicativos possam continuar elegíveis para novos recursos, patches de segurança e otimizações de desempenho.

Para atualizar seu aplicativo para o pacote mais recente, edite o arquivo de host.json na raiz do seu projeto de aplicativo. Defina o valor de como extensionBundle.version, que deve ter esta aparência no arquivo host.json[4.0.0,5.0.0):

{
    "version": "2.0",
    "extensionBundle": {
        "id": "Microsoft.Azure.Functions.ExtensionBundle",
        "version": "[4.0.0, 5.0.0)"
    }
}

Tenha estas considerações em mente ao atualizar a versão do pacote de extensão usada pelo seu aplicativo:

• O conteúdo do pacote 4.x mais recente pode sempre ser encontrado nesta página de lançamento no repositório.
• Analise a documentação de referência para quaisquer extensões utilizadas pela sua aplicação, procurando por alterações críticas entre as versões. Para obter a lista de versões de extensão incluídas no pacote padrão, consulte o extension.json arquivo de projeto vinculado a partir desta tabela. Você pode revisar a página de lançamentos de pacotes no repositório de pacotes para ver as tags de versão específicas do pacote.
• Sempre verifique seu aplicativo localmente depois de atualizar a versão do pacote para garantir a compatibilidade com as extensões atualizadas. Você pode usar o comando func start no Azure Functions Core Tools ou F5 no Visual Studio ou Visual Studio Code para executar seu aplicativo de função localmente.
• A maneira como você aciona extensões a serem atualizadas com base nas alterações na versão do pacote no arquivo de host.json depende do ambiente do seu aplicativo:
  • Projeto local: as extensões são atualizadas localmente quando as Ferramentas do Core são iniciadas, seja a partir do func start comando ou ao depurar nas suas ferramentas de desenvolvimento.
  • Aplicativo de função: as extensões são atualizadas quando você implanta o arquivo de host.json atualizado em seu aplicativo de função no Azure.

Política de suporte de pacotes de extensão

As versões principais de um pacote de extensão podem ocorrer quando há atualizações de alteração de quebra em uma das extensões de vinculação contidas. Essas alterações de quebra de extensão exigem que as atualizações do pacote permaneçam compatíveis com os SDKs do Azure subjacentes. Atualizar o pacote garante que seus aplicativos continuem a receber novos recursos, melhorias de desempenho e suporte completo ao produto.

O ciclo de suporte dos pacotes de extensão segue estas fases distintas:

Você pode exibir as versões do pacote de extensão e suas extensões incluídas no repositório de pacotes de extensão do Azure Functions. Você também pode exibir a página de versões do SDK do Azure para obter um inventário de todas as extensões do Functions. Você pode encontrar pacotes .NET individuais no NuGet.org.

Trabalhar com pacotes de extensões de pré-visualização

Tenha estas considerações em mente ao optar por usar um pacote de extensão não-GA:

• Os pacotes de visualização podem incluir recursos que ainda estão em desenvolvimento e ainda não estão prontos para uso em produção. Destinam-se a avaliação e testes em ambientes que não sejam de produção.
• Alterações disruptivas ocorrem sem aviso prévio entre versões de visualização. Podem incluir alterações a:
  • Definições de gatilho e vinculação.
  • Extensões incluídas na pré-visualização.
  • Características de desempenho e estabilidade.
• As atualizações de segurança podem exigir que você atualize versões.
• Você deve testar completamente os pacotes de visualização em ambientes que não sejam de produção e evitar o uso de pacotes de visualização na produção. Quando tiver de utilizar um pacote de pré-visualização em produção, tome estas precauções adicionais:
  • Fixe seu pacote em uma versão específica e bem testada do pacote, em vez de em um intervalo. A fixação impede a atualização automática da versão do pacote antes que você tenha a chance de verificar a atualização em um ambiente que não seja de produção.
  • Mova seu aplicativo para usar uma versão de pacote GA assim que a funcionalidade estiver disponível em uma versão de pacote totalmente suportada.
• Para se manter informado sobre as atualizações do pacote, incluindo a mudança da visualização para o GA, você deve:
  • Monitore as versões prévias dos pacotes na página de lançamentos para pacotes de extensão.
  • Monitore a documentação de referência específica da extensão.
  • Analise as versões do pacote NuGet de extensões de visualização específicas que você está usando.
  • Acompanhe atualizações ou alterações significativas nos registros de alterações publicados em NuGet.org para cada extensão de pré-visualização.

Conteúdo relacionado

• Para saber mais sobre extensões de vinculação, consulte Registrar extensões de vinculação do Azure Functions.