Usługa Azure Functions z aspirem

Aspire to specyficzny stos, który upraszcza rozwój aplikacji rozproszonych w chmurze. Integracja aplikacji Aspire z usługą Azure Functions umożliwia tworzenie, debugowanie i organizowanie projektu platformy .NET usługi Azure Functions w ramach hosta aplikacji Aspire.

Wymagania wstępne

Skonfiguruj środowisko programistyczne na potrzeby korzystania z usługi Azure Functions z aplikacją Aspire:

• Zainstaluj wymagania wstępne Aspire.
  • Pełna obsługa integracji usługi Azure Functions wymaga aplikacji Aspire 13.1 lub nowszej. Aspire 13.0 zawiera również wersję zapoznawczą Aspire.Hosting.Azure.Functions, która działa jako kandydat do wydania z obsługą "go-live".
• Zainstaluj narzędzia Azure Functions Core Tools.

Jeśli używasz programu Visual Studio, zaktualizuj program do wersji 17.12 lub nowszej. Musisz również mieć najnowszą wersję narzędzi usługi Azure Functions dla programu Visual Studio. Aby sprawdzić dostępność aktualizacji:

1. Przejdź do .
2. W obszarze Projekty i rozwiązania wybierz pozycję Azure Functions.
3. Wybierz pozycję Sprawdź dostępność aktualizacji i zainstaluj aktualizacje zgodnie z monitem.

Struktura rozwiązania

Rozwiązanie korzystające z usług Azure Functions i Aspire ma wiele projektów, w tym projekt hosta aplikacji i co najmniej jeden projekt usługi Functions.

Projekt hosta aplikacji jest punktem wejścia dla aplikacji. Organizuje ona konfigurację składników aplikacji, w tym projekt usługi Functions.

Rozwiązanie zwykle zawiera również projekt ustawień domyślnych usługi. Ten projekt udostępnia zestaw domyślnych usług i konfiguracji, które mają być używane w projektach w aplikacji.

Projekt hosta aplikacji

Aby pomyślnie skonfigurować integrację, upewnij się, że projekt hosta aplikacji spełnia następujące wymagania:

• Projekt hosta aplikacji musi odwoływać się do aplikacji Aspire.Hosting.Azure.Functions. Ten pakiet definiuje niezbędną logikę integracji.
• Projekt hosta aplikacji musi mieć referencję do projektu dla każdego projektu Functions, który ma zostać uwzględniony w orkiestracji.
• W pliku hosta AppHost.cs aplikacji należy uwzględnić projekt poprzez wywołanie AddAzureFunctionsProject<TProject>() na wystąpieniu IDistributedApplicationBuilder. Zamiast korzystać z metody AddProject<TProject>(), której używasz dla innych typów projektów w aplikacji Aspire, stosujesz tę metodę. Jeśli używasz AddProject<TProject>(), projekt Functions nie może uruchomić się poprawnie.

W poniższym przykładzie przedstawiono minimalny AppHost.cs plik dla projektu hosta aplikacji:

var builder = DistributedApplication.CreateBuilder(args);

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

builder.Build().Run();

Projekt usługi Azure Functions

Aby pomyślnie skonfigurować integrację, upewnij się, że projekt usługi Azure Functions spełnia następujące wymagania:

• Projekt usługi Functions musi odwoływać się do wersji 2.x zestawu Microsoft.Azure.Functions.Worker i Microsoft.Azure.Functions.Worker.Sdk. Należy również zaktualizować odwołania Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore do wersji 2.x.

• Plik Program.cs musi używać wersji IHostApplicationBuilderrozruchu instancji hosta. To wymaganie oznacza, że należy użyć polecenia FunctionsApplication.CreateBuilder(args).

• Jeśli twoje rozwiązanie zawiera projekt domyślny usługi, upewnij się, że projekt usługi Functions jest skonfigurowany do korzystania z niego:

  • Projekt Functions powinien zawierać odwołanie do projektu domyślnych ustawień serwisu.
  • Przed skompilowaniem IHostApplicationBuilder w Program.cs uwzględnij wywołanie builder.AddServiceDefaults().

W poniższym przykładzie pokazano minimalny plik Program.cs dla projektu Functions używanego w Aspire.

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

var builder = FunctionsApplication.CreateBuilder(args);

builder.AddServiceDefaults();

builder.ConfigureFunctionsWebApplication();

builder.Build().Run();

