Azure Functions com o .NET Aspire (versão prévia)

.NET Aspire é uma pilha opinativa que simplifica o desenvolvimento de aplicativos distribuídos na nuvem. A integração do .NET Aspire ao Azure Functions permite desenvolver, depurar e orquestrar um projeto do .NET do Azure Functions como parte do host do aplicativo .NET Aspire.

Pré-requisitos

Configure seu ambiente de desenvolvimento para usar o Azure Functions com o .NET Aspire:

• Instale o SDK do .NET 9 e o .NET Aspire 9.0 ou posterior. Embora o SDK do .NET 9 seja necessário, o .NET Aspire 9.0 dá suporte às estruturas .NET 8 e .NET 9.
• Se você usar o Visual Studio, atualize para a versão 17.12 ou posterior. Você também deve ter a versão mais recente das ferramentas do Azure Functions para Visual Studio. Para verificar se há atualizações:
  1. Acesse Ferramentas>Opções.
  2. Em Projetos e Soluções, selecione Azure Functions.
  3. Selecione Verificar se há atualizações e instale atualizações conforme solicitado.

Estrutura da solução

Uma solução que usa o Azure Functions e o .NET Aspire tem vários projetos, incluindo um projeto de host de aplicativo e um ou mais projetos do Functions.

O projeto de host do aplicativo é o ponto de entrada para seu aplicativo. Ele orquestra a instalação dos componentes do aplicativo, incluindo o projeto do Functions.

A solução normalmente também inclui um projeto de configurações padrão de serviços. Este projeto fornece um conjunto de serviços e configurações padrão a serem usados entre projetos em seu aplicativo.

Projeto de host do aplicativo

Para configurar com êxito a integração, verifique se o projeto de host do aplicativo atende aos seguintes requisitos:

• O projeto de host do aplicativo deve referenciar Aspire.Hosting.Azure.Functions. Esse pacote define a lógica necessária para a integração.
• O projeto de host do aplicativo precisa ter uma referência de projeto para cada projeto do Functions que você deseja incluir na orquestração.
• No arquivo Program.cs do host do aplicativo, você deve incluir o projeto chamando AddAzureFunctionsProject<TProject>() na sua instância IDistributedApplicationBuilder. Você usa esse método em vez de usar o AddProject<TProject>() método usado para outros tipos de projeto no .NET Aspire. Se você usar AddProject<TProject>(), o projeto do Functions não poderá ser iniciado corretamente.

O exemplo a seguir mostra um arquivo mínimo Program.cs para um projeto de host de aplicativo:

var builder = DistributedApplication.CreateBuilder(args);

builder.AddAzureFunctionsProject<Projects.MyFunctionsProject>("MyFunctionsProject");

builder.Build().Run();

Projeto do Azure Functions

Para configurar a integração com êxito, verifique se o projeto do Azure Functions atende aos seguintes requisitos:

• O projeto do Functions deve fazer referência às versões 2.x de Microsoft.Azure.Functions.Worker e Microsoft.Azure.Functions.Worker.Sdk. Você também deve atualizar as referências Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore para a versão 2.x.

• Seu arquivo Program.cs deve usar a versão IHostApplicationBuilder da inicialização da instância de host. Esse requisito significa que você deve usar FunctionsApplication.CreateBuilder(args).

• Se a solução incluir um projeto padrão de serviço, verifique se o projeto do Functions está configurado para usá-lo:

  • O projeto do Functions deve incluir uma referência de projeto para o projeto de padrões de serviço.
  • Antes de criar IHostApplicationBuilder em Program.cs, inclua uma chamada para builder.AddServiceDefaults().

O exemplo a seguir mostra um arquivo mínimo Program.cs para um projeto do Functions usado no .NET Aspire:

using Microsoft.Azure.Functions.Worker.Builder;
using Microsoft.Extensions.Hosting;

var builder = FunctionsApplication.CreateBuilder(args);

builder.AddServiceDefaults();

builder.ConfigureFunctionsWebApplication();

builder.Build().Run();

Este exemplo não inclui a configuração padrão do Application Insights que aparece em muitos outros Program.cs exemplos e nos modelos do Azure Functions. Em vez disso, você configura a integração do OpenTelemetry no .NET Aspire chamando o builder.AddServiceDefaults método.

Para aproveitar ao máximo a integração, considere as seguintes diretrizes:

