Codificar e testar o Azure Functions localmente

  • Artigo

Enquanto você é capaz de desenvolver e testar o Azure Functions no Portal do Azure, muitos desenvolvedores preferem uma experiência de desenvolvimento local. Quando você usa o Functions, fica mais fácil usar seu editor de código e ferramentas de desenvolvimento favoritos para criar e testar funções em seu computador local. Suas funções locais podem se conectar a serviços do Azure em tempo real e você pode depurá-las em seu computador local usando o runtime total do Functions.

Este artigo fornece links de ambientes de desenvolvimento específicos para sua linguagem preferencial. Ele também fornece algumas diretrizes compartilhadas para o desenvolvimento local, como trabalhar com o arquivo local.settings.json.

Ambientes de desenvolvimento locais

A maneira como você desenvolve funções em seu computador local depende de seu idioma e preferências de ferramentas. Os ambientes na tabela a seguir dão suporte a desenvolvimento local:

Ambiente Idiomas Descrição
Visual Studio Code C# (em processo)
C# (processo de trabalho isolado)
JavaScript
PowerShell
Python		 A extensão do Azure Functions para VS Code adiciona suporte ao Functions para o VS Code. Requer as Ferramentas Essenciais. Oferece suporte ao desenvolvimento em Linux, MacOS e Windows com a versão 2.x das Ferramentas Essenciais. Para saber mais, confira Criar sua primeira função usando o Visual Studio Code.
Prompt de comando ou terminal C# (em processo)
C# (processo de trabalho isolado)
JavaScript
PowerShell
Python		 O Azure Functions Core Tools fornece os principais tempos de execução e modelos para a criação de funções, o que permite o desenvolvimento local. A versão 2.x oferece suporte ao desenvolvimento em Linux, MacOS e Windows. Todos os ambientes contam com ferramentas essenciais para o runtime local do Functions.
Visual Studio C# (em processo)
C# (processo de trabalho isolado)		 As ferramentas do Azure Functions estão incluídas na carga de trabalho de desenvolvimento do Azure do Visual Studio, começando com o Visual Studio 2019. Permite que você compile funções em uma biblioteca de classes e publique o arquivo .dll no Azure. Inclui as Ferramentas Essenciais para teste local. Para saber mais, consulte Desenvolver Azure Functions usando o Visual Studio.
Maven (diversos) Java O arquétipo Maven oferece suporte às Ferramentas Essenciais para habilitar o desenvolvimento de funções Java. A versão 2.x oferece suporte ao desenvolvimento em Linux, MacOS e Windows. Para saber mais, consulte Criar sua primeira função com Java e Maven. Também dá suporte ao uso de desenvolvimento Eclipse e IntelliJ IDEA.

Observação

Devido às limitações na edição do código de função no portal do Azure, você deve desenvolver suas funções localmente e publicar o projeto de código em um aplicativo de funções no Azure. Para obter mais informações, confira Limitações de desenvolvimento no portal do Azure

Cada um desses ambientes de desenvolvimento local permite criar projetos de aplicativos de funções e usar modelos de funções predefinidos para criar novas funções. Cada um usa as Ferramentas Essenciais para que você possa testar e depurar suas funções com relação ao runtime do Functions em seu próprio computador, assim como faria com qualquer outro aplicativo. Você também pode publicar seu projeto de aplicativo de funções de qualquer um desses ambientes no Azure.

Arquivos do projeto local

Um diretório de projeto do Functions contém os seguintes arquivos na pasta raiz do projeto, 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, consulte o arquivo de configurações locais.
.gitignore Impede que o arquivo local.settings.json seja acidentalmente publicado em um repositório Git. Para saber mais, consulte o arquivo de configurações locais.
.vscode\extensions.json Arquivo de configurações usado ao abrir a pasta do projeto no Visual Studio Code.

Outros arquivos do projeto dependem do seu idioma e de funções específicas. Para obter mais informações, consulte o guia do desenvolvedor de seu idioma.

Arquivo de configurações local

O arquivo local.settings.json armazena as configurações do aplicativo e aquelas usadas pelas ferramentas de desenvolvimento locais. As configurações no arquivo local.settings.json são usadas somente ao executar projetos localmente. Ao publicar seu projeto no Azure, adicione também as configurações necessárias às configurações do aplicativo para o aplicativo de funções.

Importante

Como o local.settings.json pode conter segredos, como cadeias de conexão, você nunca deve armazená-lo em um repositório remoto. As ferramentas que dão suporte ao Functions fornecem maneiras de sincronizar as configurações do aplicativo de funções no qual seu projeto está implantado com aquelas no arquivo local.settings.json.

O arquivo de configurações local tem esta estrutura:

