Trabalhar com o Azure Functions Core Tools

O Azure Functions Core Tools permite desenvolver e testar as funções no computador local por meio do prompt de comando ou do terminal. Suas funções locais podem se conectar a serviços do Azure em tempo real e você pode depurar as suas funções em seu computador local usando o runtime total do Functions. Você ainda pode implantar um aplicativo de funções para sua assinatura do Azure.

Observação

Não combine o desenvolvimento local com o desenvolvimento do portal no mesmo aplicativo de funções. Ao criar e publicar funções de um projeto local, você não conseguirá manter ou modificar o código do projeto no portal.

O desenvolvimento de funções em seu computador local e publicá-las no Azure usando o Core Tools segue estas etapas básicas:

Pré-requisitos

Os pré-requisitos específicos para o Core Tools contam com os recursos que você planeja usar:

Publicar: no momento, o Core Tools contam com a CLI do Azure ou o Azure PowerShell para autenticação com sua conta do Azure. Isso significa que você precisa instalar uma dessas ferramentas para poder publicar no Azure do Azure Functions Core Tools.

Instalar extensões: para instalar as extensões manualmente usando o Core Tools, você precisa ter o SDK do .NET Core 3.1 instalado. O SDK do .NET Core é usado pelo Core Tools para instalar extensões do NuGet. Você não precisa saber .NET para usar extensões do Azure Functions.

Versões de Core Tools

Há quatro versões do Azure Functions Core Tools. A versão que você usa depende do ambiente de desenvolvimento local, da escolha da linguagem e do nível de suporte necessário.

Escolha uma guia de versão abaixo para saber mais sobre cada versão específica e obter instruções detalhadas de instalação:

Compatível com a versão 4.x do runtime do Functions. Essa versão é compatível com Windows, macOS e Linux e usa o npm ou gerenciadores de pacotes específicos de uma plataforma para instalação. Essa é a versão recomendada do runtime do Functions e do Core Tools.

Você só pode instalar uma versão do Core Tools em um determinado computador. A menos que indicado o contrário, os exemplos neste artigo são para a versão 3.x.

Instalação das ferramentas básicas do Azure Functions

O Azure Functions Core Tools é uma versão local do Azure Functions runtime que pode ser executada no computador local de desenvolvimento. Ele também fornece comandos para criar funções, se conectar ao Azure e implantar projetos de função.

Começando com a versão 2.x, o Core Tools é executado no Windows, no macOS e no Linux.

As etapas a seguir usam um instalador do Windows (MSI) para instalar o Core Tools v4.x. Para obter mais informações sobre outros instaladores baseados em pacote, confira o arquivo leiame do Core Tools.

Baixe e execute o instalador do Core Tools, com base em sua versão do Windows:

Mudar as versões do Core Tools

Ao mudar para uma versão diferente do Core Tools, você deve usar o mesmo gerenciador de pacotes que a instalação original para mudar para uma versão de pacote diferente. Por exemplo, se você instalou a versão 2.x do Core Tools usando o npm, use o seguinte comando para atualizar para a versão 3.x:

npm install -g azure-functions-core-tools@3 --unsafe-perm true

Se você usou o Windows Installer (MSI) para instalar o Core Tools no Windows, desinstale a versão antiga em Adicionar e Remover Programas antes de instalar uma versão diferente.

Criar um projeto de funções local

Um diretório de projeto do Functions contém os seguintes arquivos e pastas, independentemente do idioma:

Nome do arquivo Descrição
host.json Para saber mais, confira a referência de host.json.
local.settings.json Configurações usadas pelo Core Tools ao executar localmente, incluindo as configurações do aplicativo. Para saber mais, confira configurações locais.
.gitignore Impede que o arquivo local.settings.json seja acidentalmente publicado em um repositório Git. Para saber mais, confira configurações locais
.vscode\extensions.json Arquivo de configurações usado ao abrir a pasta do projeto no Visual Studio Code.

Para saber mais sobre a pastas de projeto do Functions, confira o Guia de desenvolvedores do Azure Functions.

Na janela do terminal ou em um prompt de comando, execute o seguinte comando para criar o projeto e o repositório Git local:

func init MyFunctionProj

Este exemplo cria um projeto do Functions em uma nova pasta MyFunctionProj. Você será solicitado a escolher um idioma padrão para seu projeto.

