Kurz: Začínáme se službou Azure Functions a Visual Studio pro Mac

Článek
03/01/2024

Důležité

Visual Studio pro Mac je naplánováno vyřazení ze dne 31. srpna 2024 v souladu se společností MicrosoftModerní zásady životního cyklu. I když můžete dál pracovat s Visual Studio pro Mac, existuje několik dalších možností pro vývojáře na Macu, jako je verze Preview nového rozšíření C# Dev Kit pro VS Code.

Přečtěte si další informace o časových osách podpory a alternativách.

V tomto cvičení se dozvíte, jak začít sestavovat azure Functions pomocí Visual Studio pro Mac. Integrujete se také s tabulkami Azure Storage, které představují jeden z mnoha druhů vazeb a triggerů dostupných vývojářům Azure Functions.

Cíle

Vytvoření a ladění místních funkcí Azure Functions
Integrace s webovými prostředky a prostředky Azure Storage
Orchestrace pracovního postupu zahrnujícího více funkcí Azure Functions

Požadavky

Visual Studio pro Mac 7,5 nebo vyšší.
Předplatné Azure (dostupné zdarma)https://azure.com/free

Cvičení 1: Vytvoření projektu Azure Functions

Spusťte Visual Studio pro Mac.
Vyberte Soubor > nové řešení.
V kategorii Obecné v cloudu > vyberte šablonu Azure Functions. Pomocí jazyka C# vytvoříte knihovnu tříd .NET, která hostuje Službu Azure Functions. Klikněte na tlačítko Další.
Nastavte název projektu na AzureFunctionsLab a klikněte na Vytvořit.
Rozbalte uzly v okně řešení. Výchozí šablona projektu obsahuje odkazy NuGet na celou řadu balíčků Azure WebJobs a také na balíček Newtonsoft.Json.

Existují také tři soubory: – host.json pro popis globálních možností konfigurace hostitele – local.settings.json pro konfiguraci nastavení služby. – Šablona projektu také vytvoří výchozí httpTrigger. V zájmu tohoto cvičení byste měli odstranit soubor HttpTrigger.cs z projektu.

Otevřete local.settings.json. Ve výchozím nastavení mají dvě prázdná nastavení připojovací řetězec.

Cvičení 2: Vytvoření účtu azure Storage

Přihlaste se ke svému účtu Azure na adrese https://portal.azure.com.
V části Oblíbené na levé straně obrazovky vyberte Účty úložiště:
Vyberte Přidat a vytvořte nový účet úložiště:
Zadejte globálně jedinečný název názvu a znovu ho použijte pro skupinu prostředků. Všechny ostatní položky můžete ponechat jako výchozí.
Klikněte na Vytvořit. Vytvoření účtu úložiště může trvat několik minut. Jakmile se úspěšně vytvoří, dostanete oznámení.
V oznámení vyberte tlačítko Přejít k prostředku.
Vyberte kartu Přístupové klávesy.
Zkopírujte první Připojení ion String. Tento řetězec se používá k pozdější integraci Azure Storage s funkcemi Azure.
Vraťte se do Visual Studio pro Mac a vložte úplný připojovací řetězec jako nastavení AzureWebJobsStorage v local.settings.json. Teď můžete odkazovat na název nastavení v atributech pro funkce, které potřebují přístup k prostředkům.

Příklad 3: Vytvoření a ladění funkce Azure

Teď jste připraveni začít přidávat nějaký kód. Při práci s knihovnou tříd .NET se služba Azure Functions přidá jako statické metody. V okně řešení klikněte pravým tlačítkem na uzel projektu AzureFunctions a vyberte Přidat > funkci:
V dialogovém okně Nové funkce Azure Functions vyberte šablonu Obecného webhooku. Nastavte název na Přidat a kliknutím na ok vytvořte funkci:

V horní části nového souboru přidejte následující direktivy using :

using Microsoft.Azure.WebJobs.Extensions.Http;
using System.Web;
using Microsoft.WindowsAzure.Storage.Table;

Odeberte existující Run metodu a přidejte do třídy následující metodu jako funkci Azure:

[FunctionName("Add")]
public static int Run(
[HttpTrigger(AuthorizationLevel.Function, "get", Route = null)]
HttpRequestMessage req,
TraceWriter log)
{
    int x = 1;
    int y = 2;

    return x + y;
}

Pojďme si projít část definice metody po kusu.

