Create your first durable function in C# (Criar a sua primeira função durável em C#)

  • Artigo

O Durable Functions é uma extensão do Azure Functions que permite escrever funções com monitoração de estado em um ambiente sem servidor. A extensão gere o estado, os pontos de verificação e os reinícios por si.

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

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

Pré-requisitos

Para concluir este tutorial:

  • Instalar o Visual Studio Code.

  • Instale as seguintes extensões de código do Visual Studio:

  • Certifique-se de que tem a versão mais recente das Ferramentas Principais do Azure Functions.

  • As Funções Duráveis exigem uma conta de armazenamento do Azure. Precisa de uma subscrição do Azure.

  • Verifique se você tem a versão 3.1 ou uma versão posterior do SDK do .NET Core instalada .

Se não tiver uma subscrição do Azure, crie uma conta gratuita do Azure antes de começar.

Criar o seu projeto local

Nesta seção, você usa 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, procure e selecione Azure Functions: Create New Project....

    Captura de tela da janela criar um projeto de função.

  2. Escolha um local de pasta vazia para seu projeto e escolha Selecionar.

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

    Pedido valor Description
    Selecione um idioma para seu projeto de aplicativo de função C# Crie um projeto local do C# Functions.
    Selecione uma versão Azure Functions v4 Você só verá essa opção quando as Ferramentas Principais ainda não estiverem instaladas. Nesse caso, as Ferramentas Principais são instaladas na primeira vez que você executa o aplicativo.
    Selecione um modelo para a primeira função do seu projeto Ignorar por agora
    Selecione como gostaria de abrir o seu projeto Abrir na janela atual Reabre o Visual Studio Code na pasta selecionada.

O Visual Studio Code instala as Ferramentas Principais do Azure Functions, se necessário. Ele também cria um projeto de aplicativo de função em uma pasta. Este projeto contém os arquivos de configuração host.json e local.settings.json .

Adicionar funções à aplicação

As etapas a seguir usam um modelo para criar o código de função durável em seu projeto.

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

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

    Pedido valor Description
    Selecione um modelo para a sua função DurávelFunçõesOrquestração Criar uma orquestração de funções duráveis
    Fornecer um nome de função OláOrquestração Nome da classe na qual as funções são criadas
    Fornecer um namespace Empresa.Função Namespace para a classe gerada

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

    Pedido valor Description
    Selecionar subscrição Nome da sua subscrição Selecione a sua subscrição do Azure
    Selecionar 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
    Selecionar uma localização região Selecione uma região perto de si

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

Abra o novo arquivo HelloOrchestration.cs para exibir o conteúdo. Esta função durável é um exemplo simples de encadeamento de funções com os seguintes métodos:

Método Nome da função Description
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ções à lista. Quando as três chamadas de função estiverem concluídas, ele retornará a lista.
SayHello HelloOrchestration_Hello A função retorna um olá. É a função que contém a lógica de negócios que está sendo orquestrada.
HttpStart HelloOrchestration_HttpStart Uma função acionada 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, você pode testá-lo em seu computador local.

Testar localmente a função

As Ferramentas de Núcleo das Funções do Azure permitem-lhe executar um projeto de funções do Azure no seu computador de programação local. Deve instalar estas ferramentas ao iniciar uma função do Visual Studio Code pela primeira vez.

  1. Para testar sua função, defina um ponto de interrupção no código da SayHello função de atividade e pressione F5 para iniciar o projeto do aplicativo de função. São apresentados os resultados das Ferramentas de Núcleo no painel Terminal.

    Nota

    Para obter mais informações sobre depuração, consulte Diagnóstico de funções duráveis.

  2. No painel Terminal, copie o ponto final do URL da sua função acionada por HTTP.

    Captura de ecrã da janela de saída local do Azure.

  3. Use uma ferramenta como Postman ou cURL e, em seguida, envie uma solicitação HTTP POST para o ponto de extremidade URL.

    A resposta é o resultado inicial da função HTTP, informando-nos que a orquestração durável foi iniciada com sucesso. Ainda não é o resultado final da orquestração. A resposta inclui alguns URLs úteis. Por enquanto, vamos consultar o status da orquestração.

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

    A solicitação consultará a instância de orquestração para obter o status. Você deve obter uma resposta eventual, que nos mostre que a instância foi concluída e inclua as saídas ou resultados da função durável. Tem a seguinte 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 parar a depuração, pressione Shift + F5 no Visual Studio Code.

Depois de verificar que a função é executada corretamente no computador local, deve publicar o projeto no Azure.