• Não inclua nenhuma integração direta do Application Insights no projeto do Functions. Em vez disso, o monitoramento no .NET Aspire é tratado por meio de seu suporte ao OpenTelemetry. Você pode configurar o .NET Aspire para exportar dados para o Azure Monitor por meio do projeto de padrões de serviço.
• Não defina configurações personalizadas de aplicativo no arquivo local.settings.json para o projeto Functions. A única configuração que deve estar em local.settings.json é "FUNCTIONS_WORKER_RUNTIME": "dotnet-isolated". Defina todas as outras configurações de aplicativo por meio do projeto de host do aplicativo.

Configuração de conexão com o .NET Aspire

O projeto de host do aplicativo define recursos e ajuda você a criar conexões entre eles usando código. Esta seção mostra como configurar e personalizar conexões que seu projeto do Azure Functions usa.

O .NET Aspire inclui permissões de conexão padrão que podem ajudá-lo a começar. No entanto, essas permissões podem não ser apropriadas ou suficientes para seu aplicativo.

Para cenários que usam o RBAC (controle de acesso baseado em função) do Azure, você pode personalizar permissões chamando o WithRoleAssignments() método no recurso de projeto. Quando você chama WithRoleAssignments(), todas as atribuições de função padrão são removidas e você deve definir explicitamente as atribuições de função de conjunto completo desejadas. Se você hospedar seu aplicativo nos Aplicativos de Contêiner do Azure, usar WithRoleAssignments() também exigirá que você chame AddAzureContainerAppEnvironment() em DistributedApplicationBuilder.

Armazenamento de host do Azure Functions

O Azure Functions requer uma conexão de armazenamento de host (AzureWebJobsStorage) para vários de seus principais comportamentos. Quando você chama AddAzureFunctionsProject<TProject>() no projeto de host do aplicativo, uma conexão AzureWebJobsStorage é criada por padrão e fornecida ao projeto de Funções. Essa conexão padrão usa o emulador de Armazenamento do Azure para execuções de desenvolvimento local e provisiona automaticamente uma conta de armazenamento quando ela é implantada. Para obter mais controle, você pode substituir essa conexão chamando .WithHostStorage() o recurso de projeto do Functions.

As permissões padrão que o .NET Aspire define para a conexão de armazenamento do host dependem de você chamar WithHostStorage() ou não. A adição de WithHostStorage() remove uma atribuição de Colaborador da Conta de Armazenamento. A tabela a seguir lista as permissões padrão que o .NET Aspire define para a conexão de armazenamento do host:

O exemplo a seguir mostra um arquivo mínimo Program.cs para um projeto de host de aplicativo que substitui o armazenamento do host e especifica uma atribuição de função:

using Azure.Provisioning.Storage;

var builder = DistributedApplication.CreateBuilder(args);

builder.AddAzureContainerAppEnvironment("myEnv");

var myHostStorage = builder.AddAzureStorage("myHostStorage");

builder.AddAzureFunctionsProject<Projects.MyFunctionsProject>("MyFunctionsProject")
    .WithHostStorage(myHostStorage)
    .WithRoleAssignments(myHostStorage, StorageBuiltInRole.StorageBlobDataOwner);

builder.Build().Run();

Como disparar e associar conexões

Seus gatilhos e associações fazem referência a conexões por nome. As seguintes integrações do .NET Aspire fornecem essas conexões por meio de uma chamada para WithReference() o recurso do projeto:

O exemplo a seguir mostra um arquivo mínimo Program.cs para um projeto de hospedagem de app que configura um disparador de fila. Neste exemplo, o gatilho de fila correspondente tem sua Connection propriedade definida como MyQueueTriggerConnection, assim, a chamada para WithReference() especifica o nome.

var builder = DistributedApplication.CreateBuilder(args);

var myAppStorage = builder.AddAzureStorage("myAppStorage").RunAsEmulator();
var queues = myAppStorage.AddQueues("queues");

builder.AddAzureFunctionsProject<Projects.MyFunctionsProject>("MyFunctionsProject")
    .WithReference(queues, "MyQueueTriggerConnection");

builder.Build().Run();

Para outras integrações, chamadas para WithReference definem a configuração de uma maneira diferente. Eles disponibilizam a configuração para integrações de cliente do .NET Aspire, mas não para gatilhos e associações. Para essas integrações, chame WithEnvironment() para passar as informações de conexão do gatilho ou da associação a ser resolvida.

