Criar sua primeira função durável em C#

  • Artigo

Durable Functions são uma extensão do Azure Functions que permitem que você escreva funções com estado em um ambiente sem servidor. A extensão gerencia estado, pontos de verificação e reinicializações para você.

Neste artigo, você aprenderá a usar o Visual Studio Code para criar e testar localmente uma função durável "olá, mundo". Essa função orquestra e encadeia chamadas para outras funções. Em seguida, você poderá publicar o código de função no Azure. Essas ferramentas estão disponíveis como parte da extensão Azure Functions do Visual Studio Code.

A captura de tela mostra uma janela do Visual Studio Code com uma função durável.

Pré-requisitos

Para concluir este tutorial:

Caso você não tenha uma assinatura do Azure, crie uma conta gratuita do Azure antes de começar.

Criar seu projeto local

Nesta seção, você usará o Visual Studio Code para criar um projeto local do Azure Functions.

  1. No Visual Studio Code, pressione F1 (ou CTRL/Cmd + SHIFT + P) para abrir a paleta de comandos. Na paleta de comandos, pesquise e selecione Azure Functions: Create New Project....

    Captura de tela da janela Criar um projeto do Functions.

  2. Escolha um local em uma pasta vazia para o projeto e escolha Selecionar.

  3. Siga os avisos e forneça as seguintes informações:

    Prompt Valor Descrição
    Selecione uma linguagem de programação para o seu projeto de aplicativo de função. C# Criar um projeto local do Functions em C#.
    Selecione uma versão Azure Functions v4 Você verá essa opção somente quando o Core Tools ainda não estiver instalado. Nesse caso, o Core Tools é instalado na primeira vez em que você executa o aplicativo.
    Selecione um modelo para a primeira função do projeto Ignorar por enquanto
    Selecione como você gostaria de abrir seu projeto Abrir na janela atual Reabre o Visual Studio Code na pasta selecionada.

O Visual Studio Code instalará o Azure Functions Core Tools se necessário. Ele também cria o projeto de aplicativo de funções em uma pasta. Este projeto contém os arquivos de configuração host.json e local.settings.json.

Adicionar funções ao aplicativo

As etapas a seguir usam um modelo para criar o código da durable function no projeto.

  1. Na paleta de comandos, pesquise e selecione Azure Functions: Create Function....

  2. Siga os avisos e forneça as seguintes informações:

    Prompt Valor Descrição
    Selecione um modelo para a função DurableFunctionsOrchestration Crie uma orquestração das Durable Functions
    Forneça um nome de função HelloOrchestration Nome da classe na qual as funções são criadas
    Forneça um namespace Company.Function Namespace da classe gerada

  3. Quando o Visual Studio Code solicitar a seleção de uma conta de armazenamento, escolha Selecionar conta de armazenamento. Siga os prompts e forneça as seguintes informações para criar uma conta de armazenamento no Azure:

    Prompt Valor Descrição
    Selecionar uma assinatura nome da sua assinatura Selecionar sua assinatura do Azure
    Selecione uma conta de armazenamento Criar uma nova conta de armazenamento
    Insira o nome da nova conta de armazenamento nome exclusivo Nome da conta de armazenamento a ser criada
    Selecionar um grupo de recursos nome exclusivo Nome do grupo de recursos a ser criado
    Selecione um local região Selecione uma região próxima de você

Uma classe que contém as novas funções é adicionada ao projeto. O Visual Studio Code também adiciona a cadeia de conexão da conta de armazenamento a local.settings.json e uma referência ao pacote NuGet Microsoft.Azure.WebJobs.Extensions.DurableTask ao arquivo de projeto .csproj.

Abra o novo arquivo HelloOrchestration.cs para exibir o conteúdo. Essa durable function é um exemplo simples de encadeamento de funções com os seguintes métodos:

