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 compatíveis com o Azure Functions. Você também aprenderá sobre os níveis de suporte e as políticas para seus aplicativos ao usar pacotes de extensão.

Este artigo se aplica somente aos desenvolvedores do Azure Functions que usam idiomas non-.NET. Para saber como adicionar extensões de associação diretamente aos aplicativos de funções C#, consulte Registrar extensões de associação do Azure Functions.

Overview

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

Você sempre deve 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 extensão no arquivo de projeto host.json adicionando uma extensionBundle seção, como neste exemplo:

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

Neste exemplo, o valor version de [4.0.0, 5.0.0) instrui o host do Functions a usar uma versão de pacote 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 a seguir estão disponíveis em extensionBundle:

Versões do pacote

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

^* As versões de pacote preteridas podem incluir versões de extensão de associação preteridas. Para obter a capacidade de suporte e a confiabilidade ideais, você deve atualizar para o pacote versão 4.x.

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

Considerações sobre pacotes de extensão

Tenha estas considerações em mente quando você trabalha com pacotes de extensão:

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

Atualizar pacotes de extensão

É importante manter a versão do pacote atualizada para que 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 host.json na raiz do projeto do aplicativo. Defina o valor de extensionBundle.version como [4.0.0,5.0.0), que deve ser semelhante a este em seu arquivo de host.json:

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

Tenha essas 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 sempre pode ser encontrado nesta página de versão no repositório.
• Examine a documentação de referência de todas as extensões usadas pelo aplicativo para procurar alterações significativas entre as versões. Para obter a lista de versões de extensão incluídas no pacote padrão, consulte o arquivo de projeto extension.json vinculado a partir desta tabela. Você pode examinar a página de versões do pacote no repositório de pacotes para marcas de versão de pacote específicas.
• 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 nas Ferramentas do Azure Functions Core ou F5 no Visual Studio ou no Visual Studio Code para executar seu aplicativo de funções localmente.
• A maneira como você dispara extensões a serem atualizadas com base nas alterações na versão do pacote no arquivo host.json depende do ambiente do aplicativo:
  • Projeto local: as extensões são atualizadas localmente quando as Ferramentas de Linha de Comando são iniciadas, seja pelo comando func start ou durante a depuração nas ferramentas de desenvolvimento.
  • Aplicativo de funções: as extensões são atualizadas quando você implanta o arquivo de host.json atualizado em seu aplicativo de funções 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 significativas em uma das extensões de associação contidas. Essas alterações de quebra de extensão exigem atualizações no pacote para permanecerem compatíveis com os SDKs subjacentes do Azure. A atualização do pacote garante que seus aplicativos continuem recebendo 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 as 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 um inventário de todas as extensões do Functions. Você pode encontrar pacotes .NET individuais em NuGet.org.

Trabalhar com pacotes de extensão de visualização

Tenha estas considerações em mente quando você 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 não estão prontos para uso em produção. Elas são destinadas a avaliação e teste em ambientes de não produção.
• Alterações significativas ocorrem entre versões prévias sem aviso prévio. Eles podem incluir alterações em:
  • Definições de gatilho e vinculação.
  • Extensões incluídas na visualização.
  • Características de desempenho e estabilidade.
• Atualizações de segurança podem exigir que você atualize as versões.
• Você deve testar completamente os pacotes de visualização em ambientes não produtivos e evitar o uso de pacotes de visualização em produção. Quando for necessário usar um pacote de visualização em produção, tome estas precauções extras:
  • Fixe seu pacote em uma versão específica e bem testada, 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 não produtivo.
  • 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 com suporte.
• Para se manter informado sobre as atualizações do pacote, incluindo a movimentação de visualização para GA, você deve:
  • Monitorar versões de pacotes de visualização na página de versões de pacotes de extensões.
  • Monitorar a documentação de referência específica da extensão.
  • Examine 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 logs de alterações publicados no NuGet.org para cada extensão de pré-visualização.

Conteúdo relacionado

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