As seguintes considerações se aplicam à inicialização do projeto:

  • Se você não fornecer a opção --worker-runtime no comando, será solicitado a escolher seu idioma. Para obter mais informações, confira a referência de func init.

  • Quando você não fornece um nome de projeto, a pasta atual é inicializada.

  • Se você planeja publicar seu projeto em um contêiner personalizado do Linux, use a opção --docker para garantir que um Dockerfile seja gerado para seu projeto. Para saber mais, confira Criar uma função no Linux usando uma imagem personalizada.

Determinados idiomas podem ter considerações adicionais:

  • O Core Tools permite que você crie projetos de aplicativo de funções para o runtime do .NET como projetos de biblioteca de classes C# em processo e de processo de trabalho isolado (.csproj). Esses projetos, que podem ser usados com o Visual Studio ou com Visual Studio Code, são compilados durante a depuração e ao publicar no Azure.

  • Use o parâmetro --csx se você quiser trabalhar localmente com arquivos de script C# (.csx). Esses são os mesmos arquivos que você obtém ao criar funções no portal do Azure e ao usar a versão 1.x do Core Tools. Para saber mais, confira a referência de func init.

Extensões de registro

Começando com o runtime versão 2.x, as Associações e os gatilhos do Functions são implementados como pacotes de extensão .NET (NuGet). Para projetos compilados em C#, você simplesmente referencia os pacotes de extensão do NuGet para os gatilhos e associações específicos que você está usando. As associações HTTP e os gatilhos de temporizador não exigem extensões.

Para melhorar a experiência de desenvolvimento para projetos não C#, o Functions permite que você referencie um pacote de extensão com versão em seu arquivo de projeto host.json. Os pacotes de extensão disponibilizam todas as extensões para seu aplicativo e eliminam a possibilidade de haver problemas de compatibilidade de pacotes entre as extensões. Os pacotes de extensão também eliminam a necessidade de instalar o SDK do .NET Core 3.1 e de lidar com o arquivo extensions.csproj.

Os pacotes de extensão é a abordagem recomendada para projetos do Functions incompatíveis com C#, bem como script C#. Para esses projetos, a configuração de pacote de extensão é gerada no arquivo host.json durante a inicialização. Se os pacotes não estiverem habilitados, você precisará atualizar o arquivo host.json do projeto.

A maneira mais fácil de instalar as extensões de associação é habilitar pacotes de extensão. Quando você habilita os pacotes, um conjunto predefinido de pacotes de extensão é instalado automaticamente.

Para habilitar pacotes de extensão, abra o arquivo host.json e atualize seu conteúdo de acordo com o código a seguir:

{
    "version": "2.0",
    "extensionBundle": {
        "id": "Microsoft.Azure.Functions.ExtensionBundle",
        "version": "[2.*, 3.0.0)"
    }
}

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

Pode haver casos em um projeto não .NET em que você não pode usar pacotes de extensão, como quando você precisa direcionar a uma versão específica de uma extensão que não está no grupo. Nesses casos raros, você pode usar o Core Tools para instalar localmente os pacotes de extensão específicos exigidos pelo seu projeto. Para saber mais, consulte Instalar extensões.

Configurações locais

Ao executar em um aplicativo de funções no Azure, as configurações exigidas por suas funções são armazenadas com segurança nas configurações do aplicativo. Durante o desenvolvimento local, essas configurações são adicionadas ao objeto Values no arquivo local.settings.json. O arquivo local.settings.json também armazena as configurações usadas pelas ferramentas de desenvolvimento locais.

Como o local.settings.json pode conter segredos, como cadeias de conexão, você nunca deve armazená-lo em um repositório remoto. Para saber mais sobre as configurações locais, consulte Arquivo de configurações locais.

Por padrão, essas configurações não são migradas automaticamente quando o projeto é publicado no Azure. Use a opção --publish-local-settings quando publicar para se certificar de que essas configurações serão adicionadas ao aplicativo de funções no Azure. Os valores na seção ConnectionStrings nunca são publicados.

Os valores de configuração do aplicativo de funções também podem ser lidos em seu código como variáveis de ambiente. Para obter mais informações, confira a seção de variáveis de Ambiente desses tópicos de referência específicos de linguagem:

Quando nenhuma cadeia de conexão de armazenamento válida estiver definida para AzureWebJobsStorage e um emulador de armazenamento local não estiver sendo usado, a seguinte mensagem de erro será exibida:

Valor ausente para AzureWebJobsStorage em local.settings.json. Isso é necessário para todos os gatilhos diferentes de HTTP. É possível executar o func azure functionapp fetch-app-settings <functionAppName>' ou especificar uma cadeia de conexão em local.settings.json.