Iniciar sessão no Azure

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

  1. Se você ainda não estiver conectado, escolha o ícone do Azure na barra de atividades. Em seguida, na área Recursos, escolha Entrar no Azure....

    Captura de ecrã do início de sessão na janela do Azure no VS Code.

    Se já tiver sessão iniciada e conseguir ver as suas subscrições existentes, vá para a secção seguinte. Se você ainda não tiver uma conta do Azure, escolha Criar uma Conta do Azure.... Os alunos podem escolher Criar uma Conta do Azure para Estudantes....

  2. Quando solicitado no navegador, escolha sua conta do Azure e entre usando suas credenciais de conta do Azure. Se criar uma nova conta, pode iniciar sessão depois de a sua conta ser criada.

  3. Depois de iniciar sessão com êxito, pode fechar a nova janela do browser. As assinaturas que pertencem à sua conta do Azure são exibidas na barra lateral.

Criar o aplicativo de função no Azure

Nesta seção, você cria um aplicativo de função e recursos relacionados em 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ção no Azure .

    Criar um recurso na sua subscrição do Azure

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

    Pedido Seleção
    Selecionar subscrição Escolha a subscrição a utilizar. Você não verá esse prompt quando tiver apenas uma assinatura visível em Recursos.
    Insira um nome globalmente exclusivo para o aplicativo de função Digite um nome válido em um caminho de URL. O nome digitado é validado para garantir que seja exclusivo no Azure Functions.
    Selecione uma pilha de tempo de execução Escolha a versão de idioma na qual você está executando localmente.
    Selecione um local para novos recursos Para um melhor desempenho, escolha uma região perto de si.

    A extensão mostra o status de recursos individuais à medida que eles estão sendo criados no Azure no painel Azure: Log de Atividades .

    Log de criação de recursos do Azure

  3. Quando a criação estiver concluída, os seguintes recursos do Azure serão criados na sua subscrição. Os recursos são nomeados com base no nome do aplicativo de função:

    • 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ção, que fornece o ambiente para executar seu código de função. Um aplicativo de função 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 para seu aplicativo de função.
    • Uma instância do Application Insights conectada ao aplicativo de função, que rastreia o uso de suas funções no aplicativo.

    Depois de criar a aplicação de funções, é apresentada uma notificação e o pacote de implementação é aplicado.

    Gorjeta

    Por padrão, os recursos do Azure exigidos pelo seu aplicativo de função são criados com base no nome do aplicativo de função fornecido. Por padrão, eles também são criados no mesmo novo grupo de recursos com o aplicativo de função. Se você quiser personalizar os nomes desses recursos ou reutilizar recursos existentes, você precisa publicar o projeto com opções de criação avançadas .

Implementar o projeto no Azure

Importante

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

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

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

  3. Após a conclusão da implantação, selecione Exibir saída para exibir os resultados da criação e 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 ecrã da janela Ver Saída.

Testar a sua função no Azure

  1. Copie o URL do acionador de HTTP no painel Resultados. A URL que chama sua função acionada por HTTP deve estar no seguinte formato:

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

  2. Cole este novo URL do pedido HTTP na barra de endereço do browser. Você deve obter a mesma resposta de status que antes ao usar o aplicativo publicado.

Próximos passos

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

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

Neste artigo, você aprenderá a usar o Visual Studio 2022 para criar e testar localmente uma função durável "hello world". Esta função orquestra e encadeia chamadas para outras funções. Em seguida, publique 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 da janela do Visual Studio 2019 com uma função durável.

Pré-requisitos

Para concluir este tutorial:

  • Instale o Visual Studio 2022. Verifique se a carga de trabalho de desenvolvimento do Azure também está instalada. O Visual Studio 2019 também oferece suporte ao desenvolvimento de funções duráveis, mas a interface do usuário e as etapas são diferentes.

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

Se não tiver uma subscrição do Azure, crie uma conta gratuita do Azure antes de começar.

Criar um projeto de aplicação de função

O modelo do Azure Functions cria um projeto que pode ser publicado em um aplicativo de função no Azure. Um aplicativo de função 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 New>Project (Novo Projeto) no menu File (Ficheiro).

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

    Captura de tela da caixa de diálogo do novo projeto para criar uma função no Visual Studio.

  3. Insira um nome de projeto para seu projeto e selecione OK. O nome do projeto deve ser válido como um namespace C#, portanto, não use sublinhados, hífenes ou caracteres não alfanuméricos.

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

    Captura de ecrã da caixa de diálogo de criação de uma nova caixa de diálogo Aplicação Azure Functions no Visual Studio.

    Definição Valor sugerido Description
    Funções de trabalhador .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, veja How to target Azure Functions runtime version (Como segmentar a versão do runtime das Funções do Azure).
    Função Vazio Cria um aplicativo de função vazio.
    Conta de armazenamento Emulador do Armazenamento Uma conta de armazenamento é necessária para o gerenciamento de estado de 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 à aplicação

As etapas a seguir usam um modelo para criar o código de função durável em seu projeto.

  1. Clique com o botão direito do mouse no projeto no Visual Studio e selecione Adicionar>Nova Função do Azure.

    Captura de ecrã de Adicionar nova função.

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

  3. Selecione o modelo Orquestração de funções duráveis e, em seguida, selecione Adicionar.

    Captura de tela de Selecionar modelo durável.

