Kan Azure Functions virkelig det?

24. juni 2022

AZURE FUNCTIONS - Serverless compute har taget skyen med storm. Her vil jeg give et par tips og tricks til Azure Functions, som forhåbentlig kan hjælpe dig til at bruge nogle af de mindre kendte, men fede, muligheder i Azure Functions.

Jeg vil komme ind på, hvordan du opsætter levende dokumentation, hvor dine Azure Functions API'er kan afprøves med OpenAPI-dokumentation, moderne .NET Dependency Injection, .NET konfiguration og hemmelighedsstyring i Azure Functions.

Af Nicolai Skovvart, Managing Architect

Indlægget er til dig, der allerede er bekendt med moderne C#, Azure Functions og Azure. Du behøver ikke arbejde i Visual Studio. Jeg har nemlig sørget for nogle alternative grafiske måder at gøre det samme på, f.eks. Manage NuGet Packages, som nogle måske foretrækker at bruge til de fleste instruktioner.

Kort om Azure Functions

Azure Functions er både en simpel event-baseret programmeringsmodel og en tilhørende hosting-model i Azure.

Hosting-modellen tilbyder blandt andet muligheden for kun at betale for præcist de server-ressourcer, der skal bruges ned til sekundet samt at sikre, at der er nok tilgængelige server-ressourcer klar, når de skal bruges.

Det er egenskaber, der gør Azure Functions fantastisk både til sjældne opgaver som f.eks. periodiske integrationer og til hyper-scale APIer, der til tider kræver voldsom serverkraft.

Jeg vil fokusere på kompileret C#, der bruger in-process modellen af Azure Functions, og ikke den stadig unge og i nogle områder lidt umodne out-of-process model.

OpenAPI-dokumentation

OpenAPI, ofte også kaldet Swagger, er et teknisk format, der specificerer, hvordan et HTTP-baseret API fungerer. Udover at det kan bruges som rå API-dokumentation, giver det også muligheden for at præsentere API'et grafisk blandt andet gennem Swagger UI, og det kan også bruges til at generere både servere og klienter i mange sprog.

Historisk set har der været et par forsøg til at tilbyde OpenAPI-dokumentation til Azure Functions-baserede API'er, men i nyere tid er der endelig kommet en officiel Microsoft NuGet-pakke, der kan bruges til at præsentere et SwaggerUI for dine Azure Functions baserede API'er.

For at begynde at udstille dine API'er er der ganske få ting, der er nødvendige:

1. Installér NuGet-pakken i dit Azure-function projekt. Du kan f.eks. installere den gennem NuGet Package Manager eller kommandoprompts: Install-Package Microsoft.Azure.WebJobs.Extensions.OpenApi / dotnet add package Microsoft.Azure.WebJobs.Extensions.OpenApi

2. Begynd at annotere dine HttpTrigger-baserede API'er med OpenApi* attributter:

using System.Net;
using System.Threading;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Http;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Azure.WebJobs.Extensions.OpenApi.Core.Attributes;
using Microsoft.Azure.WebJobs.Extensions.OpenApi.Core.Enums;
using Microsoft.OpenApi.Models;

namespace StarWarsApi.Functions.StarWarsApi;

public class StarWarsFunctions
{
    [FunctionName(nameof(GetStarWarsPersonNameById))]
    [OpenApiOperation(nameof(GetStarWarsPersonNameById), "StarWars Personer", Summary = "Få navnet for Star Wars karakteren med det angivne ID", Visibility = OpenApiVisibilityType.Important)]
    [OpenApiParameter("id", Type = typeof(int), Required = true, In = ParameterLocation.Path)]
    [OpenApiResponseWithBody(HttpStatusCode.OK, "application/json", typeof(string))]
    public async Task<string> GetStarWarsPersonNameById(
        [HttpTrigger(AuthorizationLevel.Anonymous, "get", Route = "starwars/person/{id:int}")] HttpRequest request,
        int id,
        CancellationToken cancellationToken
    ) => await Task.FromResult("Darth Vader");
}

Det vil resultere i følgende SwaggerUI, der beskriver, hvilke API-endpoints der findes, input- og output-modeller, samt andre API-detaljer, såsom URL og parametre m.m.

Dette UI er fuldt funktionelt og kan afprøves direkte.

Azure Functions OpenAPI Extension-referencer: NuGet, GitHub.

Der er mange flere muligheder, som jeg kan anbefale til brug af OpenAPI - blandet andet at beskrive model-klasser tydeligt samt at komme med konkrete navngivne eksempler (i stedet for at der defaultes til typen f.eks. "string" i stedet for et eksempel som "Han Solo").