První věc, kterou uvidíte, je atribut FunctionName , který tuto metodu označí jako funkci Azure. Atribut určuje veřejný název funkce. Název atributu se nemusí shodovat se skutečným názvem metody.
Dále se metoda označí jako veřejná statická metoda, která se vyžaduje. Všimněte si také, že vrácená hodnota je int. Pokud neurčíte jinak pomocí atributů metody, vrátí se klientovi jako text jakákoli návratová hodnota funkce Azure, která není void. Ve výchozím nastavení se vrátí jako XML, ale můžete ho změnit na JSON, který provedete později v testovacím prostředí.
První parametr je označen atributem HttpTrigger , který označuje, že tato metoda je vyvolána požadavkem HTTP. Atribut také určuje úroveň autorizace metody a také příkazy, které podporuje (v tomto případě pouze "GET" ). Volitelně můžete také definovat trasu, která přepíše cestu k metodě a nabízí způsob, jak automaticky extrahovat proměnné z cesty. Vzhledem k tomu, route je zde null, cesta k této metodě bude výchozí pro /api/Add.
Posledním parametrem metody je TraceWriter , který lze použít k protokolování zpráv pro diagnostiku a chyby.
Nastavte zarážku na návratovém řádku metody kliknutím na okraj řádku:
Sestavte a spusťte projekt v ladicí relaci stisknutím klávesy F5 nebo výběrem možnosti Spustit ladění>. Můžete také kliknout na tlačítko Spustit . Všechny tyto možnosti provádějí stejnou úlohu. Zbytek tohoto cvičení odkazuje na F5, ale můžete použít metodu, kterou najdete nejpohodlnější.
Spuštění projektu automaticky otevře terminálovou aplikaci.
Projekt prochází procesem zjišťování azure Functions na základě atributů metody a konvence souborů, které jsou popsány dále v tomto článku. V tomto případě zjistí jednu funkci Azure a "vygeneruje" 1 funkci úlohy.
V dolní části spouštěcích zpráv hostitel Azure Functions vytiskne adresy URL všech rozhraní API triggeru HTTP. Měl by tam být jen jeden. Zkopírujte adresu URL a vložte ji na novou kartu prohlížeče.
Zarážka by se měla aktivovat okamžitě. Webový požadavek byl směrován do funkce a nyní je možné ho ladit. Najeďte myší na proměnnou x a zobrazte její hodnotu.
Odeberte zarážku pomocí stejné metody, jako jste ji přidali dříve (klikněte na okraj nebo vyberte čáru a stiskněte klávesu F9).
Pokračujte stisknutím klávesy F5 .
V prohlížeči se vykreslí výsledek XML metody. Podle očekávání vytvoří pevně zakódovaná operace sčítání hodnověrný součet. Poznámka: Pokud se v Safari zobrazí jenom "3", přejděte na Upřesnit předvolby > Safari > a zaškrtněte políčko Zobrazit nabídku Vývoj v řádku nabídek a znovu načtěte stránku.
V Visual Studio pro Mac kliknutím na tlačítko Zastavit ukončete ladicí relaci. Abyste zajistili, že se vyberou nové změny, nezapomeňte restartovat (zastavit a pak spustit) relaci ladění.
V metodě Run nahraďte definice x a y následujícím kódem. Tento kód extrahuje hodnoty z řetězce dotazu adresy URL, aby bylo možné operaci sčítání provádět dynamicky na základě zadaných parametrů.
```
var query = HttpUtility.ParseQueryString(req.RequestUri.Query);

int x = int.Parse(query["x"]);

int y = int.Parse(query["y"]);

return x + y;
```
Aplikaci spusťte.
Vraťte se do okna prohlížeče a připojte řetězec /?x=2&y=3 k adrese URL. Celá adresa URL by teď měla být http://localhost:7071/api/Add?x=2&y=3. Přejděte na novou adresu URL.
Tentokrát by výsledek měl odrážet nové parametry. Nebojte se projekt spustit s různými hodnotami. Všimněte si, že neexistuje žádná kontrola chyb, takže neplatné nebo chybějící parametry způsobí chybu.
Zastavte ladicí relaci.

Cvičení 4: Práce s function.json