O exemplo a seguir mostra como definir a variável MyBindingConnection de ambiente para um recurso que expõe uma expressão de cadeia de conexão:

builder.AddAzureFunctionsProject<Projects.MyFunctionsProject>("MyFunctionsProject")
    .WithEnvironment("MyBindingConnection", otherIntegration.Resource.ConnectionStringExpression);

Se você quiser que as integrações de cliente do .NET Aspire e o sistema de gatilhos e associações usem uma conexão, você pode configurar WithReference() e WithEnvironment().

Para alguns recursos, a estrutura de uma conexão pode ser diferente quando você a executa localmente e quando você a publica no Azure. No exemplo anterior, otherIntegration poderia ser um recurso executado como um emulador, portanto, ConnectionStringExpression retornaria uma cadeia de conexão do emulador. No entanto, quando o recurso é publicado, o .NET Aspire pode configurar uma conexão baseada em identidade e ConnectionStringExpression retornar o URI do serviço. Nesse caso, para configurar conexões baseadas em identidade para o Azure Functions, talvez seja necessário fornecer um nome de variável de ambiente diferente.

O exemplo a seguir usa builder.ExecutionContext.IsPublishMode para adicionar condicionalmente o sufixo necessário:

builder.AddAzureFunctionsProject<Projects.MyFunctionsProject>("MyFunctionsProject")
    .WithEnvironment("MyBindingConnection" + (builder.ExecutionContext.IsPublishMode ? "__serviceUri" : ""), otherIntegration.Resource.ConnectionStringExpression);

Para obter detalhes sobre os formatos de conexão compatíveis com cada associação e as permissões que esses formatos exigem, consulte as páginas de referência da associação.

Hospedando o aplicativo

Por padrão, quando você publica um projeto do Azure Functions no Azure, ele é implantado nos Aplicativos de Contêiner do Azure.

Durante o período de visualização, os recursos do aplicativo de contêiner não dão suporte ao dimensionamento controlado por eventos. O suporte do Azure Functions não está disponível para aplicativos implantados nesse modo. Se você precisar abrir um tíquete de suporte, selecione o tipo de recurso Aplicativos de contêiner do Azure.

Considerações e melhores práticas

Considere os seguintes pontos ao avaliar a integração do Azure Functions com o .NET Aspire:

• O suporte para a integração está atualmente em versão prévia.

• A configuração de gatilho e associação por meio do .NET Aspire está atualmente limitada a integrações específicas. Para obter detalhes, consulte a configuração de conexão com o .NET Aspire neste artigo.

• O arquivo Program.cs deve usar a versão IHostApplicationBuilder da inicialização da instância do host. IHostApplicationBuilder permite que você chame builder.AddServiceDefaults() para adicionar padrões de serviço do .NET Aspire ao seu projeto do Functions.

• O .NET Aspire usa o OpenTelemetry para monitoramento. Você pode configurar o .NET Aspire para exportar dados para o Azure Monitor por meio do projeto de padrões de serviço.

  Em muitos outros contextos do Azure Functions, você pode incluir a integração direta com o Application Insights registrando o serviço de trabalho. Não recomendamos esse tipo de integração no .NET Aspire. Isso pode levar a erros de runtime com a versão 2.22.0, Microsoft.ApplicationInsights.WorkerServiceembora a versão 2.23.0 resolva esse problema. Quando você estiver usando o .NET Aspire, remova as integrações diretas do Application Insights do seu projeto do Functions.

• Para projetos do Functions inscritos em uma orquestração do .Net Aspire, a maior parte da configuração do aplicativo deve vir do projeto do host de aplicativo do .NET Aspire. Evite definir itens em local.settings.json, exceto pela configuração FUNCTIONS_WORKER_RUNTIME. Se você definir a mesma variável de ambiente no local.settings.json e no .NET Aspire, o sistema usará a versão do .NET Aspire.

• Não configure o emulador de Armazenamento do Azure para conexões em local.settings.json. Muitos modelos de início do Functions incluem o emulador como padrão para AzureWebJobsStorage. No entanto, a configuração do emulador pode solicitar que algumas ferramentas de desenvolvedor iniciem uma versão do emulador que possa entrar em conflito com a versão usada pelo .NET Aspire.