Moderne .NET applikationsudvikling med startup-filen

Azure Functions kan laves på mange måder og i mange sprog, f.eks. Python og PowerShell, og kan leveres både som binære pakker eller skrives direkte ind i Azure-webportalen.

Til de mere kontrollerede setups har vi dog lyst til både at sikre den gode udvikleroplevelse samt at understøtte gode udviklingspraksisser. Til dette kan Functions opsættes med mange af de samme gode koncepter fra andre moderne .NET -løsninger, blandt andet dependency injection, der gør koden mere testbart og de gode konfigurationsabstraktioner, der blev introduceret med .NET-core.

Azure Functions kan benytte en startup klasse, der kan bootstrappe resten af function-applikationen med dependencies og konfiguration. Det gør du ved at installere NuGet-pakken Microsoft.Azure.Functions.Extensions f.eks. med Install-Package eller dotnet add.

Efter dette kan en vilkårligt navngivet klasse tilføjes (typisk Startup.cs), der nedarver fra FunctionsStartup, hvortil du før namespace-deklaration tilføjer følgende assembly-attribut [assembly: FunctionsStartup(typeof(Startup))].

Fuldt Startup.cs eksempel:

using System;
using Microsoft.Azure.Functions.Extensions.DependencyInjection;
using StarWarsApi.Functions;

[assembly: FunctionsStartup(typeof(Startup))]
namespace StarWarsApi.Functions;

public class Startup : FunctionsStartup
{
    public override void Configure(IFunctionsHostBuilder builder)
    {
        throw new NotImplementedException();
    }
}

Ovenstående leder dog ikke til specielt interessant opførsel (andet end at din Function-app fejler under opstart på grund af den kastede NotImplementedException). Lad os fikse det!

Dependency Injection

For at benytte dependency injection skal man blot begynde at opsætte afhængighederne i Startup og at tage imod afhængighederne i resten af projektets relevante konstruktører.

Lad os fortsætte med at opsætte en stærkt-typet HttpClient abstraktion der automatisk laver genforsøg ved visse typer (potentielt) kort-varige fejl.

Start med at installere NuGet-pakken Microsoft.Extensions.Http.Polly og opdater derefter Startup.cs til følgende (note: det er ikke hensigtsmæssigt at have alle sine klasser i samme fil på denne måde, men det gør det forhåbentligt lettere at følge blogindlægget):

using System;
using System.Net;
using System.Net.Http;
using System.Threading;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Http;
using Microsoft.Azure.Functions.Extensions.DependencyInjection;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Azure.WebJobs.Extensions.OpenApi.Core.Attributes;
using Microsoft.Azure.WebJobs.Extensions.OpenApi.Core.Enums;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.OpenApi.Models;
using Polly;
using StarWarsApi.Functions;

[assembly: FunctionsStartup(typeof(Startup))]
namespace StarWarsApi.Functions;

public interface IStarWarsApiClient
{
    Task<string> GetPersonNameById(int id, CancellationToken cancellationToken = default);
}

public class StarWarsApiClient : IStarWarsApiClient
{
    private readonly HttpClient _httpClient;

    public StarWarsApiClient(HttpClient httpClient)
    {
        _httpClient = httpClient;
        _httpClient.BaseAddress = new("https://swapi.dev");
    }

    public async Task<string> GetPersonNameById(int id, CancellationToken cancellationToken = default)
    {
        var httpResponse = await _httpClient.GetAsync($"/api/people/{id}/", cancellationToken);
        httpResponse.EnsureSuccessStatusCode();
        var response = await httpResponse.Content.ReadAsAsync<StarWarsPersonResponse>(cancellationToken);
        return response.name;
    }

    private record StarWarsPersonResponse(string name);
}

public class Startup : FunctionsStartup
{
    public override void Configure(IFunctionsHostBuilder builder)
    {
        var configuration = builder.GetContext().Configuration;
        builder.Services
            .AddHttpClient<IStarWarsApiClient, StarWarsApiClient>()
                .AddTransientHttpErrorPolicy(policy =>
                    policy
                        .OrResult(res => res.StatusCode == HttpStatusCode.TooManyRequests)
                        .WaitAndRetryAsync(5, retryNumber =>
                            TimeSpan.FromMilliseconds(Math.Pow(2, retryNumber) * 50 + Random.Shared.Next(1000))
                        )
                );
    }
}

public class StarWarsFunctions // genbrugt fra tidligere, men nu opdateret
{
    private readonly IStarWarsApiClient _starWarsApiClient;