Ten przykład nie zawiera domyślnej konfiguracji usługi Application Insights, która jest wyświetlana w wielu innych Program.cs przykładach i w szablonach usługi Azure Functions. Zamiast tego konfigurujesz integrację OpenTelemetry w Aspire, wywołując metodę builder.AddServiceDefaults.

Aby jak najlepiej wykorzystać integrację, należy wziąć pod uwagę następujące wytyczne:

• Nie uwzględniaj żadnych bezpośrednich integracji usługi Application Insights w projekcie usługi Functions. Monitorowanie w Aspire jest obsługiwane za pośrednictwem OpenTelemetry. Możesz skonfigurować Aspire do eksportowania danych do Azure Monitor poprzez projekt domyślnych ustawień usługi.
• Nie należy definiować niestandardowych ustawień aplikacji w local.settings.json pliku projektu usługi Functions. Jedynym ustawieniem, które powinno znajdować się w local.settings.json, jest "FUNCTIONS_WORKER_RUNTIME": "dotnet-isolated". Ustaw wszystkie inne konfiguracje aplikacji za pomocą projektu hosta aplikacji.

Konfiguracja połączenia z aplikacją Aspire

Projekt hosta aplikacji definiuje zasoby i ułatwia tworzenie połączeń między nimi przy użyciu kodu. W tej sekcji przedstawiono sposób konfigurowania i dostosowywania połączeń używanych przez projekt usługi Azure Functions.

Aspire zawiera domyślne uprawnienia do połączeń, które mogą pomóc w rozpoczęciu pracy. Jednak te uprawnienia mogą nie być odpowiednie lub wystarczające dla aplikacji.

W przypadku scenariuszy korzystających z kontroli dostępu opartej na rolach (RBAC) platformy Azure można dostosować uprawnienia, wywołując metodę WithRoleAssignments() w zasobie projektu. Po wywołaniu WithRoleAssignments() wszystkie domyślne przypisania ról zostaną usunięte i należy jawnie zdefiniować wszystkie przypisania ról, które chcesz. Jeśli hostujesz aplikację w usłudze Azure Container Apps, użycie WithRoleAssignments() również wymaga wywołania AddAzureContainerAppEnvironment() na DistributedApplicationBuilder.

Pamięć hosta dla Azure Functions

Usługa Azure Functions wymaga połączenia magazynu hosta (AzureWebJobsStorage) dla kilku podstawowych zachowań. Po wywołaniu AddAzureFunctionsProject<TProject>() w projekcie hosta aplikacji połączenie jest tworzone domyślnie i udostępniane projektowi Functions. To domyślne połączenie używa emulatora usługi Azure Storage do uruchamiania programowania lokalnego i automatycznie aprowizuje konto magazynu podczas wdrażania. Aby uzyskać większą kontrolę, możesz zastąpić to połączenie, wywołując .WithHostStorage() zasób projektu Functions.

Domyślne uprawnienia, które Aspire ustawia dla połączenia magazynu hosta, zależą od tego, czy wywołujesz WithHostStorage(), czy nie. Dodanie WithHostStorage() usuwa przypisanie uczestnika konta magazynu. Aspire ustawia domyślne uprawnienia dla połączenia pamięci masowej hosta w poniższej tabeli.

W poniższym przykładzie przedstawiono minimalny AppHost.cs plik dla projektu hostingu aplikacji, który zastępuje przechowywanie hosta i określa przypisanie ról.

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();

Wyzwalanie i wiązanie połączeń

Mechanizmy wyzwalające i powiązania odwołują się do połączeń według ich nazw. Następujące integracje Aspire umożliwiają te połączenia poprzez wywołanie zasobu projektu WithReference():

W poniższym przykładzie przedstawiono minimalny plik AppHost.cs dla projektu hosta aplikacji, który konfiguruje wyzwalanie kolejki. W tym przykładzie odpowiedni wyzwalacz kolejki ma właściwość Connection ustawioną na MyQueueTriggerConnection, więc wywołanie WithReference() określa nazwę.

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();

W przypadku innych integracji wywołania do WithReference ustawiają konfigurację w inny sposób. Udostępniają konfigurację dla integracji klienta Aspire, ale nie dla wyzwalaczy i powiązań. W przypadku tych integracji wywołaj metodę WithEnvironment() , aby przekazać informacje o połączeniu wyzwalacza lub powiązania w celu rozwiązania problemu.

W poniższym przykładzie pokazano, jak ustawić zmienną środowiskową MyBindingConnection dla zasobu, który uwidacznia wyrażenie parametrów połączenia:

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