V předchozím cvičení bylo zmíněno, že Visual Studio pro Mac "vygenerovala" funkci úlohy pro funkci Azure definovanou v knihovně. Důvodem je, že Azure Functions ve skutečnosti nepoužívá atributy metody za běhu, ale místo toho používá konvenci systému souborů za kompilace ke konfiguraci, kde a jak jsou dostupné funkce Azure Functions. V okně řešení klikněte pravým tlačítkem na uzel projektu a vyberte Zobrazit ve Finderu.
Přejděte do systému souborů, dokud se nedostanete na bin/Debug/netstandard2.0. Měla by existovat složka s názvem Přidat. Tato složka byla vytvořena tak, aby odpovídala atributu názvu funkce v kódu jazyka C#. Rozbalte složku Přidat a zobrazte jeden soubor function.json . Tento soubor používá modul runtime k hostování a správě funkce Azure. U jiných jazykových modelů bez podpory kompilace (například skriptu jazyka C# nebo JavaScriptu) je nutné tyto složky vytvořit a udržovat ručně. Pro vývojáře v jazyce C# se při sestavování automaticky generují z metadat atributů. Klikněte pravým tlačítkem na function.json a výběrem ho otevřete v sadě Visual Studio.
Vzhledem k předchozím krokům tohoto kurzu byste měli mít základní znalosti o atributech jazyka C#. Vzhledem k tomu by tento json měl vypadat dobře. Existuje však několik položek, které nebyly popsány v předchozích cvičeních. Každá vazba musí mít například nastaveno směr. Jak můžete odvodit, "in" znamená, že parametr je vstupní, zatímco "out" označuje, že parametr je návratová hodnota (prostřednictvím $return) nebo výstupní parametr metody. Musíte také zadat scriptFile (vzhledem k tomuto konečnému umístění) a metodu entryPoint (veřejná a statická) v rámci sestavení. V několika dalších krocích přidáte vlastní cestu funkce pomocí tohoto modelu, takže zkopírujte obsah tohoto souboru do schránky.
V okně řešení klikněte pravým tlačítkem na uzel projektu AzureFunctionsLab a vyberte Přidat > novou složku. Pojmenujte novou složku Adder. Ve výchozím nastavení bude název této složky definovat cestu k rozhraní API, například api/Adder.
Klikněte pravým tlačítkem na složku Adder (Přidat nový soubor) a vyberte Add New File (Přidat > nový soubor).
Vyberte kategorii Web a prázdnou šablonu souboru JSON. Nastavte název na funkci a klepněte na tlačítko Nový.
Vložte obsah druhého function.json (z kroku 3) a nahraďte výchozí obsah nově vytvořeného souboru.

Odeberte následující řádky z horní části souboru JSON:

"configurationSource":"attributes",
"generatedBy":"Microsoft.NET.Sdk.Functions-1.0.13",