    public StarWarsFunctions(IStarWarsApiClient starWarsApiClient) => _starWarsApiClient = starWarsApiClient;

    [FunctionName(nameof(GetStarWarsPersonNameById))]
    [OpenApiOperation(nameof(GetStarWarsPersonNameById), "StarWars Personer", Summary = "Få navnet for Star Wars karakteren med det angivne ID", Visibility = OpenApiVisibilityType.Important)]
    [OpenApiParameter("id", Type = typeof(int), Required = true, In = ParameterLocation.Path)]
    [OpenApiResponseWithBody(HttpStatusCode.OK, "application/json", typeof(string))]
    public async Task<string> GetStarWarsPersonNameById(
        [HttpTrigger(AuthorizationLevel.Anonymous, "get", Route = "starwars/person/{id:int}")] HttpRequest request,
        int id,
        CancellationToken cancellationToken
    ) => await _starWarsApiClient.GetPersonNameById(id, cancellationToken);
}

Med ovenstående kode kan vi nu kalde en stærkt typet HttpClient (StarWarsApiClient) instantieret intelligent af en HttpClientFactory, der kan kalde det eksterne Star Wars API og hente rigtige karakternavne ud baseret på ID i stedet for vores tidligere hårdkodede svar.

Konfiguration

Applikationer har brug for konfigurationsmuligheder både for at sikre at minimale og hyppige ændringer ikke kræver ny udvikling og release. Men det gælder også, for at samme applikation kan køre i flere forskellige konfigurationer, f.eks. typisk baseret på hvilket kørselsmiljø applikationen kører i udviklingsmiljø kontra produktionsmiljø.

I .NET kan man bruge en stærk og fleksibel konfigurationsmodel, hvor koden, der er afhængig af konfiguration, er afkoblet fra, hvor værdierne kommer fra, og hvor konfigurationskilder kan opsættes i prioriteret rækkefølge.

Grundlæggende konfiguration kan lægges i en application.json-fil, mens miljø-specifik konfiguration lægges i en application.{miljø}.json-fil, og til sidst tilføjes system-miljøvariabler, der i omvendt rækkefølge kan redefinere tidligere værdier. Derudover er der også behov for at kunne håndtere hemmelige konfigurationsværdier. Det kommer jeg nærmere ind på i næste sektion.

I Azure Functions opsætter du konfiguration i Startup.cs filen ved at implementere den anden metode fra FunctionsStartup base-klassen: ConfigureAppConfiguration(IFunctionsConfigurationBuilder builder).

Med ovenstående noter kunne det ligne nedenstående kodeblok. Bemærk at vi definerer kørselsmiljøet med systemmiljøvariablen AZURE_FUNCTIONS_ENVIRONMENT. Navnet er en standard Azure Functions-variabel for kørselsmiljøet. Den bliver hentet ud på denne måde og benytter f.eks. ikke builder.GetContext().EnvironmentName, da det sikrer, at miljønavnet altid fungerer og ikke f.eks. kan overskrives, hvis du enabler debugging features i Azure.

public override void ConfigureAppConfiguration(IFunctionsConfigurationBuilder builder)
{
    var context = builder.GetContext();
    var environmentName = Environment.GetEnvironmentVariable("AZURE_FUNCTIONS_ENVIRONMENT");

    builder.ConfigurationBuilder
        .AddJsonFile(Path.Combine(context.ApplicationRootPath, "appsettings.json"), optional: false)
        .AddJsonFile(Path.Combine(context.ApplicationRootPath, $"appsettings.{environmentName}.json"), optional: true)
        .AddEnvironmentVariables();
}

Et eksempel på hvordan en appsettings.json-fil ser ud kunne være følgende:

{
  "StarWarsApi": {
    "BaseUrl": "https://swapi.dev"
  }
}

Og hvis man havde behov for at overskrive denne specifikke værdi i f.eks. produktion, kunne man tilføje følgende appsettings.Production.json:

{
  "StarWarsApi": {
    "BaseUrl": "https://swapi.prod" // Note: findes ikke
  }
}

Note: Alle denne slags applikationsfiler skal være tilgængelig sammen med applikationen. Dette gøres lettest ved at konfigurere din projekt-fil til altid at inkludere dem:

<Project Sdk="Microsoft.NET.Sdk">
    <!-- Eksisterende indhold -->
    <ItemGroup>
        <None Update="appsettings.json">
            <CopyToOutputDirectory>Always</CopyToOutputDirectory>
        </None>
        <None Update="appsettings.Production.json">
            <CopyToOutputDirectory>Always</CopyToOutputDirectory>
        </None>
    </ItemGroup>
