Bagikan melalui

Panduan untuk SDK PowerShell Durable Functions mandiri

  • Artikel

PowerShell SDK Durable Functions (DF) sekarang tersedia, dalam pratinjau, sebagai paket mandiri di Galeri PowerShell: AzureFunctions.PowerShell.Durable.SDK. Setelah paket SDK ini adalah GA, ini akan menjadi sarana yang direkomendasikan untuk menulis aplikasi Durable Functions dengan PowerShell. Dalam artikel ini, kami menjelaskan manfaat perubahan ini, dan perubahan apa yang dapat Anda harapkan saat mengadopsi paket baru ini.

Catatan

Paket ini sedang dalam pratinjau.

Motivasi di balik SDK mandiri

DF SDK sebelumnya dibangun ke dalam pekerja bahasa PowerShell. Pendekatan ini datang dengan manfaat bahwa aplikasi Durable Functions dapat ditulis di luar kotak untuk pengguna PowerShell Azure Functions. Namun, itu juga datang dengan berbagai kekurangan:

  • Fitur baru, perbaikan bug, dan perubahan lainnya bergantung pada irama rilis pekerja PowerShell.
  • Karena sifat peningkatan otomatis pekerja PowerShell, DF SDK harus konservatif tentang memperbaiki bug karena setiap perubahan perilaku dapat merupakan perubahan yang melanggar.
  • Algoritma pemutaran ulang yang digunakan oleh DF SDK bawaan sudah kedaluarsa: SDK DF lainnya sudah menggunakan implementasi yang lebih cepat dan lebih andal.

Dengan membuat paket DF PowerShell SDK mandiri, kita dapat mengatasi kekurangan ini. Ini adalah manfaat memanfaatkan paket SDK mandiri baru ini:

  • SDK ini mencakup banyak peningkatan yang sangat diminta seperti pengecualian yang lebih baik dan penanganan nilai null, dan perbaikan serialisasi.
  • Paket ini dibuat versinya secara independen dari pekerja PowerShell. Ini memungkinkan pengguna untuk menggabungkan fitur dan perbaikan baru segera setelah tersedia, sekaligus menghindari melanggar perubahan dari peningkatan otomatis.
  • Logika pemutaran ulang lebih cepat, dan lebih dapat diandalkan: menggunakan mesin pemutaran ulang yang sama dengan SDK terisolasi DF untuk C#.

Rencana penghentian penggunaan untuk DF PowerShell SDK bawaan

DF SDK bawaan di pekerja PowerShell akan tetap tersedia untuk PowerShell 7.4, 7.2, dan rilis sebelumnya.

Kami berencana untuk akhirnya merilis versi utama baru pekerja PowerShell tanpa SDK bawaan. Pada saat itu, pengguna harus menginstal SDK secara terpisah menggunakan paket mandiri ini; langkah-langkah penginstalan dijelaskan di bawah ini.

Menginstal dan mengaktifkan SDK

Lihat bagian ini untuk mempelajari cara menginstal dan mengaktifkan SDK mandiri baru di aplikasi yang sudah ada.

Prasyarat

PowerShell SDK mandiri memerlukan versi minimum berikut:

Ikut serta dalam DF SDK mandiri

Pengaturan aplikasi berikut diperlukan untuk menjalankan PowerShell SDK mandiri:

  • Nama: ExternalDurablePowerShellSDK
  • Nilai: "true"

Pengaturan aplikasi ini akan menonaktifkan Durable SDK bawaan untuk PowerShell versi 7.2 ke atas, memaksa pekerja untuk menggunakan SDK eksternal.

Jika Anda menjalankan secara lokal menggunakan Azure Functions Core Tools, Anda harus menambahkan pengaturan ini ke file Andalocal.settings.json. Jika Anda menjalankan di Azure, ikuti langkah-langkah berikut dengan alat pilihan Anda:

Ganti <FUNCTION_APP_NAME> dan <RESOURCE_GROUP_NAME> dengan nama aplikasi fungsi dan grup sumber daya Anda.

az functionapp config appsettings set --name <FUNCTION_APP_NAME> --resource-group <RESOURCE_GROUP_NAME> --settings ExternalDurablePowerShellSDK="true"

Menginstal dan mengimpor SDK

Anda memiliki dua opsi untuk menginstal paket SDK: dapat diinstal sebagai dependensi terkelola, atau sebagai modul kustom. Di bagian ini, kami menjelaskan kedua opsi tersebut, tetapi hanya salah satunya yang diperlukan.

Opsi penginstalan 1: Gunakan dependensi terkelola

Untuk menginstal SDK sebagai dependensi terkelola, Anda harus mengikuti panduan dependensi terkelola. Harap tinjau panduan untuk detailnya. Singkatnya, Pertama-tama Anda perlu memastikan bahwa Anda host.json berisi managedDependency bagian dengan properti yang enabled diatur ke true. Di bawah ini adalah contoh host.json yang memenuhi persyaratan ini:

{
  "version": "2.0",
  "managedDependency": {
    "enabled": true
  },
  "extensionBundle": {
    "id": "Microsoft.Azure.Functions.ExtensionBundle",
    "version": "[3.*, 4.0.0)"
  },
}

Kemudian Anda hanya perlu menentukan entri untuk DF SDK dalam file Anda requirements.psd1 , seperti dalam contoh di bawah ini:

# This file enables modules to be automatically managed by the Functions service.
# See https://aka.ms/functionsmanageddependency for additional information.
#
@{
    # For latest supported version, go to 'https://www.powershellgallery.com/packages/AzureFunctions.PowerShell.Durable.SDK/'.
    'AzureFunctions.PowerShell.Durable.SDK' = '1.*'
}

Opsi penginstalan 2: Menggunakan modul kustom

Untuk menginstal DF SDK mandiri sebagai modul kustom, Anda perlu mengikuti panduan mengenai pembuatan folder modul tingkat aplikasi. Pastikan untuk meninjau dokumen yang disebutkan di atas untuk detailnya. Singkatnya, Anda harus menempatkan paket SDK di dalam direktori yang ".\Modules" terletak di akar aplikasi Anda.

Misalnya, dari dalam akar aplikasi Anda, dan setelah membuat ".\Modules" direktori, Anda dapat mengunduh SDK mandiri ke direktori modul seperti:

Save-Module -Name AzureFunctions.PowerShell.Durable.SDK -AllowPrerelease -Path ".\Modules"

Mengimpor SDK

Langkah terakhir adalah mengimpor SDK ke sesi kode Anda. Untuk melakukan ini, impor PowerShell SDK melalui Import-Module AzureFunctions.PowerShell.Durable.SDK -ErrorAction Stop di file Anda profile.ps1 . Misalnya, jika aplikasi Anda di-scaffold melalui templat, file Anda profile.ps1 mungkin akhirnya mencari seperti itu:

# Azure Functions profile.ps1
#
# This profile.ps1 will get executed every "cold start" of your Function App.
# "cold start" occurs when:
#
# * A Function App starts up for the very first time
# * A Function App starts up after being de-allocated due to inactivity
#
# You can define helper functions, run commands, or specify environment variables
# NOTE: any variables defined that are not environment variables will get reset after the first execution

# Authenticate with Azure PowerShell using MSI.
# Remove this if you are not planning on using MSI or Azure PowerShell.
if ($env:MSI_SECRET) {
    Disable-AzContextAutosave -Scope Process | Out-Null
    Connect-AzAccount -Identity
}

# Uncomment the next line to enable legacy AzureRm alias in Azure PowerShell.
# Enable-AzureRmAlias

# You can also define functions or aliases that can be referenced in any of your PowerShell functions.

# Import standalone PowerShell SDK
Import-Module AzureFunctions.PowerShell.Durable.SDK -ErrorAction Stop

Ini semua adalah langkah-langkah yang diperlukan untuk menggunakan PowerShell SDK berikutnya. Jalankan aplikasi Anda seperti biasa, melalui func host start di terminal Anda untuk mulai menggunakan SDK.

Panduan migrasi

Di bagian ini, kami menjelaskan antarmuka dan perubahan perilaku yang dapat Anda harapkan saat menggunakan SDK baru.

CmdLet Baru

  • Invoke-DurableSubOrchestrator -FunctionName <Name> -Input <Input> adalah CmdLet baru yang memungkinkan pengguna untuk menggunakan suborkestrator dalam alur kerja mereka.

CmdLet yang Dimodifikasi

  • CmdLet Get-DurableTaskResult -Task <task> sekarang hanya menerima satu Tugas sebagai argumen, alih-alih menerima daftar Tugas.

Perubahan perilaku

  • Pengecualian yang dilemparkan oleh aktivitas yang dijadwalkan dengan Wait-DurableTask (seperti dalam pola Fan-Out/Fan-In) tidak lagi diabaikan secara diam-diam. Sebaliknya, pada pengecualian, CmdLet menyebarluaskan pengecualian tersebut ke orkestrator sehingga dapat ditangani oleh kode pengguna.
  • Nilai null tidak lagi dihilangkan dari daftar hasil pemanggilan Wait-DurableTask (yaitu, WhenAll). Ini berarti bahwa pemanggilan Wait-DurableTask yang berhasil tanpa -Any bendera harus mengembalikan array dengan ukuran yang sama dengan jumlah tugas yang dijadwalkannya.

Tempat mendapatkan dukungan, memberikan umpan balik, dan menyarankan perubahan

Selama fase pratinjau rilis ini, SDK mandiri dapat memperkenalkan beberapa perubahan lagi. Perubahan ini dapat dipengaruhi oleh komunitas sehingga melaporkan umpan balik dan saran apa pun ke repositori GitHub baru SDK.