Obter suas cadeias de conexão de armazenamento

Mesmo usando o Emulador de armazenamento do Azure para desenvolvimento, convém executar localmente com uma conexão de armazenamento real. Supondo que você já tenha criado uma conta de armazenamento, será possível obter uma cadeia de conexão de armazenamento válida de uma destas maneiras:

  1. No portal do Azure, pesquise e selecione as Contas de armazenamento.

    Selecionar contas de armazenamento no portal do Azure

  2. Selecione sua conta de armazenamento, Chaves de acesso em Configurações e copie um dos valores da Cadeia de conexão.

    Copiar cadeia de conexão do portal do Azure

Criar uma função

Para criar uma função em um projeto existente, execute o seguinte comando:

func new

Na versão 3.x/2.x, quando você executar func new, será solicitado a escolher um modelo no idioma padrão do seu aplicativo de funções. Em seguida, você será solicitado a escolher um nome para a função. Na versão 1.x, você também precisará escolher o idioma.

Você também pode especificar o nome da função e o modelo no comando func new. O seguinte exemplo usa a opção --template para criar um gatilho HTTP chamado MyHttpTrigger:

func new --template "Http Trigger" --name MyHttpTrigger

Esse exemplo cria um gatilho de Armazenamento de Filas chamado MyQueueTrigger:

func new --template "Azure Queue Storage Trigger" --name MyQueueTrigger

Para saber mais, confira o comando func new.

Executar funções localmente

Para executar um projeto do Functions, execute o host do Functions do diretório raiz do seu projeto. O host permite os gatilhos para todas as funções no projeto. O comando start varia conforme o idioma do projeto.

func start

Observação

A versão 1.x do runtime do Functions requer func host start. Para saber mais, confira referência do Azure Functions Core Tools.

Quando o host de funções é iniciado, ele gera as funções acionadas por URL de HTTP, como no seguinte exemplo:

Found the following functions:
Host.Functions.MyHttpTrigger

Job host started
Http Function MyHttpTrigger: http://localhost:7071/api/MyHttpTrigger

Importante

Quando você fizer a execução local, a autenticação não é imposta para pontos de extremidade HTTP. Isso significa que todas as solicitações HTTP locais são tratadas como authLevel = "anonymous". Para obter mais informações, confira o artigo de associação HTTP.

Transferência dos dados de teste para uma função

Para testar as funções localmente, inicie o host do Functions e chame os pontos de extremidade no servidor local usando solicitações HTTP. O ponto de extremidade que você chama depende do tipo de função.

Observação

Os exemplos neste tópico usam a ferramenta cURL para enviar solicitações HTTP do terminal ou de um prompt de comando. Você pode usar uma ferramenta de sua escolha para enviar solicitações HTTP para o servidor local. A ferramenta cURL está disponível por padrão em sistemas baseados em Linux e no Windows 10 build 17063 e posteriores. No Windows antigo, primeiro você precisa baixar e instalar a ferramenta cURL.

Para ter informações mais gerais sobre o teste de funções, confira Estratégias para testar seu código no Azure Functions.

Funções disparadas por HTTP e webhook

Chame o seguinte ponto de extremidade para executar localmente funções disparadas por HTTP e webhook:

http://localhost:{port}/api/{function_name}

Use o mesmo nome de servidor e porta no qual o host do Functions está escutando. Veja isso na saída gerada ao iniciar o host do Function. Chame essa URL usando qualquer método HTTP com suporte do disparador.

O seguinte comando cURL dispara a função de início rápido MyHttpTrigger de uma solicitação GET com o parâmetro name transmitido na cadeia de consulta.

curl --get http://localhost:7071/api/MyHttpTrigger?name=Azure%20Rocks

O exemplo a seguir é a mesma função chamada a partir de uma solicitação POST passando name no corpo da solicitação:

curl --request POST http://localhost:7071/api/MyHttpTrigger --data '{"name":"Azure Rocks"}'

Você pode fazer solicitações GET de um navegador passando dados na cadeia de consulta. Para todos os outros métodos HTTP, você deve usar cURL, Fiddler, Postman ou uma ferramenta de teste HTTP compatível com solicitações POST.

Funções disparadas por algo diferente de HTTP

