Desenvolver o Azure Functions usando o Visual Studio

O Visual Studio permite que você desenvolva, teste e implante funções da biblioteca de classes C# no Azure. Se esta for sua primeira experiência com o Azure Functions, confira Uma introdução ao Azure Functions.

O Visual Studio oferece os seguintes benefícios quando você desenvolve suas funções:

  • Editar, criar e executar funções em seu computador de desenvolvimento local.
  • Publique seu projeto do Azure Functions diretamente no Azure e crie recursos do Azure conforme necessário.
  • Use atributos C# para declarar associações de função diretamente no código C#.
  • Desenvolver e implantar funções de pré-compiladas C#. Funções pré-compiladas fornecem um desempenho de inicialização a frio melhor que funções baseadas em script C#.
  • Codificar suas funções em C# tendo todos os benefícios de desenvolvimento do Visual Studio.

Este artigo fornece detalhes sobre como usar o Visual Studio para desenvolver funções de biblioteca de classes C# e publicá-las no Azure. Antes de ler este artigo, considere concluir o guia início rápido das funções para o Visual Studio.

Salvo indicação em contrário, os procedimentos e exemplos mostrados são para o Visual Studio 2019.

Pré-requisitos

  • Ferramentas do Azure Functions. Para adicionar as Ferramentas do Azure Functions, inclua a carga de trabalho de desenvolvimento do Azure na instalação do Visual Studio. As Ferramentas do Azure Functions estão disponíveis na carga de trabalho de desenvolvimento do Azure, começando com o Visual Studio 2017.

  • Outros recursos necessários, como uma conta de armazenamento do Azure, são criados em sua assinatura durante o processo de publicação.

  • Se você não tiver uma assinatura do Azure, crie uma conta gratuita antes de começar.

Observação

No Visual Studio 2017, a carga de trabalho de desenvolvimento do Azure instala as Ferramentas do Azure Functions como uma extensão separada. Ao atualizar a instalação do Visual Studio 2017, verifique se você está usando a versão mais recente das ferramentas do Azure Functions. As seções a seguir mostram como verificar e (se necessário) atualizar sua extensão das Ferramentas do Azure Functions no Visual Studio 2017.

Ignore essas seções se você estiver usando o Visual Studio 2019.

Verifique a versão das ferramentas no Visual Studio 2017

  1. No menu Ferramentas, clique em Extensões e Atualizações. Expanda Instalado > Ferramentas e escolha Azure Functions e Ferramentas de Trabalhos da Web.

    Verifique a versão das ferramentas do Functions

  2. Observe a Versão instalada e compare-a com a versão mais recente listada nas notas sobre a versão.

  3. Se a sua versão for mais antiga, atualize suas ferramentas no Visual Studio conforme mostrado na seção a seguir.

Atualizar suas ferramentas no Visual Studio 2017

  1. Na caixa de diálogo Extensões e Atualizações, expanda Atualizações > Visual Studio Marketplace, escolha Azure Functions e Ferramentas de Trabalhos da Web e selecione Atualizar.

    Atualize a versão das ferramentas do Functions

  2. Depois de fazer o download da atualização das ferramentas, selecione Fechar e feche o Visual Studio para disparar a atualização das ferramentas usando o instalador VSIX.

  3. No instalador VSIX, escolha Modificar para atualizar as ferramentas.

  4. Depois que a atualização for concluída, escolha Fechar e reinicie o Visual Studio.

Observação

No Visual Studio 2019 e posterior, a extensão das ferramentas do Azure Functions é atualizada como parte do Visual Studio.

Criar um projeto do Azure Functions