Jeśli chcesz, aby zarówno integracje klientów Aspire, jak i system wyzwalaczy oraz powiązań używać połączenia, możesz skonfigurować zarówno WithReference(), jak i WithEnvironment().

W przypadku niektórych zasobów struktura połączenia może się różnić w przypadku uruchamiania go lokalnie i podczas publikowania go na platformie Azure. W poprzednim przykładzie otherIntegration może to być zasób, który działa jako emulator, więc ConnectionStringExpression zwraca parametry połączenia emulatora. Jednak po opublikowaniu zasobu Aspire może ustanowić połączenie oparte na tożsamości i ConnectionStringExpression zwróci identyfikator URI usługi. W takim przypadku, aby skonfigurować połączenia oparte na tożsamości dla usługi Azure Functions, może być konieczne podanie innej nazwy zmiennej środowiskowej.

W poniższym przykładzie użyto builder.ExecutionContext.IsPublishMode do warunkowego dodania niezbędnego sufiksu.

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

Aby uzyskać szczegółowe informacje na temat formatów połączeń, które obsługuje każde powiązanie, oraz uprawnienia wymagane przez te formaty, zapoznaj się ze stronami referencyjnymi powiązania.

Hostowanie aplikacji

Aplikacja Aspire obsługuje dwa różne sposoby hostowania projektu usługi Functions na platformie Azure:

• Publikowanie jako aplikacja kontenera (ustawienie domyślne)
• Opublikuj jako aplikację funkcji używając integracji z usługą App Service w wersji zapoznawczej

W obu przypadkach projekt jest wdrażany jako kontener. Aspire zajmuje się tworzeniem obrazu kontenera i wypychaniem go do Azure Container Registry.

Publikuj jako aplikacja kontenerowa

Domyślnie podczas publikowania projektu Aspire na platformie Azure jest on wdrażany w usłudze Azure Container Apps. System konfiguruje reguły skalowania dla projektu usługi Functions przy użyciu usługi KEDA. W przypadku korzystania z usługi Azure Container Apps wymagana jest dodatkowa konfiguracja kluczy funkcji. Aby uzyskać więcej informacji, zobacz Klucze dostępu w usłudze Azure Container Apps .

Klucze dostępu w usłudze Azure Container Apps

Kilka scenariuszy usługi Azure Functions używa kluczy dostępu, aby zapewnić podstawowe środki zaradcze przed niepożądanym dostępem. Na przykład funkcje wyzwalacza HTTP domyślnie wymagają wywołania klucza dostępu, chociaż to wymaganie można wyłączyć przy użyciu AuthLevel właściwości . Zobacz Praca z kluczami dostępu w usłudze Azure Functions, aby zapoznać się ze scenariuszami, które mogą wymagać klucza.

Podczas wdrażania projektu usługi Functions przy użyciu aplikacji Aspirujących do usługi Azure Container Apps system nie tworzy automatycznie kluczy dostępu usługi Functions ani nie zarządza nimi. Jeśli musisz używać kluczy dostępu, możesz zarządzać nimi w ramach konfiguracji hosta aplikacji. W tej sekcji pokazano, jak utworzyć metodę rozszerzenia, którą można wywołać z pliku hosta aplikacji Program.cs w celu utworzenia i zarządzania kluczami dostępu. To podejście używa usługi Azure Key Vault do przechowywania kluczy i podpinania ich w aplikacji kontenerowej jako sekrety.

Te kroki wymagają wersji Bicep lub nowszej 0.38.3 . Wersję Bicep można sprawdzić, uruchamiając polecenie bicep --version w wierszu polecenia. Jeśli masz zainstalowany interfejs wiersza polecenia platformy Azure, możesz użyć az bicep upgrade polecenia , aby szybko zaktualizować aplikację Bicep do najnowszej wersji.

Dodaj następujące pakiety NuGet do projektu hosta aplikacji:

• Aspire.Hosting.Azure.AppContainers
• Aspire.Hosting.Azure.KeyVault

Utwórz nową klasę w projekcie hosta aplikacji i dołącz następujący kod:

using Aspire.Hosting.Azure;
using Azure.Provisioning.AppContainers;

namespace Aspire.Hosting;

internal static class Extensions
{
    private record SecretMapping(string OriginalName, IAzureKeyVaultSecretReference Reference);