Uma nova função durável é adicionada ao aplicativo. Abra o novo arquivo .cs para exibir o conteúdo. Esta função durável é um exemplo simples de encadeamento de funções com os seguintes métodos:

Método Nome da função Description
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ções à lista. Quando as três chamadas de função estiverem concluídas, ele retornará a lista.
SayHello <file-name>_Hello A função retorna um olá. É a função que contém a lógica de negócios que está sendo orquestrada.
HttpStart <file-name>_HttpStart Uma função acionada por HTTP que inicia uma instância da orquestração e retorna uma resposta de status de verificação.

Você pode testá-lo em seu computador local agora que você criou seu projeto de função e uma função durável.

Testar localmente a função

As Ferramentas de Núcleo das Funções do Azure permitem-lhe executar um projeto de funções do Azure no seu computador de programação local. Você será solicitado a instalar essas ferramentas na primeira vez que iniciar uma função do Visual Studio.

  1. Para testar a sua função, prima F5. Se solicitado, aceite o pedido do Visual Studio para transferir e instalar as ferramentas de Núcleo das Funções do Azure (CLI). Também poderá ativar a exceção da firewall para que todas as ferramentas possam aceitar os pedidos de HTTP.

  2. Copie o URL da sua função na saída do tempo de execução das funções do Azure.

    Captura de tela do tempo de execução local do Azure.

  3. Cole o URL da solicitação HTTP na barra de endereço do navegador e execute a solicitação. O exemplo apresentado em seguida mostra a resposta no browser relativamente ao pedido GET devolvido retornado pela função:

    Captura de tela da janela do navegador com statusQueryGetUri chamado.

    A resposta é o resultado inicial da função HTTP, informando-nos que a orquestração durável foi iniciada com sucesso. Ainda não é o resultado final da orquestração. A resposta inclui alguns URLs úteis. Por enquanto, vamos consultar o status da orquestração.

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

    A solicitação consultará a instância de orquestração para obter o status. Você deve obter uma eventual resposta parecida com a seguinte. Esta saída nos mostra que a instância foi concluída e inclui as saídas ou resultados 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 parar a depuração, prima Shift + F5.

Depois de verificar que a função é executada corretamente no computador local, deve publicar o projeto no Azure.

Publicar o projeto no Azure

Você deve ter um aplicativo de função em sua assinatura do Azure antes de publicar seu projeto. Pode criar uma aplicação de funções diretamente a partir do Visual Studio.

  1. No Explorador de Soluções, clique com o botão direito do rato no projeto e selecione Publicar. Em Destino, selecione Azure e, em seguida, Avançar.

    Captura de ecrã da janela de publicação.

  2. Selecione Aplicativo de Função do Azure (Windows) para o destino Específico, que cria um aplicativo de função que é executado no Windows e, em seguida, selecione Avançar.

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

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

    Captura de tela da criação de uma nova instância de aplicativo de função.

  4. Crie uma nova instância usando os valores especificados na tabela a seguir:

    Definição valor Descrição
    Nome Nome globalmente exclusivo Nome que identifica exclusivamente a sua nova aplicação de funções. Aceite este nome ou introduza um novo nome. Os caracteres válidos são: a-z, 0-9, e -.
    Subscrição a sua subscrição A subscrição do Azure que deve utilizar. Aceite esta subscrição ou selecione uma nova na lista pendente.
    Grupo de recursos Nome do grupo de recursos O grupo de recursos no qual você deseja criar seu aplicativo de função. 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ção que é 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.
    Location Localização do serviço da aplicação Escolha um local em uma região perto de você ou outros serviços que suas funções acessam.
    Armazenamento do Azure Conta de armazenamento de uso geral O runtime das Funções precisa de uma conta de armazenamento do Azure. Selecione Novo para configurar uma conta de armazenamento de 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ção. Selecione Novo para criar uma nova instância, em um espaço de trabalho novo ou existente do Log Analytics. 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ção e seus recursos relacionados no Azure. O status da criação de recursos é mostrado no canto inferior esquerdo da janela.

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

    Captura de ecrã de Concluir criação de perfil.

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

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

  8. Na guia Publicar, na seção Hospedagem, escolha Abrir no portal do Azure. Isso abre o novo recurso do Azure do aplicativo de função no portal do Azure.

    Captura de ecrã da mensagem Publicar êxito.

Testar a sua função no Azure

  1. Copie a URL de base da aplicação de funções a partir da página de perfil Publicar. Substitua a localhost:port parte da URL que utilizou ao testar a localmente a função com a nova URL de base.

    A URL que chama seu gatilho HTTP de função durável deve estar no seguinte formato:

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

  2. Cole este novo URL do pedido HTTP na barra de endereço do browser. Você deve obter a mesma resposta de status que antes ao usar o aplicativo publicado.

Próximos passos

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

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