O modelo de projeto do Azure Functions no Visual Studio cria um projeto de biblioteca de classes C# que você pode publicar em um aplicativo de funções no Azure. Você pode usar um aplicativo de funções para agrupar funções como uma unidade lógica para facilitar o gerenciamento, a implantação, o dimensionamento e o compartilhamento de recursos.

  1. No menu do Visual Studio, selecione Arquivo > Novo > Projeto.

  2. Em Criar um projeto, insira funções na caixa de pesquisa, escolha o modelo Azure Functions e, em seguida, selecione Próximo.

  3. Em Configurar seu novo projeto, insira um Nome de projeto para seu projeto e, em seguida, selecione Criar. O nome do aplicativo de funções deve ser válido como um namespace do C# e, portanto, não use outros caracteres não alfanuméricos, hífens ou sublinhados.

  4. Para as configurações de Criar um aplicativo do Azure Functions, use os valores da tabela a seguir:

    Configuração Valor Descrição
    Versão do .NET .NET Core 3 (LTS) Esse valor cria um projeto de função que é executado em processo com a versão 3.x do Azure Functions Runtime. O Azure Functions 1.x dá suporte ao .NET Framework. Para obter mais informações, consulte Visão geral de versões do Azure Functions runtime.
    Modelo de função Gatilho HTTP Esse valor cria uma função acionada por uma solicitação HTTP.
    Conta de armazenamento (AzureWebJobsStorage) Emulador de armazenamento Como um aplicativo de funções no Azure requer uma conta de armazenamento, ela será atribuída ou criada quando você publicar seu projeto no Azure. Um gatilho HTTP não usa uma cadeia de conexão da conta do Armazenamento do Azure; todos os outros tipos de gatilho exigem uma cadeia de conexão válida da conta do Armazenamento do Azure.
    Nível de autorização Anônimo A função criada pode ser acionada por qualquer cliente sem fornecer uma chave. Essa configuração de autorização torna fácil testar a nova função. Para obter mais informações sobre chaves e autorização, consulte Chaves de autorização e associações HTTP e webhook.

    Configurações do projeto do Azure Functions

    Verifique se você definiu o Nível de autorização como Anônimo. Se você escolher o nível padrão da Função, será necessário que você apresente a chave da função em solicitações para acessar seu ponto de extremidade da função.

  5. Selecione Criar para criar o projeto de função e a função de gatilho HTTP.

Depois de criar um projeto do Azure Functions, o modelo de projeto cria um projeto C#, instala o pacote NuGet Microsoft.NET.Sdk.Functions e define a estrutura de destino. O novo projeto contém os seguintes arquivos:

  • host.json: Permite que você configure o host do Functions. Essas configurações se aplicam para execução local e no Azure. Para obter mais informações, consulte a referência para host.json.

  • local.Settings.json: Mantém as configurações usadas ao executar as funções localmente. Essas configurações não são usadas quando estão em execução no Azure. Para obter mais informações, confira Arquivo de configurações local.

    Importante

    Como o arquivo local.settings.json pode conter segredos, você precisa excluí-lo do controle do código-fonte do projeto. Verifique se a configuração Copiar para o Diretório de Saída desse arquivo está definida como Copiar se for mais recente.

Para saber mais, confira Projeto de biblioteca de classe de funçõ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.

O Visual Studio não carrega automaticamente as configurações em local.settings.json quando você publica o projeto. Para que essas configurações também existam em seu aplicativo de funções no Azure, carregue-as depois de publicar seu projeto. Para obter mais informações, confira Configurações do aplicativo de funções. Os valores em uma coleção ConnectionStrings nunca são publicados.

Seu código também pode ler os valores de configurações do aplicativo de funções como variáveis de ambiente. Para obter mais informações, confira Variáveis de ambiente.

Definir as configurações de saída do build

Quando você cria um projeto do Azure Functions, as ferramentas de build otimizam a saída para que apenas uma cópia de qualquer assembly compartilhado com o runtime do Functions seja preservada. O resultado é um build otimizado que economiza o máximo de espaço possível. No entanto, quando você muda para uma versão mais recente de qualquer um dos seus assemblies de projeto, as ferramentas de build podem não saber que esses assemblies precisam ser preservados. Para garantir que esses assemblies sejam preservados durante o processo de otimização, você pode especificá-los usando elementos FunctionsPreservedDependencies no arquivo de projeto (.csproj):

  <ItemGroup>
    <FunctionsPreservedDependencies Include="Microsoft.AspNetCore.Http.dll" />
    <FunctionsPreservedDependencies Include="Microsoft.AspNetCore.Http.Extensions.dll" />
    <FunctionsPreservedDependencies Include="Microsoft.AspNetCore.Http.Features.dll" />
  </ItemGroup>

Configurar seu projeto para desenvolvimento local