    public static IResourceBuilder<T> PublishWithContainerAppSecrets<T>(
        this IResourceBuilder<T> builder,
        IResourceBuilder<AzureKeyVaultResource>? keyVault = null,
        string[]? hostKeyNames = null,
        string[]? systemKeyExtensionNames = null)
        where T : AzureFunctionsProjectResource
    {
        if (!builder.ApplicationBuilder.ExecutionContext.IsPublishMode)
        {
            return builder;
        }

        keyVault ??= builder.ApplicationBuilder.AddAzureKeyVault("functions-keys");

        var hostKeysToAdd = (hostKeyNames ?? []).Append("default").Select(k => $"host-function-{k}");
        var systemKeysToAdd = systemKeyExtensionNames?.Select(k => $"host-systemKey-{k}_extension") ?? [];
        var secrets = hostKeysToAdd.Union(systemKeysToAdd)
            .Select(secretName => new SecretMapping(
                secretName,
                CreateSecretIfNotExists(builder.ApplicationBuilder, keyVault, secretName.Replace("_", "-"))
            )).ToList();

        return builder
            .WithReference(keyVault)
            .WithEnvironment("AzureWebJobsSecretStorageType", "ContainerApps")
            .PublishAsAzureContainerApp((infra, app) => ConfigureFunctionsContainerApp(infra, app, builder.Resource, secrets));
    }

    private static void ConfigureFunctionsContainerApp(
        AzureResourceInfrastructure infrastructure, 
        ContainerApp containerApp, 
        IResource resource, 
        List<SecretMapping> secrets)
    {
        const string volumeName = "functions-keys";
        const string mountPath = "/run/secrets/functions-keys";

        var appIdentityAnnotation = resource.Annotations.OfType<AppIdentityAnnotation>().Last();
        var containerAppIdentityId = appIdentityAnnotation.IdentityResource.Id.AsProvisioningParameter(infrastructure);

        var containerAppSecretsVolume = new ContainerAppVolume
        {
            Name = volumeName,
            StorageType = ContainerAppStorageType.Secret
        };

        foreach (var mapping in secrets)
        {
            var secret = mapping.Reference.AsKeyVaultSecret(infrastructure);

            containerApp.Configuration.Secrets.Add(new ContainerAppWritableSecret()
            {
                Name = mapping.Reference.SecretName.ToLowerInvariant(),
                KeyVaultUri = secret.Properties.SecretUri,
                Identity = containerAppIdentityId
            });

            containerAppSecretsVolume.Secrets.Add(new SecretVolumeItem
            {
                Path = mapping.OriginalName.Replace("-", "."),
                SecretRef = mapping.Reference.SecretName.ToLowerInvariant()
            });
        }

        containerApp.Template.Containers[0].Value!.VolumeMounts.Add(new ContainerAppVolumeMount
        {
            VolumeName = volumeName,
            MountPath = mountPath
        });
        containerApp.Template.Volumes.Add(containerAppSecretsVolume);
    }

    public static IAzureKeyVaultSecretReference CreateSecretIfNotExists(
        IDistributedApplicationBuilder builder,
        IResourceBuilder<AzureKeyVaultResource> keyVault,
        string secretName)
    {
        var secretParameter = ParameterResourceBuilderExtensions.CreateDefaultPasswordParameter(builder, $"param-{secretName}", special: false);
        builder.AddBicepTemplateString($"key-vault-key-{secretName}", """
                param location string = resourceGroup().location
                param keyVaultName string
                param secretName string
                @secure()
                param secretValue string    

                // Reference the existing Key Vault
                resource keyVault 'Microsoft.KeyVault/vaults@2023-07-01' existing = {
                  name: keyVaultName
                }

                // Deploy the secret only if it does not already exist
                @onlyIfNotExists()
                resource newSecret 'Microsoft.KeyVault/vaults/secrets@2023-07-01' = {
                  parent: keyVault
                  name: secretName
                  properties: {
                      value: secretValue
                  }
                }
                """)
            .WithParameter("keyVaultName", keyVault.GetOutput("name"))
            .WithParameter("secretName", secretName)
            .WithParameter("secretValue", secretParameter);

        return keyVault.GetSecret(secretName);
    }
}

Następnie możesz użyć tej metody w pliku hosta Program.cs aplikacji:

builder.AddAzureFunctionsProject<Projects.MyFunctionsProject>("MyFunctionsProject")
       .WithHostStorage(storage)
       .WithExternalHttpEndpoints()
       .PublishWithContainerAppSecrets(systemKeyExtensionNames: ["mcp"]);

W tym przykładzie użyto domyślnego magazynu kluczy utworzonego przez metodę rozszerzenia. Skutkuje to kluczem domyślnym i kluczem systemowym dla rozszerzenia Protokołu kontekstu modelu.