Método FunctionName Descrição
RunOrchestrator HelloOrchestration Gerencia a orquestração durável. Nesse caso, a orquestração é iniciada, cria uma lista e adiciona o resultado de três chamadas de função à lista. Quando as três chamadas de função são concluídas, ela retorna a lista.
SayHello HelloOrchestration_Hello A função retorna uma saudação. É a função que contém a lógica de negócios que está sendo orquestrada.
HttpStart HelloOrchestration_HttpStart Uma função disparada por HTTP que inicia uma instância da orquestração e retorna uma resposta de status de verificação.

Agora que você criou seu projeto de função e uma função durável, poderá testá-la em seu computador local.

Testar a função localmente

As Ferramentas Principais do Azure Functions permitem executar um projeto do Azure Functions no seu computador de desenvolvimento local. É solicitado que você instale essas ferramentas na primeira vez em que inicia uma função no Visual Studio Code.

  1. Para testar sua função, defina um ponto de interrupção no código da função da atividade SayHello e pressione F5 para iniciar o projeto do aplicativo de funções. A saída do Core Tools é exibida no painel Terminal.

    Observação

    Para obter mais informações sobre depuração, confira Diagnóstico das Durable Functions.

  2. No painel Terminal, copie o ponto de extremidade de URL da sua função disparada por HTTP.

    Captura de tela da janela Saída local do Azure.

  3. Usando uma ferramenta como o Postman ou o cURL, envie uma solicitação HTTP POST ao ponto de extremidade de URL.

    A resposta é o resultado inicial da função HTTP, informando que a orquestração durável foi iniciada com êxito. Ela ainda não é o resultado final da orquestração. A resposta inclui algumas URLs úteis. Por enquanto, vamos consultar o status da orquestração.

  4. Copie o valor da URL para statusQueryGetUri, cole-o na barra de endereços do navegador e execute a solicitação. Como alternativa, você também pode continuar usando o Postman para emitir a solicitação GET.

    A solicitação consultará a instância de orquestração do status. Você precisa obter uma resposta eventual, que nos mostra que a instância foi concluída e inclui as saídas ou os resultados da função durável. Ele tem esta aparência:

    {
    "name": "HelloOrchestration",
    "instanceId": "9a528a9e926f4b46b7d3deaa134b7e8a",
    "runtimeStatus": "Completed",
    "input": null,
    "customStatus": null,
    "output": [
        "Hello Tokyo!",
        "Hello Seattle!",
        "Hello London!"
    ],
    "createdTime": "2020-03-18T21:54:49Z",
    "lastUpdatedTime": "2020-03-18T21:54:54Z"
}

  5. Para interromper a depuração, pressione SHIFT + F5 no Visual Studio Code.

Após verificar se a função foi executada corretamente no computador local, é hora de publicar o projeto no Azure.

Entrar no Azure

Para criar recursos do Azure ou publicar seu aplicativo, você deve entrar no Azure.

  1. Se você ainda não tiver entrado, escolha o ícone do Azure na barra de Atividades. Em seguida, na área Recursos, escolha Entrar no Azure….

    Captura de tela da janela de entrada no Azure no VS Code.

    Se você já estiver conectado e puder ver suas assinaturas existentes, vá para a próxima seção. Caso ainda não tenha uma conta do Azure, escolha Criar uma conta do Azure…. Os alunos podem escolher Criar uma Conta do Microsoft Azure for Students….

  2. Quando solicitado no navegador, escolha sua conta do Azure e entre usando suas credenciais de conta do Azure. Se você criar uma conta, poderá se conectar depois que a conta for criada.

  3. Após entrar com êxito, você poderá fechar a nova janela do navegador. As assinaturas que pertencem à sua conta do Azure são exibidas na barra lateral.

Criar o aplicativo de funções no Azure