O runtime do Functions usa internamente uma conta de Armazenamento do Azure. Para todos os tipos de gatilhos diferentes de HTTP e webhooks, defina a chave Values.AzureWebJobsStorage como uma cadeia de conexão de conta de Armazenamento do Azure válida. O aplicativo de funções também pode usar o Emulador de Armazenamento do Azure para a configuração de conexão AzureWebJobsStorage exigida pelo projeto. Para usar o emulador, defina o valor de AzureWebJobsStorage como UseDevelopmentStorage=true. Altere essa configuração para uma cadeia de conexão de conta de armazenamento antes da implantação.

Para definir a cadeia de conexão da conta de armazenamento:

  1. No Visual Studio, selecione Exibir > Cloud Explorer.

  2. No Cloud Explorer, expanda Contas de Armazenamento e selecione sua conta de armazenamento. Na guia Propriedades, copie o valor da Cadeia de Conexão Primária.

  3. Em seu projeto, abra o arquivo local.settings.json e defina o valor da chave AzureWebJobsStorage na cadeia de conexão que você copiou.

  4. Repita a etapa anterior para adicionar as chaves exclusivas para a matriz de Values para todas as outras conexões necessárias para as suas funções.

Adicionar uma função ao projeto

Nas funções da biblioteca de classes C#, as associações usadas pela função são definidas aplicando atributos no código. Quando você cria seus gatilhos de função com base nos modelos fornecidos, os atributos de gatilho são aplicados para você.

  1. No Gerenciador de Soluções, clique com o botão direito do mouse no nó do projeto e selecione Adicionar > Novo Item.

  2. Selecione Função do Azure, insira um Nome para a classe e escolha Adicionar.

  3. Escolha o gatilho, defina as propriedades de associação e clique em OK. O exemplo a seguir mostra as configurações para criar uma função de gatilho de armazenamento de filas.

    Criar uma função de gatilho de armazenamento de filas

    Este exemplo de gatilho usa uma cadeia de conexão com uma chave chamada QueueStorage. Defina esta configuração de cadeia de conexão no arquivo local.settings.json.

  4. Examine a classe recém-adicionada. Você verá um método Run() estático atribuído com o atributo FunctionName. Esse atributo indica que o método é o ponto de entrada para a função.

    Por exemplo, a seguinte classe C# representa uma função básica de gatilho de armazenamento de filas:

    using System;
    using Microsoft.Azure.WebJobs;
    using Microsoft.Azure.WebJobs.Host;
    using Microsoft.Extensions.Logging;
    
    namespace FunctionApp1
    {
        public static class Function1
        {
            [FunctionName("QueueTriggerCSharp")]
            public static void Run([QueueTrigger("myqueue-items", 
                Connection = "QueueStorage")]string myQueueItem, ILogger log)
            {
                log.LogInformation($"C# Queue trigger function processed: {myQueueItem}");
            }
        }
    }
    

Um atributo específico de associação é aplicado a cada parâmetro de associação fornecido ao método do ponto de entrada. O atributo utiliza as informações de associação como parâmetros. No exemplo anterior, o primeiro parâmetro tem um atributo QueueTrigger aplicado, que indica a função de gatilho de armazenamento de filas. O nome da fila e o nome de configuração da cadeia de conexão são passadas como parâmetros ao atributo QueueTrigger. Para obter mais informações, veja Associações do armazenamento de Fila do Azure para o Azure Functions.

Use o procedimento acima para adicionar mais funções a seu projeto de aplicativo de funções. Cada função no projeto pode ter um gatilho diferente, mas uma função deve ter apenas um gatilho. Para obter mais informações, consulte Gatilhos e conceitos de associações do Azure Functions.

Adicionar associações