Para todas as funções diferentes de gatilhos HTTP e Grade de Eventos, você pode testar suas funções localmente usando REST chamando um ponto de extremidade especial chamado de ponto de extremidade de administração. Chamar esse ponto de extremidade com uma solicitação HTTP POST no servidor local dispara a função.

Para testar as funções disparadas pela Grade de Eventos localmente, confira Teste local com o aplicativo Web do visualizador.

Como alternativa, é possível passar dados de teste para a execução no corpo da solicitação POST. Essa funcionalidade é semelhante á guia Teste no Portal do Azure.

Chame o seguinte ponto de extremidade de administrador para disparar funções que não são HTTP:

http://localhost:{port}/admin/functions/{function_name}

Para passar dados de teste para o ponto de extremidade administrador de uma função, é necessário fornecer os dados no corpo de uma mensagem de solicitação POST. O corpo da mensagem deve ter o seguinte formato JSON:

{
    "input": "<trigger_input>"
}

O valor <trigger_input> contém dados em um formato esperado pela função. O exemplo de cURL a seguir é um POST para uma função QueueTriggerJS. Nesse caso, a entrada é uma cadeia de caracteres equivalente à mensagem esperada na fila.

curl --request POST -H "Content-Type:application/json" --data '{"input":"sample queue data"}' http://localhost:7071/admin/functions/QueueTrigger

Ao chamar um ponto de extremidade de administrador em seu aplicativo de funções no Azure, você deve fornecer uma chave de acesso. Para saber mais, confira Chaves de acesso da função.

Publicar no Azure

O Azure Functions Core Tools dá suporte a dois tipos de implantação:

Tipo de implantação Comando Descrição
Arquivos de projeto func azure functionapp publish Implanta arquivos de projeto de função diretamente em seu aplicativo de funções usando a implantação zip.
Cluster do Kubernetes func kubernetes deploy Implanta seu aplicativo de funções do Linux como um contêiner do Docker personalizado em um cluster do Kubernetes.

Antes de publicar

Importante

Você precisa ter a CLI do Azure ou o Azure PowerShell instalado localmente para poder fazer uma publicação no Azure por meio do Core Tools.

Uma pasta de projeto pode conter arquivos e diretórios específicos a uma linguagem que não devem ser publicados. Os itens excluídos são listados em um arquivo .funcignore na pasta raiz do projeto.

Você já precisa ter criado um aplicativo de funções em sua assinatura do Azure, no qual você implantará seu código. Os projetos que exigem build devem ser compilados para que os binários possam ser implantados.

Para saber como criar um aplicativo de funções pelo prompt de comando ou pela janela do terminal usando a CLI do Azure ou o Azure PowerShell, confira Criar um aplicativo de funções para execução sem servidor.

Importante

Quando você cria um aplicativo de funções no portal do Azure, ele usa a versão 3.x do runtime do Core Tools por padrão. Para que o aplicativo de funções use a versão 1.x do runtime, siga as instruções em Executar na versão 1.x. Você não pode alterar a versão do runtime de um aplicativo de funções que tenha funções existentes.

Implantar arquivos de projeto

Para publicar seu código local para um aplicativo de funções no Azure, use o comando publish:

func azure functionapp publish <FunctionAppName>

As seguintes considerações se aplicam a esse tipo de implantação:

  • A publicação substitui os arquivos no aplicativo de funções.

  • Use a opção --publish-local-settings para criar automaticamente as configurações do aplicativo em seu aplicativo de funções com base nos valores no arquivo local.settings.json.

  • Um build remoto é executado em projetos compilados. Isso pode ser controlado usando a opção --no-build.

  • Seu projeto é implantado de modo que seja executado no pacote de implantação. Para desabilitar esse modo de implantação recomendado, use a opção --nozip.

  • O Java usa o Maven para publicar seu projeto local no Azure. Em vez disso, use o seguinte comando para publicar no Azure: mvn azure-functions:deploy. Os recursos do Azure são criados durante a implantação inicial.

  • Você receberá um erro se tentar fazer uma publicação em um <FunctionAppName> que não exista em sua assinatura.

Cluster do Kubernetes

O Functions também permite que você defina seu projeto do Functions para ser executado em um contêiner do Docker. Use a opção --docker de func init para gerar um Dockerfile para seu idioma específico. Esse arquivo é usado ao criar um contêiner a ser implantado. Para saber como publicar um contêiner personalizado no Azure sem o Kubernetes, confira Criar uma função no Linux usando um contêiner personalizado.

O Core Tools pode ser usado para implantar seu projeto como uma imagem de contêiner personalizada em um cluster do Kubernetes.