</Project>

For at læse konfigurationsværdierne har man nu to muligheder:

1. I dine klassers constructor kan du kræve en afhængighed til IConfiguration-interfacet og tilgå værdier baseret på JSON-strukturen f.eks. følgende:

public StarWarsApiClient(HttpClient httpClient, IConfiguration configuration)
{
    _httpClient = httpClient;
    _httpClient.BaseAddress = configuration.GetValue("StarWarsApi:BaseUrl", new Uri("https://swapi.dev")); // sidste argument er en default-værdi, hvis ikke der allerede findes en værdi fra konfigurationen
}

2. Eller endnu bedre binde din konfiguration til et stærkt-typet objekt, der matcher en sektion i din JSON-struktur, og benytte denne:

public record StarWarsApiSettings
{
    public Uri BaseUrl { get; set; } = new("https://swapi.dev");
}

// Opdater Configure-metoden i Startup
public override void Configure(IFunctionsHostBuilder builder)
{
    var configuration = builder.GetContext().Configuration; // <-- ny
    builder.Services
        .Configure<StarWarsApiSettings>(configuration.GetSection("StarWarsApi")) // <-- ny
        .AddHttpClient<IStarWarsApiClient, StarWarsApiClient>()
            .AddTransientHttpErrorPolicy(policy =>
                policy
                    .OrResult(res => res.StatusCode == HttpStatusCode.TooManyRequests)
                    .WaitAndRetryAsync(5, retryNumber =>
                        TimeSpan.FromMilliseconds(Math.Pow(2, retryNumber) * 50 + Random.Shared.Next(1000))
                    )
        );
}

// Opdater StarWarsApiClient-konstruktøren
public StarWarsApiClient(HttpClient httpClient, IOptions<StarWarsApiSettings> starWarsApiSettings)
{
    _httpClient = httpClient;
    _httpClient.BaseAddress = starWarsApiSettings.Value.BaseUrl;
}

Når vi nu kører applikationen som i produktionsmiljøet f.eks. ved at tilføje en Properties\launchSettings.json-fil med følgende indhold:

{
  "profiles": {
    "StarWarsApi.Functions": {
      "commandName": "Project",
      "environmentVariables": {
        "AZURE_FUNCTIONS_ENVIRONMENT": "Production"
      }
    }
  }
}

så får vi nu den aktuelle konfigurationsværdi:

Hemmelighedsstyring

Det eksterne Star Wars API, som vi benytter, kan kaldes direkte, men de fleste eksterne afhængigheder kræver, at man identificerer sig selv med en eller flere hemmelige værdier. Vi kan smide dem ind som al anden konfiguration, men det vil resultere i, at alle der har adgang til konfigurationen, f.eks. gennem versionskontrol eller Azure-portalen, også får adgang til hemmelighederne, noget der langt fra er ideelt.

Du kan evt. læse mere om problematikken i min kollega Esbens blogindlæg om nøglerulning.

Hvad vi har brug for er en mekanisme som Azure KeyVault, hvor hemmeligheder kan opbevares og styres sikkert. Det vil dog også kræve, at forskellige udviklere skal gives adgang, og at de kan forbinde til Key Vaulten, hvilket gør, at det kan være praktisk at have et sikkert alternativ til lokal udvikling. Det findes der heldigvis allerede i form af User Secrets!

For at tilføje hemmelige konfigurationsværdier fra en Key Vault og bruge User Secrets lokalt skal der heldigvis kun laves mindre ændringer.

1. Installer NuGet-pakken Azure.Extensions.AspNetCore.Configuration.Secrets (og Azure.Identity hvis du ikke allerede har den installeret) for Key Vault adgang med Azure Managed Identity. Opdater ConfigureAppConfiguration-metoden i Startup.cs til at bygge en midlertidig konfiguration, der ser efter, om vi ønsker at bruge en Key Vault. Hvis det er tilfældet, tilføjer vi en Key Vault reference, der benytter DefaultAzureCredentials (der bl.a. inkluderer Azure Managed Identity) til at tilgå hemmelighederne.