{
  "IsEncrypted": false,
  "Values": {
    "FUNCTIONS_WORKER_RUNTIME": "<language worker>",
    "AzureWebJobsStorage": "<connection-string>",
    "MyBindingConnection": "<binding-connection-string>",
    "AzureWebJobs.HttpExample.Disabled": "true"
  },
  "Host": {
    "LocalHttpPort": 7071,
    "CORS": "*",
    "CORSCredentials": false
  },
  "ConnectionStrings": {
    "SQLConnectionString": "<sqlclient-connection-string>"
  }
}

Essas configurações têm suporte quando você executa projetos localmente:

Configuração Descrição
IsEncrypted Quando essa configuração é definida como true, todos os valores são criptografados com uma chave do computador local. Usado com func settings comandos. O valor padrão é false. Talvez você queira criptografar o arquivo local.settings.json no computador local quando ele contiver segredos, como cadeias de conexão de serviço. O host descriptografa automaticamente as configurações quando ele é executado. Use o comando func settings decrypt antes de tentar ler as configurações criptografadas localmente.
Values Coleção de configurações de aplicativo usadas quando um projeto é executado localmente. Esses pares chave-valor (cadeia de caracteres– cadeia de caracteres) correspondem às configurações de aplicativos no aplicativo de funções no Azure, como AzureWebJobsStorage. Muitos gatilhos e associações têm uma propriedade que se refere a uma configuração de aplicativo de cadeia de conexão, como Connection para o Connection. Para essas propriedades, você precisa de uma configuração de aplicativo definida na matriz Values. Confira a tabela subsequente para obter uma lista de configurações comumente usadas.
Os valores devem ser cadeias de caracteres e não matrizes ou objetos JSON. Os nomes de configuração não podem incluir um sublinhado duplo (__) e não devem incluir dois pontos (:). Os caracteres de sublinhado duplo são reservados pelo runtime e os dois-pontos são reservados para dar suporte à injeção de dependência.
Host As configurações nesta seção personalizam o processo de host do Functions quando você executa projetos localmente. Essas configurações são separadas das configurações de host.json, que também se aplicam quando você executa projetos no Azure.
LocalHttpPort Define a porta padrão usada ao executar o host local do Functions (func host start e func run). A opção de linha de comando --port tem precedência sobre essa configuração. Por exemplo, ao executar no IDE do Visual Studio, você pode alterar o número da porta navegando até a janela "Propriedades do Projeto -> Depurar" e especificando explicitamente o número da porta em um comando host start --port <your-port-number> que pode ser fornecido no campo "Argumentos do Aplicativo".
CORS Define as origens permitidas para CORS (Compartilhamento de recurso entre origens). As origens são fornecidas como uma lista separada por vírgulas, sem espaços. Há suporte para o valor do caractere curinga (*), que permite solicitações de qualquer origem.
CORSCredentials Quando definido como true, withCredentials solicitações são permitidas.
ConnectionStrings Uma coleção. Não use essa coleção para as cadeias de conexão usadas por suas associações de função. Ela só é usada por estruturas que devem obter cadeias de conexão da seção ConnectionStrings de um arquivo de configuração, como o ConnectionStrings. As cadeias de caracteres de conexão neste objeto são adicionadas ao ambiente com o tipo de provedor de System.Data.SqlClient. Os itens nesta coleção não são publicados no Azure com outras configurações de aplicativo. É necessário adicionar explicitamente esses valores à coleção Connection strings das configurações do aplicativo de funções. Se estiver criando um SqlConnection no código de função, você deverá armazenar o valor da cadeia de conexão com as outras conexões nas SqlConnection no portal.

As seguintes configurações de aplicativo podem ser incluídas na matriz Values ao serem executadas localmente:

Configuração Valores Descrição
AzureWebJobsStorage Cadeia de conexão da conta de armazenamento, ou
UseDevelopmentStorage=true		 Contém a cadeia de conexão para uma conta de Armazenamento do Azure. Necessário quando são usados gatilhos diferentes de HTTP. Para obter mais informações, confira a referência do AzureWebJobsStorage.
Quando o Emulador do Azurite tiver sido instalado localmente e você configurar AzureWebJobsStorage em UseDevelopmentStorage=true, o Core Tools usará o emulador. Para mais informações, confira Emulador de armazenamento local.
AzureWebJobs.<FUNCTION_NAME>.Disabled true|false Para desabilitar uma função durante a execução local, adicione "AzureWebJobs.<FUNCTION_NAME>.Disabled": "true" à coleção, em que <FUNCTION_NAME> é o nome da função. Para saber mais, confira Como desabilitar funções no Azure Functions.
FUNCTIONS_WORKER_RUNTIME dotnet
dotnet-isolated
node
java
powershell
python		 Indica a linguagem de destino do runtime do Functions. Necessário para a versão 2.x e versões superiores do runtime do Functions. Essa configuração é gerada para seu projeto pelo Core Tools. Para saber mais, confira a referência do FUNCTIONS_WORKER_RUNTIME.
FUNCTIONS_WORKER_RUNTIME_VERSION ~7 Indica usar o PowerShell 7 ao executar localmente. Se não estiver definido, o PowerShell Core 6 será usado. Essa configuração é usada apenas durante a execução local. A versão do runtime do PowerShell é determinada pela configuração de site do powerShellVersion, quando executada no Azure, que pode ser definida no portal.

