Tutorial: Mulai menggunakan Azure Functions & Visual Studio untuk Mac

Artikel
03/05/2024

Penting

Visual Studio untuk Mac dijadwalkan untuk dihentikan pada 31 Agustus 2024 sesuai dengan Kebijakan Siklus Hidup Modern Microsoft. Meskipun Anda dapat terus bekerja dengan Visual Studio untuk Mac, ada beberapa opsi lain untuk pengembang di Mac seperti versi pratinjau ekstensi C# Dev Kit baru untuk Visual Studio Code.

Pelajari selengkapnya tentang garis waktu dukungan dan alternatif.

Di lab ini, Anda akan mempelajari cara mulai membangun Azure Functions menggunakan Visual Studio untuk Mac. Anda juga akan berintegrasi dengan tabel Azure Storage, yang mewakili salah satu dari banyak jenis pengikatan dan pemicu yang tersedia untuk pengembang Azure Functions.

Tujuan

Membuat dan debug Azure Functions lokal
Mengintegrasikan dengan sumber daya web dan Azure Storage
Mengatur alur kerja yang melibatkan beberapa Azure Functions

Persyaratan

Visual Studio untuk Mac 7.5 atau yang lebih tinggi.
Langganan Azure (tersedia gratis dari https://azure.com/free).

Latihan 1: Membuat proyek Azure Functions

Meluncurkan Visual Studio untuk Mac.
Pilih File > Solusi Baru.
Dari kategori Cloud > General, pilih templat Azure Functions. Anda akan menggunakan C# untuk membuat pustaka kelas .NET Framework yang menghosting Azure Functions. Klik Berikutnya.
Atur Nama Proyek ke "AzureFunctionsLab" dan klik Buat.
Perluas node di Jendela Solusi. Templat proyek default menyertakan referensi NuGet ke berbagai paket Azure WebJobs, serta paket Newtonsoft.Json.

Ada juga tiga file: - host.json untuk menjelaskan opsi konfigurasi global untuk host - local.settings.json untuk mengonfigurasi pengaturan layanan. - Templat proyek juga membuat HttpTrigger default. Demi lab ini, Anda harus menghapus file HttpTrigger.cs dari proyek.

Buka local.settings.json. Secara default memiliki dua pengaturan string koneksi kosong.

Latihan 2: Membuat akun Azure Storage

Masuk ke akun Azure Anda di https://portal.azure.com.
Di bawah bagian Favorit, yang terletak di sebelah kiri layar, pilih Akun Penyimpanan:
Pilih Tambahkan untuk membuat akun penyimpanan baru:
Masukkan nama unik global untuk Nama dan gunakan kembali untuk Grup sumber daya. Anda dapat menyimpan semua item lainnya sebagai default.
Klik Buat. Mungkin perlu beberapa menit untuk membuat akun penyimpanan. Anda akan mendapatkan pemberitahuan setelah berhasil dibuat.
Pilih tombol Buka sumber daya dari pemberitahuan.
Pilih tab Kunci akses.
Salin String Koneksi pertama. String ini digunakan untuk mengintegrasikan Azure Storage dengan fungsi Azure Anda nanti.
Kembali ke Visual Studio untuk Mac dan tempel string koneksi lengkap sebagai pengaturan AzureWebJobsStorage di local.settings.json. Sekarang Anda dapat mereferensikan nama pengaturan dalam atribut untuk fungsi yang memerlukan akses ke sumber dayanya.

Contoh 3: Membuat dan men-debug fungsi Azure

Anda sekarang siap untuk mulai menambahkan beberapa kode. Saat bekerja dengan pustaka kelas .NET Framework Azure Functions ditambahkan sebagai metode statik. Dari Jendela Solusi, klik kanan node proyek AzureFunctions dan pilih Tambahkan > Tambahkan Fungsi:
Dalam dialog Azure Functions Baru, pilih templat webhook Generik. Atur Nama ke Tambah dan klik Oke untuk membuat fungsi Anda:

Di bagian atas file baru, tambahkan direktif penggunaan di bawah:

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

Hapus metode yang ada Run dan tambahkan metode berikut ke kelas sebagai fungsi Azure Anda:

[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;
}

Mari kita telusuri definisi metode sepotong demi sepotong.

Hal pertama yang akan Anda lihat adalah atribut FunctionName yang menandai metode ini sebagai fungsi Azure. Atribut menunjuk nama publik dari fungsi. Nama atribut tidak harus cocok dengan nama metode yang aktual.
Selanjutnya, metode ini ditandai sebagai metode statik publik, yang diperlukan. Anda juga akan melihat bahwa nilai yang dikembalikan adalah int. Kecuali ditentukan lain menggunakan atribut metode, nilai pengembalian yang tidak batal dari fungsi Azure dikembalikan ke klien sebagai teks. Secara default dikembalikan sebagai XML, tetapi dapat diubah menjadi JSON, yang akan Anda lakukan nanti di lab.
Parameter pertama ditandai dengan atribut HttpTrigger, yang menunjukkan bahwa metode ini dipanggil oleh permintaan HTTP. Atribut juga menentukan tingkat otorisasi metode, serta kata kerja yang didukungnya (hanya "GET" dalam kasus ini). Anda mungkin juga secara opsional menentukan Rute yang mengambil alih jalur ke metode dan menawarkan cara untuk mengekstrak variabel secara otomatis dari jalur. Karena Rute di sini null, jalur ke metode ini akan ditetapkan secara default ke /api/Add.
Parameter terakhir untuk metode ini adalah TraceWriter yang dapat digunakan untuk mencatat pesan untuk diagnostik dan kesalahan.
Tetapkan titik henti pada baris pengembalian metode dengan mengeklik di margin baris:
Buat dan jalankan proyek dalam sesi debug dengan menekan F5 atau memilih Jalankan > Mulai Penelusuran kesalahan. Sebagai alternatif, Anda dapat mengeklik tombol Jalankan. Semua opsi ini melakukan tugas yang sama. Sisa lab ini mereferensikan pada F5, tetapi Anda dapat menggunakan metode yang menurut Anda paling nyaman.
Menjalankan proyek secara otomatis akan membuka aplikasi Terminal.
Proyek melewati proses mendeteksi Azure Functions berdasarkan atribut metode dan konvensi file yang dibahas nanti dalam artikel ini. Dalam hal ini, ini mendeteksi satu fungsi Azure dan "menghasilkan" 1 fungsi pekerjaan.
Di bagian bawah pesan startup, host Azure Functions mencetak URL API pemicu HTTP apa pun. Seharusnya hanya ada satu. Salin URL itu dan tempel di tab browser baru.
Titik henti harus segera dipicu. Permintaan web telah dialihkan ke fungsi tersebut dan sekarang dapat didebug. Arahkan mouse ke variabel x untuk melihat nilainya.
Hapus titik henti menggunakan metode yang sama yang digunakan untuk menambahkannya sebelumnya (klik pada margin atau pilih garis dan tekan F9).
Tekan F5 untuk melanjutkan.
Di browser, hasil XML dari metode akan dirender. Seperti yang diharapkan, operasi penambahan hardcode menghasilkan jumlah yang masuk akal. Perhatikan, jika Anda hanya melihat "3" di Safari, buka Preferensi Safari Tingkat Lanjut dan centang kotak centang "Tampilkan menu Kembangkan di bilah menu" dan muat ulang halaman.>>
Di Visual Studio untuk Mac, klik tombol Hentikan untuk mengakhiri sesi debug. Untuk memastikan bahwa perubahan baru diambil, jangan lupa untuk memulai kembali (berhenti dan kemudian menjalankan) sesi penelusuran kesalahan.
Dalam metode Jalankan, ganti definisi x dan y dengan kode berikut. Kode ini mengekstrak nilai dari string kueri URL sehingga operasi penambahan dapat dilakukan secara dinamis berdasarkan parameter yang disediakan.
```
var query = HttpUtility.ParseQueryString(req.RequestUri.Query);

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

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

return x + y;
```
Jalankan aplikasi lagi.
Kembali ke jendela browser dan tambahkan string /?x=2&y=3 ke URL. Seluruh URL sekarang harus http://localhost:7071/api/Add?x=2&y=3. Arahkan ke URL baru.
Kali ini hasilnya harus mencerminkan parameter baru. Jangan ragu untuk menjalankan proyek dengan nilai yang berbeda. Perhatikan bahwa tidak ada pemeriksaan kesalahan, jadi parameter yang tidak valid atau hilang akan menimbulkan kesalahan.
Hentikan sesi penelusuran kesalahan.

Latihan 4: Bekerja dengan function.json

Dalam latihan sebelumnya, disebutkan bahwa Visual Studio untuk Mac "menghasilkan" fungsi pekerjaan untuk fungsi Azure yang ditentukan dalam pustaka. Ini karena Azure Functions tidak benar-benar menggunakan atribut metode saat runtime, melainkan menggunakan konvensi sistem file waktu kompilasi untuk mengonfigurasi di mana dan bagaimana Azure Functions tersedia. Dari Jendela Solusi, klik kanan pada node proyek Anda dan pilih Ungkapkan di Finder.
Navigasikan ke bawah sistem file hingga Anda mencapai bin/Debug/netstandard2.0. Seharusnya ada folder bernama Tambahkan. Folder ini dibuat agar sesuai dengan atribut nama fungsi dalam kode C#. Perluas folder Tambah untuk menampilkan satu file function.json. File ini digunakan oleh runtime untuk menghosting dan mengelola fungsi Azure. Untuk model bahasa lain tanpa dukungan waktu kompilasi (seperti skrip C# atau JavaScript), folder ini harus dibuat dan dipelihara secara manual. Untuk pengembang C#, mereka secara otomatis dihasilkan dari metadata atribut saat dibuat. Klik kanan pada function.json dan pilih untuk membukanya di Visual Studio.
Mengingat langkah-langkah sebelumnya dari tutorial ini, Anda harus memiliki pemahaman dasar tentang atribut C#. Mempertimbangkan hal itu, JSON ini seharusnya terlihat akrab. Namun, ada beberapa item yang tidak tercakup dalam latihan sebelumnya. Misalnya, setiap pengikatan harus memiliki set arahnya. Seperti yang mungkin Anda simpulkan, "in" berarti bahwa parameter tersebut adalah input, sedangkan "out" menunjukkan bahwa parameter tersebut adalah nilai yang dikembalikan (melalui $return ) atau parameter keluar ke metode. Anda juga perlu menentukan scriptFile (relatif terhadap lokasi akhir ini) dan metode entryPoint (publik dan statik) dalam rakitan. Dalam beberapa langkah berikutnya Anda akan menambahkan jalur fungsi kustom menggunakan model ini, jadi salin konten file ini ke clipboard.
Di Jendela Solusi, klik kanan node proyek AzureFunctionsLab dan pilih Tambahkan > Folder Baru. Beri nama folder baru Adder. Secara default, nama folder ini akan menentukan jalur ke API, seperti api/Adder.
Klik kanan folder Adder dan pilih Tambahkan > File Baru.
Pilih kategori Web dan templat File JSON Kosong. Atur Nama ke fungsi dan klik Baru.
Tempelkan konten function.json lainnya (dari langkah 3) untuk menggantikan konten default dari file yang baru dibuat.

Hapus baris berikut dari bagian atas file json:

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

Di akhir pengikatan pertama (setelah baris "nama": "req" ), tambahkan properti berikut. Jangan lupa untuk menyertakan koma pada baris sebelumnya. Properti ini mengganti akar default sehingga sekarang akan mengekstrak parameter int dari jalur dan menempatkannya ke dalam parameter metode yang diberi nama x dan y.
```
"direction": "in",
"route": "Adder/{x:int?}/{y:int?}"
```
Tambahkan pengikatan data lain di bawah yang pertama. Pengikatan ini menangani nilai yang dikembalikan fungsi. Jangan lupa untuk menyertakan koma pada baris sebelumnya:
```
{
"name": "$return",
"type": "http",
"direction": "out"
}
```
Perbarui juga properti entryPoint di bagian bawah file untuk menggunakan metode yang disebut "Add2", seperti yang ditunjukkan di bawah ini. Ini untuk menggambarkan bahwa jalur api/Adder... dapat dipetakan ke metode yang sesuai dengan nama apa pun (Add2 di sini).
```
"entryPoint": "<project-name>.<function-class-name>.Add2"
```

File function.json terakhir Anda akan terlihat seperti json berikut:

{
"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"
}

Satu langkah terakhir yang diperlukan untuk membuat semua ini berfungsi adalah dengan menginstruksikan Visual Studio untuk Mac untuk menyalin file ini ke jalur relatif yang sama di direktori output setiap kali berubah. Dengan file yang dipilih, pilih tab properti dari bilah sebelah kanan, dan untuk Salin ke direktori output pilih Salin jika lebih baru:
Di Add.cs, ganti metode Run (termasuk atribut) dengan metode berikut untuk memenuhi fungsi yang diharapkan. Ini sangat mirip dengan Run, kecuali bahwa ia tidak menggunakan atribut dan memiliki parameter eksplisit untuk x dan y.
```
public static int Add2(
    HttpRequestMessage req,
    int x,
    int y,
    TraceWriter log)
{
    return x + y;
}
```
Tekan F5 untuk membangun dan menjalankan proyek.
Saat build selesai dan platform berputar, sekarang akan menunjukkan bahwa ada rute kedua yang tersedia untuk permintaan yang memetakan ke metode yang baru ditambahkan:
Kembalikan jendela browser dan navigasikan ke http://localhost:7071/api/Adder/3/5.
Kali ini metode bekerja sekali lagi, menarik parameter dari jalur dan menghasilkan jumlah.
Kembali ke Visual Studio untuk Mac dan akhiri sesi debug.

Latihan 5: Bekerja dengan tabel Azure Storage

Seringkali, layanan yang Anda bangun mungkin jauh lebih kompleks daripada apa yang telah kami bangun sejauh ini dan membutuhkan sejumlah besar waktu atau infrastruktur untuk dijalankan. Dalam hal ini, Anda mungkin merasa efektif untuk menerima permintaan yang diantrekan untuk diproses saat sumber daya tersedia, yang didukung oleh Azure Functions. Dalam kasus lain, Anda mungkin ingin menyimpan data secara terpusat. Tabel Azure Storage memungkinkan Anda melakukannya dengan cepat.

Tambahkan kelas berikut ke Add.cs. Itu harus masuk ke dalam namespace layanan, tetapi di luar kelas yang ada.

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

Dalam kelas Tambahkan, tambahkan kode berikut untuk memperkenalkan fungsi lain. Perhatikan bahwa yang satu ini unik sejauh ini karena tidak melibatkan respons HTTP. Baris terakhir mengembalikan TableRow baru yang diisi dengan beberapa informasi penting yang akan memudahkan untuk diambil nanti (PartitionKey dan RowKey), serta parameternya dan jumlah. Kode dalam metode ini juga menggunakan TraceWriter untuk memudahkan mengetahui kapan fungsi tersebut berjalan.
```
[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
    };
}
```
Tekan F5 untuk membangun dan menjalankan proyek.
Di tab browser, navigasikan ke http://localhost:7071/api/Process/4/6. Ini akan memasukkan pesan lain ke dalam antrian, yang pada akhirnya akan menghasilkan baris lain yang ditambahkan ke tabel.
Kembali ke Terminal dan perhatikan permintaan masuk untuk 4 + 6.
Kembali ke browser untuk merefresh permintaan ke URL yang sama. Kali ini Anda akan melihat kesalahan setelah metode Proses. Ini karena kode mencoba menambahkan baris ke tabel Azure Table Storage menggunakan kombinasi tombol partisi dan baris yang sudah ada.

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.
Akhiri sesi penelusuran kesalahan.
Untuk mengurangi kesalahan, tambahkan parameter berikut ke definisi metode tepat sebelum parameter TraceWriter. Parameter ini menginstruksikan platform Azure Functions untuk mencoba mengambil TableRow dari tabel Results di PartitionKey yang telah kami gunakan untuk menyimpan hasil. Namun, beberapa keajaiban nyata mulai dimainkan saat Anda melihat bahwa RowKey sedang dibuat secara dinamis berdasarkan parameter x dan y lainnya untuk hal yang sama metode. Jika baris tersebut sudah ada, maka tableRow akan memilikinya ketika metode dimulai tanpa pekerjaan tambahan yang diperlukan oleh pengembang. Jika baris tidak ada, maka baris tersebut hanya akan menjadi null. Efisiensi semacam ini memungkinkan pengembang untuk fokus pada logika bisnis yang penting dan bukan infrastruktur.
```
[Table("Results", "sums", "{x}_{y}")]
TableRow tableRow,
```
Tambahkan kode berikut ke awal metode. Jika tableRow bukan null, maka kami telah memiliki hasil untuk operasi yang diminta dan dapat segera mengembalikannya. Jika tidak, fungsi berlanjut seperti sebelumnya. Meskipun ini mungkin bukan cara yang paling kuat untuk mengembalikan data, ini menggambarkan titik bahwa Anda dapat mengatur operasi yang sangat canggih di beberapa tingkatan yang dapat diskalakan dengan kode yang sangat sedikit.
```
if (tableRow != null)
{
    log.Info($"{x} + {y} already exists");
    return null;
}
```
Tekan F5 untuk membangun dan menjalankan proyek.
Di tab browser, refresh URL di http://localhost:7071/api/Process/4/6. Karena baris tabel untuk rekaman ini ada, baris tersebut harus segera kembali dan tanpa kesalahan. Karena tidak ada output HTTP, Anda dapat melihat output di Terminal.
Perbarui URL untuk mencerminkan kombinasi yang belum diuji, seperti http://localhost:7071/api/Process/5/7. Perhatikan pesan di Terminal, yang menunjukkan bahwa baris tabel tidak ditemukan (seperti yang diharapkan).
Kembali ke Visual Studio untuk Mac dan akhiri sesi debug.

Ringkasan

Di lab ini, Anda telah mempelajari cara mulai membangun Azure Functions dengan Visual Studio untuk Mac.