Nesta seção, você criará um aplicativo de funções e os recursos relacionados na sua assinatura do Azure.

  1. Escolha o ícone do Azure na barra de atividades. Em seguida, na área Recursos, selecione o ícone + e escolha a opção Criar Aplicativo de Funções no Azure.

    Crie um recurso em sua assinatura do Azure

  2. Forneça as seguintes informações nos prompts:

    Prompt Seleção
    Selecionar uma assinatura Escolha a assinatura a ser usada. Você não verá esse aviso quando tiver apenas uma assinatura visível em Recursos.
    Insira um nome exclusivo globalmente para o aplicativo de funções Digite um nome que seja válido em um caminho de URL. O nome que você digitar é validado para ter certeza de que ele é exclusivo no Azure Functions.
    Selecionar uma pilha de runtime Escolha a versão da linguagem em que você está fazendo a execução localmente.
    Selecione uma localização para novos recursos Para obter um melhor desempenho, escolha uma região perto de você.

    A extensão mostra o status de recursos individuais conforme eles são criados no Azure no painel Azure: Log de Atividades.

    Log da criação de recursos do Azure

  3. Quando a criação for concluída, os recursos do Azure a seguir serão criados na sua assinatura. Os recursos são nomeados com base no nome do aplicativo de funções:

    • Um grupo de recursos, que é um contêiner lógico para recursos relacionados.
    • Uma conta de armazenamento do Azure padrão, que mantém o estado e outras informações sobre seus projetos.
    • Um aplicativo de funções, que fornece o ambiente para a execução do código de função. Um aplicativo de funções lhe permite agrupar funções como uma unidade lógica para facilitar o gerenciamento, a implantação e o compartilhamento de recursos dentro do mesmo plano de hospedagem.
    • Um Plano do Serviço de Aplicativo, que define o host subjacente do aplicativo de funções.
    • Uma instância do Application Insights conectada ao aplicativo de funções, que controla o uso das suas funções no aplicativo.

    Uma notificação é exibida depois que seu aplicativo de funções é criado e o pacote de implantação é aplicado.

    Dica

    Por padrão, os recursos do Azure necessários para o aplicativo de funções são criados com base no nome do aplicativo de funções fornecido por você. Por padrão, eles também são criados no mesmo grupo de recursos com o aplicativo de funções. Se desejar personalizar os nomes desses recursos ou reutilizar os recursos existentes, você precisará publicar o projeto com opções de criação avançadas.

Implantar o projeto no Azure

Importante

A implantação em um aplicativo de funções existente sempre substitui o conteúdo do aplicativo no Azure.

  1. Na área Recursos da atividade do Azure, localize o recurso do aplicativo de funções que você acabou de criar, clique com o botão direito do mouse no recurso e selecione Implantar no aplicativo de funções....

  2. Quando solicitado sobre a substituição de implantações anteriores, selecione Implantar para implantar seu código de função no novo recurso do aplicativo de funções.

  3. Após a conclusão da implantação, escolha Exibir Saída para ver a criação e os resultados da implantação, incluindo os recursos do Azure que você criou. Se você perder a notificação, selecione o ícone de sino no canto inferior direito para vê-lo novamente.

    Captura de tela da janela Exibir saída

Testar sua função no Azure

  1. Copie a URL do gatilho de HTTP do painel Saída. A URL que chama a função disparada por HTTP precisa estar no seguinte formato:

    https://<functionappname>.azurewebsites.net/api/HelloOrchestration_HttpStart

  2. Cole essa nova URL para a solicitação HTTP na barra de endereços do navegador. Você precisa obter a mesma resposta de status de antes ao usar o aplicativo publicado.

Próximas etapas

Você usou o Visual Studio Code para criar e publicar um aplicativo de funções duráveis em C#.

Saiba mais sobre os padrões comuns de função durável

Neste artigo, você aprenderá a usar o Visual Studio 2022 para criar e testar localmente uma função durável "Olá, Mundo". Essa função orquestrará e encadeará chamadas para outras funções. Em seguida, você publicará o código de função no Azure. Essas ferramentas estão disponíveis como parte da carga de trabalho de desenvolvimento do Azure no Visual Studio 2022.