public override void ConfigureAppConfiguration(IFunctionsConfigurationBuilder builder)
{
    var context = builder.GetContext();
    var environmentName = Environment.GetEnvironmentVariable("AZURE_FUNCTIONS_ENVIRONMENT");

    var configBuilder = builder.ConfigurationBuilder
        .AddJsonFile(Path.Combine(context.ApplicationRootPath, "appsettings.json"), optional: false)
        .AddJsonFile(Path.Combine(context.ApplicationRootPath, $"appsettings.{environmentName}.json"), optional: true)
        .AddEnvironmentVariables();

    // nyt herunder
    var temporaryConfig = configBuilder.Build();

    if (!temporaryConfig.GetValue("KeyVault:UseKeyVault", true)) return;
    var keyVaultUrl = temporaryConfig.GetValue<Uri>("KeyVault:Url");
    configBuilder.AddAzureKeyVault(keyVaultUrl, new DefaultAzureCredential());
}

2. Installer NuGet-pakken Microsoft.Extensions.Configuration.UserSecrets og kør dotnet user-secrets init for at få et lokalt udvikler alternativ til Key Vault-hemmeligheder.

Opdater Startup.cs' ConfigureAppConfiguration til også valgfrit at tilføje User Secrets baseret på en fil der ligger væk fra resten af applikationskoden (og versionskontrol).

public override void ConfigureAppConfiguration(IFunctionsConfigurationBuilder builder)
{
    var context = builder.GetContext();
    var environmentName = Environment.GetEnvironmentVariable("AZURE_FUNCTIONS_ENVIRONMENT");

    var configBuilder = builder.ConfigurationBuilder
        .AddJsonFile(Path.Combine(context.ApplicationRootPath, "appsettings.json"), optional: false)
        .AddJsonFile(Path.Combine(context.ApplicationRootPath, $"appsettings.{environmentName}.json"), optional: true)
        .AddEnvironmentVariables()
        .AddUserSecrets<Startup>(true); // <-- ny

    var temporaryConfig = configBuilder.Build();

    if (!temporaryConfig.GetValue("KeyVault:UseKeyVault", true)) return;
    var keyVaultUrl = temporaryConfig.GetValue<Uri>("KeyVault:Url");
    configBuilder.AddAzureKeyVault(keyVaultUrl, new DefaultAzureCredential());
}

3. Tilføj den refererede key vault konfiguration og en placeholder for en hemmelig værdi til appsettings-filerne. appsettings.json:

{
  "KeyVault": {
    "UseKeyVault": true,
    "Url": null // overskriv i appsettings.{miljø}.json
  },
  "StarWarsApi": {
    "BaseUrl": "https://swapi.dev",
    "ImaginarySecretApiKey": null // overskriv i key vault / user secrets
  }
}

appsettings.Production.json:

{
  "KeyVault": {
    "Url": "https://produktion-mit-starwarsapi.vault.azure.net/"
  },
  "StarWarsApi": {
    "BaseUrl": "https://swapi.prod" // Note: findes ikke
  }
}

4. Slå Key Vault brug fra lokalt. Dette gøres bedst ved at sætte værdien i "Values"-sektionen af local.settings.json (bemærk at denne eksplicit kræver "sti"-formatet og ikke supporterer JSON strukturer).

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "FUNCTIONS_WORKER_RUNTIME": "dotnet",
    "KeyVault:UseKeyVault": false
  }
}

5. Tilføj din hemmelighed lokalt til User Secrets: dotnet user-secrets set "StarWarsApi:ImaginarySecretApiKey" "secret-123".

Efter disse trin vil hemmeligheder kunne tilgås på lige fod med al anden konfiguration men baseret på forskellige konfigurationskilder alt efter, hvor applikationen kører henne. I Azure vil det dog yderligere kræve, at applikationen har fået opsat en Managed Identiity, at denne identitet har fået lov til at liste og læse hemmeligheder fra Key Vaulten (der også skal eksistere), og at hemmeligheden er opsat i et Key Vault kompatibelt format (StarWarsApi--ImaginarySecretApiKey i stedet for StarWarsApi:ImaginarySecretApiKey). Og det konkluderer tips og tricks for denne gang! Al den refererede kode kan findes i en lidt mere struktureret opsætning på GitHub.

Om Nicolai Skovvart

Nicolai er Managing Architect og har været en del af Immeo siden 2015. Han har en masse erfaring med at etablere cloud baserede løsninger og integrationer i Azure.

Han både designer og koder løsninger og elsker nye tekniske udfordringer. Nicolai er særlig glad for at lave fede løsninger, der måske er baseret på Azure Functions? ;)

Han er desuden party animal of the year 2015-2017, Svelte-evangelist og får regelmæssigt Immeos marketingafdeling til at græde af grin (nogle gange med vilje!).

M: nsk@immeo.dk | T: +45 2222 0258