Aby używać tych kluczy od klientów, należy pobrać je z magazynu kluczy.

Opublikuj jako aplikacja funkcji

Możesz skonfigurować Aspire do wdrożenia w aplikacji funkcji Azure przy użyciu integracji Aspire z usługą Azure App Service. Ponieważ Aspire publikuje projekt usługi Functions jako kontener, plan hostingu aplikacji funkcji musi obsługiwać wdrażanie konteneryzowanych aplikacji.

Aby opublikować projekt Aplikacji Aspire Functions jako aplikację funkcji, wykonaj następujące kroki:

1. Dodaj odwołanie do pakietu NuGet Aspire.Hosting.Azure.AppService w projekcie hosta aplikacji.
2. W pliku wywołaj AppHost.csAddAzureAppServiceEnvironment()IDistributedApplicationBuilder wystąpienie, aby utworzyć plan usługi App Service. Należy pamiętać, że pomimo nazwy nie zapewnia to zasobu Środowiska Usług Aplikacyjnych (App Service Environment).
3. W zasobie projektu Functions wywołaj metodę .WithExternalHttpEndpoints(). Jest to wymagane do wdrożenia z integracją Aspire Azure App Service.
4. W zasobie projektu funkcji wywołaj metodę .PublishAsAzureAppServiceWebsite((infra, app) => app.Kind = "functionapp,linux"), aby opublikować ten projekt w ramach planu.

W poniższym przykładzie pokazano minimalny AppHost.cs plik dla projektu hosta aplikacji, który publikuje projekt Functions jako aplikację funkcji.

var builder = DistributedApplication.CreateBuilder(args);
builder.AddAzureAppServiceEnvironment("functions-env");
builder.AddAzureFunctionsProject<Projects.MyFunctionsProject>("MyFunctionsProject")
    .WithExternalHttpEndpoints()
    .PublishAsAzureAppServiceWebsite((infra, app) => app.Kind = "functionapp,linux");

Ta konfiguracja tworzy plan Premium V3. W przypadku korzystania z dedykowanego planu usługi App Service SKU, skalowanie nie bazuje na zdarzeniach. Zamiast tego skalowanie jest zarządzane za pomocą ustawień planu usługi App Service.

Zagadnienia i najlepsze rozwiązania

Podczas oceniania integracji usługi Azure Functions z aplikacją Aspire należy wziąć pod uwagę następujące kwestie:

• Konfiguracja wyzwalacza i wiązania za pośrednictwem platformy Aspire jest obecnie ograniczona do określonych integracji. Aby uzyskać szczegółowe informacje, zobacz Konfiguracja połączenia z aplikacją Aspire w tym artykule.

• Plik projektu Program.cs funkcji powinien używać IHostApplicationBuilder wersji uruchamiania wystąpienia hosta. IHostApplicationBuilder Umożliwia wywołanie funkcji builder.AddServiceDefaults() w celu dodania domyślnych ustawień usługi Aspire do projektu usługi Functions.

• Aspire używa OpenTelemetry do monitorowania. Możesz skonfigurować Aspire do eksportowania danych do Azure Monitor poprzez projekt domyślnych ustawień usługi.

  W wielu innych kontekstach usługi Azure Functions można uwzględnić bezpośrednią integrację z usługą Application Insights, rejestrując usługę roboczą. Nie zalecamy takiej integracji w aplikacji Aspire. Może to prowadzić do błędów środowiska uruchomieniowego w wersji 2.22.0 programu Microsoft.ApplicationInsights.WorkerService, chociaż wersja 2.23.0 rozwiązuje ten problem. Kiedy korzystasz z Aspire, usuń wszystkie bezpośrednie integracje Application Insights z projektu Functions.

• W przypadku projektów Functions wprowadzonych do orkiestracji Aspire, większość konfiguracji aplikacji powinna pochodzić z projektu hostującego aplikacje Aspire. Unikaj ustawiania rzeczy w local.settings.json, innych niż ustawienie FUNCTIONS_WORKER_RUNTIME. Jeśli ustawisz tę samą zmienną środowiskową w local.settings.json i Aspire, system skorzysta z wersji Aspire.

• Nie konfiguruj emulatora usługi Azure Storage dla jakichkolwiek połączeń w local.settings.json. Wiele szablonów startowych usługi Functions zawiera emulator jako domyślną opcję dla AzureWebJobsStorage. Niemniej jednak konfiguracja emulatora może skłaniać do uruchomienia wersji emulatora, która może konfliktować z wersją używaną przez Aspire.