Captura de tela de uma janela do Visual Studio 2019 com uma função durável.

Pré-requisitos

Para concluir este tutorial:

  • Instalar o Visual Studio 2022. Garanta que a carga de trabalho de desenvolvimento do Azure também seja instalada. O Visual Studio 2019 também dá suporte ao desenvolvimento de Durable Functions, mas a interface do usuário e as etapas são diferentes.

  • Verifique se você tem o Emulador de Azurite instalado e em execução.

Caso você não tenha uma assinatura do Azure, crie uma conta gratuita do Azure antes de começar.

Crie um projeto de aplicativo de funções

O modelo do Azure Functions cria um projeto que pode ser publicado em um aplicativo de funções no Azure. Um aplicativo de funções lhe permite agrupar funções como uma unidade lógica para facilitar o gerenciamento, a implantação, o dimensionamento e o compartilhamento de recursos.

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

  2. Na caixa de diálogo Criar um projeto, procure functions, escolha o modelo do Azure Functions e selecione Avançar.

    Captura de tela da caixa de diálogo Novo Projeto para criar uma função no Visual Studio.

  3. Insira um Nome do projeto e selecione OK. O nome do projeto precisa ser válido como um namespace do C#. Portanto, não use sublinhados, hifens ou caracteres não alfanuméricos.

  4. Em Informações adicionais, use as configurações especificadas na tabela que acompanha a imagem.

    Captura de tela da caixa de diálogo Criar um novo aplicativo do Azure Functions no Visual Studio.

    Configuração Valor sugerido Descrição
    Função de trabalho do Functions .NET 6 Cria um projeto de função que dá suporte ao .NET 6 e ao Azure Functions Runtime 4.0. Para obter mais informações, consulte Como direcionar para versões do Azure Functions runtime.
    Função Vazio Cria um aplicativo de funções vazio.
    Conta de armazenamento Emulador de Armazenamento Uma conta de armazenamento é necessária para o gerenciamento de estado de uma função durável.

  5. Selecione Criar para criar um projeto de função vazio. Este projeto tem os arquivos de configuração básicos necessários para executar suas funções.

Adicionar funções ao aplicativo

As etapas a seguir usam um modelo para criar o código da durable function no projeto.

  1. Clique com o botão direito do mouse no Visual Studio e escolha Adicionar>Novo Azure Function.

    Captura de tela da opção Adicionar nova função.

  2. Verifique se a opção Função do Azure está selecionada no menu de adição, insira um nome para o arquivo C# e escolha Adicionar.

  3. Escolha o modelo Orquestração de Durable Functions e selecione Adicionar.

    Captura de tela da opção Selecionar modelo durável.

Uma nova durable function será adicionada ao aplicativo. Abra o novo arquivo .cs para ver o conteúdo. Essa durable function é um exemplo simples de encadeamento de funções com os seguintes métodos:

Método FunctionName Descrição
RunOrchestrator <file-name> Gerencia a orquestração durável. Nesse caso, a orquestração é iniciada, cria uma lista e adiciona o resultado de três chamadas de função à lista. Quando as três chamadas de função são concluídas, ela retorna a lista.
SayHello <file-name>_Hello A função retorna uma saudação. É a função que contém a lógica de negócios que está sendo orquestrada.
HttpStart <file-name>_HttpStart Uma função disparada por HTTP que inicia uma instância da orquestração e retorna uma resposta de status de verificação.

Teste isso no computador local agora que criou seu projeto de função e uma função durável.

Testar a função localmente