Sincronizar as configurações

Ao desenvolver suas funções localmente, quaisquer configurações locais exigidas pelo aplicativo também devem estar presentes nas configurações do aplicativo de funções no qual o código é implantado. Talvez você também precise baixar as configurações atuais do aplicativo de funções para o projeto local. Embora você possa definir manualmente as configurações do aplicativo no portal do Azure, as ferramentas a seguir também permitem sincronizar as configurações do aplicativo com as configurações locais em seu projeto:

Gatilhos e associações

Ao desenvolver suas funções localmente, você precisa levar em consideração os comportamentos de gatilho e associação. Para acionadores HTTP, você pode simplesmente chamar o endpoint HTTP no computador local, usando http://localhost/. Para funções não acionadas por HTTP, há várias opções para serem executadas localmente:

  • A maneira mais fácil de testar associações durante o desenvolvimento local é usar cadeias de conexão direcionadas aos serviços dinâmicos do Azure. Você pode ter como alvo serviços dinâmicos adicionando as configurações de cadeia de conexão apropriadas na matriz Values no arquivo local.settings.json. Quando você faz isso, as execuções locais durante o teste afetam os dados do serviço ativo. Por esse motivo, considere configurar serviços separados para uso durante o desenvolvimento e o teste e, em seguida, mude para serviços diferentes durante a produção.
  • Para gatilhos baseados em armazenamento, você pode usar um emulador de armazenamento local.
  • Você pode executar manualmente funções de acionamento não HTTP usando endpoints especiais de administrador. Para obter mais informações, consulte Executar manualmente uma função não acionada por HTTP.

Durante o teste local, você deve executar o host fornecido pelo Core Tools (func.exe) localmente. Para obter mais informações, consulte Azure Functions Core Tools.

Ferramentas de Teste de HTTP

Durante o desenvolvimento, é fácil chamar qualquer um dos pontos de extremidade de função de um navegador da Web quando eles dão suporte ao método HTTP GET. No entanto, para outros métodos HTTP que dão suporte a cargas, como POST ou PUT, você precisa usar uma ferramenta de teste de HTTP para criar e enviar essas solicitações HTTP para seus pontos de extremidade de função.

Cuidado

Para cenários em que suas solicitações devem incluir dados confidenciais, use uma ferramenta que proteja seus dados e reduza o risco de expor dados confidenciais ao público. Os dados confidenciais que você deve proteger podem incluir: credenciais, segredos, tokens de acesso, chaves de API, dados de geolocalização, até mesmo informações de identificação pessoal (PII).

Você pode manter seus dados seguros escolhendo uma ferramenta de teste de HTTP que funciona offline ou localmente, não sincroniza seus dados com a nuvem e não exige que você entre em uma conta online. Algumas ferramentas também podem proteger seus dados contra exposição acidental implementando recursos de segurança específicos.

Evite usar ferramentas que armazenam centralmente seu histórico de solicitação HTTP (incluindo informações confidenciais), que não seguem as práticas recomendadas de segurança ou não respeitam as preocupações de privacidade de dados.

Considere usar uma dessas ferramentas para enviar solicitações HTTP com segurança para seus pontos de extremidade de função:

Emulador de armazenamento local

Durante o desenvolvimento local, você pode usar o emulador Azurite local ao testar funções com associações do Armazenamento do Azure (Armazenamento de Filas, Armazenamento de Blobs e Armazenamento de Tabelas), sem precisar se conectar aos serviços de armazenamento remoto. O Azurite se integra ao Visual Studio Code e ao Visual Studio, e você também pode executá-lo no prompt de comando usando o npm. Para obter mais informações, consulte Usar o emulador Azurite para desenvolvimento local do armazenamento do Azure.

A seguinte configuração na coleção Values do arquivo local.settings.json informa ao host local do Functions para usar o Azurite para a conexão AzureWebJobsStorage padrão:

"AzureWebJobsStorage": "UseDevelopmentStorage=true"

Com esse valor de configuração, qualquer gatilho ou associação do Armazenamento do Azure que usa AzureWebJobsStorage como conexão se conecta ao Azurite ao ser executado localmente. Tenha essas considerações em mente ao usar a emulação de armazenamento durante a execução local:

  • Você precisa ter o Azurite instalado e em execução.
  • Você deve testá-lo com uma conexão de armazenamento real com os serviços do Azure antes de publicá-lo no Azure.
  • Ao publicar seu projeto, não publique a configuração AzureWebJobsStorage como UseDevelopmentStorage=true. No Azure, a configuração AzureWebJobsStorage precisa ser sempre a cadeia de conexão da conta de armazenamento usada pelo aplicativo de funções. Para obter mais informações, consulte AzureWebJobsStorage.

Próximas etapas