Assim como acontece com gatilhos, as associações de entrada e saída são adicionadas à sua função como atributos de associação. Adicione associações a uma função da seguinte maneira:

  1. Verifique se você configurou o projeto para desenvolvimento local.

  2. Adicione o pacote de extensão do NuGet pertinente para a associação.

    Para obter mais informações, confira Biblioteca de classes C# com o Visual Studio. Localize os requisitos de pacote NuGet específicos da associação no artigo de referência da associação. Por exemplo, encontre os requisitos do pacote para o gatilho dos Hubs de Eventos no artigo de referência da associação dos Hubs de Eventos.

  3. Se houver configurações de aplicativo exigidas pela associação, adicione-as à coleção Values no arquivo de configuração local.

    A função usa esses valores quando ele é executado localmente. Quando a função é executada no aplicativo de funções no Azure, ela usa configurações do aplicativo de funções.

  4. Adicione o atributo de associação apropriado para a assinatura do método. No exemplo a seguir, uma mensagem da fila dispara a função e a associação de saída cria uma nova mensagem de fila com o mesmo texto em uma fila diferente.

    public static class SimpleExampleWithOutput
    {
        [FunctionName("CopyQueueMessage")]
        public static void Run(
            [QueueTrigger("myqueue-items-source", Connection = "AzureWebJobsStorage")] string myQueueItem, 
            [Queue("myqueue-items-destination", Connection = "AzureWebJobsStorage")] out string myQueueItemCopy,
            ILogger log)
        {
            log.LogInformation($"CopyQueueMessage function processed: {myQueueItem}");
            myQueueItemCopy = myQueueItem;
        }
    }
    

    A conexão com o Armazenamento de filas é obtida na configuração AzureWebJobsStorage. Para saber mais, confira o artigo de referência da associação específica.

Esta tabela mostra as associações que são compatíveis com as versões principais do Azure Functions Runtime:

Tipo 1.x 2.x e posterior1 Gatilho Entrada Saída
Armazenamento de Blobs
Azure Cosmos DB
Dapr3
Grade de Eventos
Hubs de Evento
HTTP e webhooks
Hub IoT
Kafka2
Aplicativos Móveis
Hubs de Notificação
Armazenamento de filas
RabbitMQ2
SendGrid
Barramento de Serviço
SignalR
Armazenamento de tabelas
Timer
Twilio

1 A partir de runtimes de versão 2.x e posteriores, todas as associações, exceto HTTP e Timer, precisam ser registradas. Confira Registrar as extensões de associação.

2 Não há suporte para gatilhos no plano de Consumo. Requer gatilhos controlados por runtime.

3 Com suporte apenas no Kubernetes, IoT Edge e outros modos com auto-hospedagem.

Funções de teste

As Ferramentas Principais do Azure Functions permitem executar o projeto do Azure Functions no seu computador de desenvolvimento local. Para obter mais informações, confira Trabalhar com o Azure Functions Core Tools. É solicitado que você instale essas ferramentas na primeira vez em que inicia uma função no Visual Studio.

Para testar sua função no Visual Studio:

  1. Pressione F5. Se solicitado, aceite a solicitação do Visual Studio para baixar e instalar as ferramentas principais (CLI) do Azure Functions. Além disso, talvez seja necessário habilitar uma exceção de firewall para que as ferramentas possam manipular solicitações HTTP.

  2. Com o projeto em execução, teste seu código da mesma forma que você testaria uma função implantada.

    Para saber mais informações, consulte Estratégias para testar seu código no Azure Functions. Quando você executa o Visual Studio em modo de depuração, os pontos de interrupção são atingidos conforme o esperado.

Publicar no Azure

Quando você faz uma publicação do Visual Studio, ele usa um dos dois métodos de implantação:

Use as etapas a seguir para publicar seu projeto para um aplicativo de funções no Azure.

  1. No Gerenciador de Soluções, clique com o botão direito do mouse no projeto e selecione Publicar. Depois, em Destino, selecione Azure e Avançar.

  2. Para o Destino específico, escolha o Aplicativo de Funções do Azure (Windows) , que cria um aplicativo de funções executado no Windows.

  3. Em Instância de Função, escolha Criar uma função do Azure...

    Criar uma instância de aplicativo de funções

  4. Crie uma instância usando os valores especificados nesta tabela:

    Configuração Valor Descrição
    Nome Nome globalmente exclusivo Nome que identifica seu novo aplicativo de funções de forma exclusiva. Aceite esse nome ou insira um novo nome. Os caracteres válidos são: a-z, 0-9 e -.
    Assinatura Sua assinatura A assinatura do Azure a utilizar. Aceite esta assinatura ou selecione uma nova na lista suspensa.
    Grupo de recursos Nome do seu grupo de recursos O grupo de recursos no qual criar o seu aplicativo de funções. Selecione um grupo de recursos existente na lista suspensa ou escolha Novo para criar um grupo de recursos.
    Tipo de Plano Consumo Quando você publica seu projeto em um aplicativo de funções executado em um Plano de consumo, você paga apenas pelas execuções do seu aplicativo de funções. Outros planos de hospedagem incorrem em custos mais altos.
    Localidade Local do serviço de aplicativo Escolha um Local em uma região perto de você ou de outros serviços acessados pelas suas funções.
    Armazenamento do Azure Conta de armazenamento para uso geral Uma conta do Armazenamento do Azure é requerida pelo runtime do Functions. Selecione Novo para configurar uma conta de armazenamento para uso geral. Você também pode escolher uma conta existente que atenda aos requisitos da conta de armazenamento.

    Criar caixa de diálogo do Serviço de Aplicativo

  5. Selecione Criar para criar um aplicativo de funções e recursos relacionados no Azure. O status da criação do recurso é mostrado na parte inferior esquerda da janela.

  6. Na Instância do Functions, verifique se Executar no arquivo do pacote está marcado. Seu aplicativo de funções é implantado usando a Implantação de Zip com o modo Run-From-Package habilitado. Esse é o método de implantação recomendado para o seu projeto do Functions, pois ele resulta em um melhor desempenho.

    Concluir a criação do perfil

  7. Selecione Concluir e, na página Publicar, selecione Publicar para implantar o pacote que contém os arquivos do projeto no seu novo aplicativo de funções no Azure.

    Após a conclusão da implantação, a URL raiz do aplicativo de funções no Azure é mostrada na guia Publicar.

  8. Na guia Publicar, escolha Gerenciar no Cloud Explorer. Isso abre o novo recurso do Azure do aplicativo de funções no Cloud Explorer.

    Publicar mensagem de êxito

    O Cloud Explorer permite que você use o Visual Studio para exibir o conteúdo do site, iniciar e parar o aplicativo de funções e navegar diretamente para recursos do aplicativo de funções no Azure e no portal do Azure.

Configurações do aplicativo de funções

Como o Visual Studio não carrega essas configurações automaticamente quando você publica o projeto, todas as configurações que você adiciona no local.settings.json você também precisa adicionar ao aplicativo de funções no Azure.

A maneira mais fácil de carregar as configurações necessárias para o seu aplicativo de função no Azure é selecionar o link Gerenciar configurações do Serviço de Aplicativo do Azure exibido depois que você publica seu projeto com êxito.

Configurações na janela Publicar

Selecionar esse link exibe a caixa de diálogo Configurações de aplicativo para o aplicativo de função, onde você pode adicionar novas configurações do aplicativo ou modificar as existentes.

Configurações do aplicativo

Local exibe um valor de configuração no arquivo local.settings.json e Remoto exibe uma configuração atual no aplicativo de funções no Azure. Escolha Adicionar configuração para criar uma nova configuração de aplicativo. Use o link Inserir valor do local para copiar um valor de configuração para o campo Remoto. As alterações pendentes serão gravadas no arquivo de configurações local e no aplicativo de funções quando você selecionar OK.

Observação

Por padrão, o check-in do arquivo local.settings.json não é feito no controle do código-fonte. Isso significa que, se você clonar um projeto local do Functions do controle do código-fonte, o projeto não terá um arquivo local.settings.json. Nesse caso, você precisa criar manualmente o local.settings.json arquivo na raiz do projeto para que a caixa de diálogo Configurações do aplicativo funcione conforme o esperado.

Você também pode gerenciar as configurações de aplicativo em um desses outros modos:

Funções de monitoramento

A maneira recomendada de monitorar a execução de suas funções é a integração do aplicativo de funções com o Azure Application Insights. Ao criar um aplicativo de funções no portal do Azure, essa integração é realizada por padrão. No entanto, ao criar o aplicativo de funções durante a publicação do Visual Studio, a integração no aplicativo de funções no Azure não é realizada. Para saber como conectar o Application Insights ao seu aplicativo de funções, confira Habilitar a integração do Application Insights.

Para saber mais sobre o monitoramento usando o Application Insights, confira Monitorar o Azure Functions.

Próximas etapas

Para obter mais informações sobre o Azure Functions Core Tools, confira Trabalhar com o Azure Functions Core Tools.

Para obter mais informações sobre como desenvolver funções como bibliotecas de classes do .NET, confira Referência do desenvolvedor de C# do Azure Functions. Este tópico também fornece links para exemplos de como usar atributos para declarar os vários tipos de associações com suporte pelo Azure Functions.