As Ferramentas Principais do Azure Functions permitem executar um projeto do Azure Functions no seu computador de desenvolvimento local. É solicitado que você instale essas ferramentas na primeira vez em que inicia uma função no Visual Studio.

  1. Para testar a função, pressione F5. Se solicitado, aceite a solicitação do Visual Studio para baixar e instalar as ferramentas principais (CLI) do Azure Functions. Você também precisará habilitar a exceção de firewall de forma que as ferramentas possam lidar com solicitações HTTP.

  2. Copie a URL da sua função da saída do Azure Functions runtime.

    Captura de tela do runtime local do Azure.

  3. Cole a URL da solicitação HTTP na barra de endereços do navegador e execute a solicitação. O exemplo a seguir mostra a resposta no navegador à solicitação GET local retornada pela função:

    Captura de tela de uma janela do navegador com statusQueryGetUri chamado.

    A resposta é o resultado inicial da função HTTP, informando que a orquestração durável foi iniciada com êxito. Ela ainda não é o resultado final da orquestração. A resposta inclui algumas URLs úteis. Por enquanto, vamos consultar o status da orquestração.

  4. Copie o valor da URL para statusQueryGetUri, cole-o na barra de endereços do navegador e execute a solicitação.

    A solicitação consultará a instância de orquestração do status. Você precisa receber uma resposta eventual parecida com a mostrada a seguir. Esse resultado mostra que a instância foi concluída e inclui os resultados ou as saídas da função durável.

    {
    "name": "Durable",
    "instanceId": "d495cb0ac10d4e13b22729c37e335190",
    "runtimeStatus": "Completed",
    "input": null,
    "customStatus": null,
    "output": [
        "Hello Tokyo!",
        "Hello Seattle!",
        "Hello London!"
    ],
    "createdTime": "2019-11-02T07:07:40Z",
    "lastUpdatedTime": "2019-11-02T07:07:52Z"
}

  5. Para interromper a depuração, pressione Shift + F5.

Após verificar se a função foi executada corretamente no computador local, é hora de publicar o projeto no Azure.

Publicar o projeto no Azure

Você precisa ter um aplicativo de funções na sua assinatura do Azure antes de publicar seu projeto. Você pode criar um aplicativo de funções diretamente no Visual Studio.

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

    Captura de tela da janela de publicação.

  2. Escolha Aplicativo de Funções do Azure (Windows) em Destino específico, o que criará um aplicativo de funções executado no Windows, e selecione Avançar.

    Captura de tela da janela de publicação com destino específico.

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

    Captura de tela de 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 você deseja criar o aplicativo de funções. Selecione Novo para criar um novo grupo de recursos. Você também pode escolher um grupo de recursos existente na lista suspensa.
    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 de 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.
    Application Insights Instância do Application Insights Você deve habilitar a integração do Application Insights para seu aplicativo de funções. Selecione Novo para criar uma nova instância, em um workspace novo ou em um workspace do Log Analytics existente. Você também pode escolher uma instância existente.

    Captura de tela da caixa de diálogo Criar 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 no canto inferior esquerdo da janela.

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

    Captura de tela de Concluir 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.

    Concluída a implantação, a URL raiz do aplicativo de funções no Azure é mostrada na guia Publicar.

  8. Na guia Publicar, na seção Hospedagem, escolha Abrir no portal do Azure. O novo recurso de aplicativo de funções do Azure é aberto no portal do Azure.

    Captura de tela de Publicar mensagem de êxito.

Testar sua função no Azure

  1. Copie a URL base do aplicativo de funções da página de perfil de publicação. Substitua a parte localhost:port da URL que você usou ao testar a função localmente pela nova URL base.

    A URL que chama o gatilho HTTP da função durável precisa estar no seguinte formato:

    https://<APP_NAME>.azurewebsites.net/api/<FUNCTION_NAME>_HttpStart

  2. Cole essa nova URL para a solicitação HTTP na barra de endereços do navegador. Você precisa obter a mesma resposta de status de antes ao usar o aplicativo publicado.

Próximas etapas

Você usou o Visual Studio Code para criar e publicar um aplicativo de funções C# durável.

Saiba mais sobre os padrões comuns de função durável