O comando a seguir usa o Dockerfile para gerar um contêiner e implantá-lo em um cluster do Kubernetes.

func kubernetes deploy --name <DEPLOYMENT_NAME> --registry <REGISTRY_USERNAME> 

Para saber mais, confira Implantação de um aplicativo de funções no Kubernetes.

Instalar extensões

Se você não puder usar os pacotes de extensão, poderá usar o Azure Functions Core Tools localmente para instalar os pacotes de extensão específicos exigidos pelo seu projeto.

Importante

Não é possível instalar explicitamente as extensões em um aplicativo de funções com pacotes de extensão habilitados. Primeiro, remova a seção extensionBundle em host.json antes de instalar explicitamente as extensões.

Os itens a seguir descrevem alguns motivos pelos quais você pode precisar instalar extensões manualmente:

  • Você precisa acessar uma versão específica de uma extensão não disponível em um pacote.
  • Você precisa acessar uma extensão personalizada não disponível em um pacote.
  • Você precisa acessar uma combinação específica de extensões não disponíveis em um único pacote.

Quando você instala extensões explicitamente, um arquivo de projeto .NET denominado extensions.csproj é adicionado à raiz do seu projeto. Este arquivo define o conjunto de pacotes NuGet exigidos por suas funções. Embora você possa trabalhar com as referências do pacote NuGet neste arquivo, o Core Tools permite que você instale extensões sem ter que editar manualmente esse arquivo de projeto C#.

Existem várias maneiras de usar as ferramentas principais para instalar as extensões necessárias em seu projeto local.

Instale todas as extensões

Use o seguinte comando para adicionar automaticamente todos os pacotes de extensão usados pelas ligações em seu projeto local:

func extensions install

O comando lê o arquivo function.json para ver quais pacotes você precisa, faz a instalação e reconstrói o projeto de extensões (extensions.csproj). Ele adiciona as novas associações na versão atual, mas não atualiza as associações existentes. Use a opção --force para atualizar as associações existentes para a versão mais recente nas novas instalações. Para saber mais, confira o func extensions install comando.

Se o seu aplicativo de funções usar associações ou pacotes NuGet que o Core Tools não reconhece, você deverá instalar manualmente a extensão específica.

Instale uma extensão específica

Use o seguinte comando para instalar um pacote de extensão específico em uma versão específica, neste caso a extensão de armazenamento:

func extensions install --package Microsoft.Azure.WebJobs.Extensions.Storage --version 5.0.0

Você pode usar esse comando para instalar qualquer pacote NuGet compatível. Para saber mais, confira o comando func extensions install.

Funções de monitoramento

A maneira recomendada de monitorar a execução das suas funções é a integração com o Azure Application Insights. Você também pode transmitir logs de execução para o computador local. Para saber mais, consulte Monitorar Azure Functions.

Integração do Application Insights

A integração do Application Insights deve ser habilitada quando você cria seu aplicativo de funções no Azure. Se, por algum motivo, seu aplicativo de funções não estiver conectado a uma instância do Application Insights, será fácil fazer essa integração no portal do Azure. Para saber mais, confira Habilitar a integração do Application Insights.

Habilitar logs de streaming

Você pode ver um fluxo de arquivos de log que estão sendo gerados por suas funções em uma sessão de linha de comando em seu computador local.

Streaming de log interno

Use o comando func azure functionapp logstream para começar a receber logs de streaming de um aplicativo de funções específico em execução no Azure, como no exemplo a seguir:

func azure functionapp logstream <FunctionAppName>

Observação

O streaming de log interno ainda não está habilitado no Core Tools para aplicativos de funções em execução no Linux em um plano de Consumo. Em vez disso, nos planos de hospedagem, você precisa usar o Live Metrics Stream para exibir os logs quase em tempo real.

Live Metrics Stream

Você pode exibir o Live Metrics Stream para o seu aplicativo de funções em uma nova janela do navegador, incluindo a opção --browser, como no seguinte exemplo:

func azure functionapp logstream <FunctionAppName> --browser

Esse tipo de logs de streaming requer que a integração do Application Insights seja habilitada para seu aplicativo de funções.

Próximas etapas

Saiba como desenvolver, testar e publicar funções do Azure usando as ferramentas principais do Azure Functions. As principais ferramentas do Azure Functions são Código-fonte aberto e hospedado no GitHub. Para arquivar uma solicitação de bug ou recurso, abra um problema do GitHub.