Na konec první vazby (za řádek "name": "req" přidejte následující vlastnosti. Nezapomeňte na předchozí řádek přidat čárku. Tato vlastnost přepíše výchozí kořenový adresář tak, že nyní extrahuje int parametry z cesty a umístí je do parametrů metody s názvem x a y.
```
"direction": "in",
"route": "Adder/{x:int?}/{y:int?}"
```
Přidejte pod první vazbu. Tato vazba zpracovává návratové hodnoty funkce. Nezapomeňte na předchozí řádek uvést čárku:
```
{
"name": "$return",
"type": "http",
"direction": "out"
}
```
Aktualizujte také vlastnost entryPoint v dolní části souboru tak, aby používala metodu s názvem "Add2", například na obrázku níže. To je ilustrovat , že cesta api/Adder... by mohla mapovat na příslušnou metodu s libovolným názvem (sem Přidat2 ).
```
"entryPoint": "<project-name>.<function-class-name>.Add2"
```

Konečný soubor function.json by měl vypadat jako následující json:

{
"bindings": [
    {
    "type": "httpTrigger",
    "methods": [
        "get"
    ],
    "authLevel": "function",
    "direction": "in",
    "name": "req",
    "route": "Adder/{x:int?}/{y:int?}"
    },
    {
    "name": "$return",
    "type": "http",
    "direction": "out"
    }
],
"disabled": false,
"scriptFile": "../bin/AzureFunctionsProject.dll",
"entryPoint": "AzureFunctionsProject.Add.Add2"
}

Jedním posledním krokem potřebným k provedení této práce je instruovat Visual Studio pro Mac, aby tento soubor při každé změně zkopíroval do stejné relativní cesty ve výstupním adresáři. Při vybraném souboru zvolte na pravém panelu kartu Vlastnosti a v případě příkazu Kopírovat do výstupního adresáře vyberte Kopírovat, pokud je novější:
V Add.cs nahraďte metodu Run (včetně atributu) následující metodou, která splní očekávanou funkci. Je velmi podobný s tím rozdílem Run, že nepoužívá žádné atributy a má explicitní parametry pro x a y.
```
public static int Add2(
    HttpRequestMessage req,
    int x,
    int y,
    TraceWriter log)
{
    return x + y;
}
```
Stisknutím klávesy F5 sestavte a spusťte projekt.
Jakmile se sestavení dokončí a platforma se roztáčí, bude teď značit, že pro požadavky, které se mapují na nově přidanou metodu, je k dispozici druhá trasa:
Vraťte okno prohlížeče a přejděte na http://localhost:7071/api/Adder/3/5adresu .
Tentokrát tato metoda znovu funguje, načítání parametrů z cesty a vytvoření součtu.
Vraťte se do Visual Studio pro Mac a ukončete ladicí relaci.

Cvičení 5: Práce s tabulkami Azure Storage

Služba, kterou sestavíte, může být často mnohem složitější než to, co jsme zatím vytvořili, a k provedení vyžadovat značné množství času nebo infrastruktury. V takovém případě může být efektivní přijímat požadavky, které jsou zařazené do fronty pro zpracování, jakmile budou dostupné prostředky, které služba Azure Functions poskytuje podporu. V jiných případech budete chtít data ukládat centrálně. Tabulky Azure Storage umožňují to rychle.

Do Add.cs přidejte následující třídu. Měl by jít uvnitř oboru názvů, ale mimo existující třídu.

public class TableRow : TableEntity
{
    public int X { get; set; }
    public int Y { get; set; }
    public int Sum { get; set; }
}

Do třídy Add přidejte následující kód, který představí jinou funkci. Všimněte si, že tato hodnota je zatím jedinečná, protože nezahrnuje odpověď HTTP. Poslední řádek vrátí nový TableRow naplněný některými klíčovými informacemi, které později snadno načtou (PartitionKey a RowKey) a také jeho parametry a součet. Kód v rámci metody také používá TraceWriter , aby bylo snazší zjistit, kdy funkce běží.

[FunctionName("Process")]
[return: Table("Results")]
public static TableRow Process(
    [HttpTrigger(AuthorizationLevel.Function, "get",
        Route = "Process/{x:int}/{y:int}")]
    HttpRequestMessage req,
    int x,
    int y,
    TraceWriter log)
{
    log.Info($"Processing {x} + {y}");

    return new TableRow()
    {
        PartitionKey = "sums",
        RowKey = $"{x}_{y}",
        X = x,
        Y = y,
        Sum = x + y
    };
}

Stisknutím klávesy F5 sestavte a spusťte projekt.
Na kartě prohlížeče přejděte na http://localhost:7071/api/Process/4/6. Tím se do fronty vloží další zpráva, která by nakonec měla vést k přidání dalšího řádku do tabulky.
Vraťte se do terminálu a sledujte příchozí požadavek na 4 + 6.
Vraťte se do prohlížeče a aktualizujte požadavek na stejnou adresu URL. Tentokrát se po metodě Process zobrazí chyba. Důvodem je, že se kód pokouší přidat řádek do tabulky Azure Table Storage pomocí kombinace klíčů oddílů a řádků, které už existují.

System.Private.CoreLib: Exception while executing function: Process. Microsoft.Azure.WebJobs.Host: Error while handling parameter $return after function returned:. Microsoft.Azure.WebJobs.Host: The specified entity already exists.
Ukončete ladicí relaci.
Chcete-li tuto chybu zmírnit, přidejte následující parametr do definice metody bezprostředně před TraceWriter parametr. Tento parametr dává platformě Azure Functions pokyn, aby se pokusil načíst TableRow z tabulky Results v partitionKey , který jsme používali k ukládání výsledků. Nicméně, některé skutečné magie přichází do hry, když si všimnete, že RowKey je dynamicky generován na základě ostatních parametrů x a y pro velmi stejnou metodu. Pokud tento řádek již existuje, tableRow ho bude mít, když metoda začíná bez další práce vyžadované vývojářem. Pokud řádek neexistuje, bude mít hodnotu null. Tento druh efektivity umožňuje vývojářům zaměřit se na důležitou obchodní logiku, nikoli na infrastrukturu.
```
[Table("Results", "sums", "{x}_{y}")]
TableRow tableRow,
```
Na začátek metody přidejte následující kód. Pokud parametr tableRow nemá hodnotu null, máme již výsledky požadované operace a můžeme ji okamžitě vrátit. V opačném případě bude funkce pokračovat jako předtím. I když to nemusí být nej robustnější způsob, jak data vrátit, ukazuje to, že můžete orchestrovat neuvěřitelně sofistikované operace napříč několika škálovatelnými vrstvami s velmi malým kódem.
```
if (tableRow != null)
{
    log.Info($"{x} + {y} already exists");
    return null;
}
```
Stisknutím klávesy F5 sestavte a spusťte projekt.
Na kartě prohlížeče aktualizujte adresu URL na adrese http://localhost:7071/api/Process/4/6. Vzhledem k tomu, že řádek tabulky pro tento záznam existuje, měl by se vrátit okamžitě a bez chyby. Vzhledem k tomu, že neexistuje žádný výstup HTTP, můžete výstup zobrazit v terminálu.
Aktualizujte adresu URL tak, aby odrážela kombinaci, která ještě nebyla testována, například http://localhost:7071/api/Process/5/7. Všimněte si zprávy v terminálu, která označuje, že řádek tabulky nebyl nalezen (podle očekávání).
Vraťte se do Visual Studio pro Mac a ukončete ladicí relaci.

Shrnutí

V tomto cvičení jste se naučili, jak začít sestavovat azure Functions pomocí Visual Studio pro Mac.