Udostępnij za pośrednictwem

Przewodnik po autonomicznym zestawie SDK programu PowerShell dla funkcji Durable Functions

  • Artykuł

Zestaw SDK programu PowerShell dla rozszerzenia Durable Functions (DF) jest teraz dostępny w wersji zapoznawczej jako pakiet autonomiczny w Galeria programu PowerShell: AzureFunctions.PowerShell.Durable.SDK. Gdy ten pakiet SDK będzie ogólnie dostępny, będzie to zalecany sposób tworzenia aplikacji durable functions za pomocą programu PowerShell. W tym artykule wyjaśnimy korzyści wynikające z tej zmiany i jakie zmiany można oczekiwać podczas wdrażania tego nowego pakietu.

Uwaga

Ten pakiet jest obecnie w wersji zapoznawczej.

Motywacja autonomicznego zestawu SDK

Poprzedni zestaw SDK systemu plików DF został wbudowany w proces roboczy języka programu PowerShell. Takie podejście przyniosło korzyści, które mogą być tworzone przez aplikacje Durable Functions w pudełku dla użytkowników programu PowerShell usługi Azure Functions. Jednak wystąpiły również różne niedociągnięć:

  • Nowe funkcje, poprawki błędów i inne zmiany były zależne od kadencji procesu roboczego programu PowerShell.
  • Ze względu na charakter automatycznego uaktualniania procesu roboczego programu PowerShell zestaw SDK systemu plików DF musi być ostrożny w rozwiązywaniu usterek, ponieważ wszelkie zmiany zachowania mogą stanowić niezgodną zmianę.
  • Algorytm odtwarzania używany przez wbudowany zestaw SDK systemu plików DF był nieaktualny: inne zestawy SDK systemu plików DF korzystają już z szybszej i bardziej niezawodnej implementacji.

Tworząc autonomiczny pakiet zestawu SDK programu PowerShell dla systemu plików DF, możemy przezwyciężyć te braki. Są to zalety korzystania z tego nowego autonomicznego pakietu SDK:

  • Ten zestaw SDK zawiera wiele wysoce żądanych ulepszeń, takich jak lepsza obsługa wyjątków i obsługa wartości null oraz poprawki serializacji.
  • Pakiet jest wersjonowany niezależnie od procesu roboczego programu PowerShell. Dzięki temu użytkownicy mogą uwzględniać nowe funkcje i poprawki natychmiast po ich udostępnieniu, jednocześnie unikając zmian powodujących niezgodność z automatycznymi uaktualnieniami.
  • Logika odtwarzania jest szybsza i bardziej niezawodna: używa tego samego aparatu odtwarzania, co izolowany zestaw SDK systemu plików DF dla języka C#.

Plan wycofywania dla wbudowanego zestawu SDK programu PowerShell dla systemu plików DF

Wbudowany zestaw SDK systemu plików DF w ramach procesu roboczego programu PowerShell pozostanie dostępny dla programu PowerShell 7.4, 7.2 i wcześniejszych wersji.

Planujemy w końcu wydać nową wersję główną procesu roboczego programu PowerShell bez wbudowanego zestawu SDK. W tym momencie użytkownicy musieliby zainstalować zestaw SDK oddzielnie przy użyciu tego pakietu autonomicznego; kroki instalacji zostały opisane poniżej.

Instalowanie i włączanie zestawu SDK

Zobacz tę sekcję, aby dowiedzieć się, jak zainstalować i włączyć nowy autonomiczny zestaw SDK w istniejącej aplikacji.

Wymagania wstępne

Autonomiczny zestaw SDK programu PowerShell wymaga następujących minimalnych wersji:

Wyrażanie zgody na autonomiczny zestaw SDK systemu plików DF

Do uruchomienia autonomicznego zestawu SDK programu PowerShell wymagane jest następujące ustawienie aplikacji:

  • Nazwa: ExternalDurablePowerShellSDK
  • Wartość: "true"

To ustawienie aplikacji spowoduje wyłączenie wbudowanego zestawu Durable SDK dla programu PowerShell w wersji 7.2 lub nowszej, co zmusza proces roboczy do korzystania z zewnętrznego zestawu SDK.

Jeśli używasz narzędzi Azure Functions Core Tools lokalnie, należy dodać to ustawienie do local.settings.json pliku. Jeśli korzystasz z platformy Azure, wykonaj następujące kroki za pomocą wybranego narzędzia:

Zastąp <FUNCTION_APP_NAME> wartości i <RESOURCE_GROUP_NAME> nazwą aplikacji funkcji i grupy zasobów odpowiednio.

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

Instalowanie i importowanie zestawu SDK

Dostępne są dwie opcje instalowania pakietu SDK: można go zainstalować przy użyciu zarządzanych zależności lub powiązać z zawartością aplikacji. W tej sekcji opisano obie opcje, ale potrzebna jest tylko jedna z nich.

Opcja instalacji 1. Korzystanie z zarządzanych zależności

Aby zainstalować zestaw SDK jako zależność zarządzaną, należy postępować zgodnie ze wskazówkami dotyczącymi zarządzanych zależności. Zapoznaj się ze wskazówkami, aby uzyskać szczegółowe informacje. Podsumowując, najpierw należy upewnić się, że zawiera host.json sekcję managedDependency z właściwością ustawioną enabled na true. Poniżej przedstawiono przykład host.json spełniający to wymaganie:

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

Następnie wystarczy po prostu określić wpis dla zestawu DF SDK w requirements.psd1 pliku, jak w poniższym przykładzie:

# 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.*'
}

Opcja instalacji 2. Używanie modułów niestandardowych

Aby zainstalować autonomiczny zestaw DF SDK jako moduł niestandardowy, należy postępować zgodnie ze wskazówkami dotyczącymi dołączania modułów w zawartości aplikacji. Aby uzyskać szczegółowe informacje, zapoznaj się z wyżej wymienionymi dokumentami. Podsumowując, należy umieścić pakiet zestawu SDK w ".\Modules" katalogu głównym aplikacji.

Na przykład z poziomu katalogu głównego aplikacji i po utworzeniu ".\Modules" katalogu możesz pobrać autonomiczny zestaw SDK do katalogu modules w następujący sposób:

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

Importowanie zestawu SDK

Ostatnim krokiem jest zaimportowanie zestawu SDK do sesji kodu. W tym celu zaimportuj zestaw SDK programu PowerShell za pośrednictwem pliku Import-Module AzureFunctions.PowerShell.Durable.SDK -ErrorAction Stopprofile.ps1 . Jeśli na przykład aplikacja została utworzona szkieletem za pomocą szablonów, plik profile.ps1 może wyglądać następująco:

# 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

Są to wszystkie kroki potrzebne do korzystania z następnego zestawu PowerShell SDK. Uruchom aplikację normalnie, korzystając z func host start terminalu, aby rozpocząć korzystanie z zestawu SDK.

Przewodnik migracji

W tej sekcji opisano zmiany interfejsu i zachowania, których można oczekiwać podczas korzystania z nowego zestawu SDK.

Nowe polecenia cmdLet

  • Invoke-DurableSubOrchestrator -FunctionName <Name> -Input <Input> to nowy cmdLet, który umożliwia użytkownikom korzystanie z suborchestratorów w swoich przepływach pracy.

Zmodyfikowane polecenia cmdLet

  • Polecenie CmdLet Get-DurableTaskResult -Task <task> akceptuje teraz tylko jedno zadanie jako argument, zamiast akceptować listę zadań.

Zmiany zachowań

  • Wyjątki zgłaszane przez działania zaplanowane Wait-DurableTask za pomocą funkcji (tak jak we wzorcu Fan-Out/Fan-In) nie są już ignorowane w trybie dyskretnym. Zamiast tego w przypadku wyjątku polecenie CmdLet propaguje ten wyjątek do orkiestratora, aby mógł być obsługiwany przez kod użytkownika.
  • Wartości null nie są już porzucane z listy Wait-DurableTask wyników wywołania (tj. WhenAll). Oznacza to, że pomyślne wywołanie Wait-DurableTask bez -Any flagi powinno zwrócić tablicę o takim samym rozmiarze jak liczba zaplanowanych zadań.

Gdzie uzyskać pomoc techniczną, przekazać opinię i zasugerować zmiany

W fazie wersji zapoznawczej tego wydania autonomiczny zestaw SDK może wprowadzić jeszcze kilka zmian. Te zmiany mogą mieć wpływ na społeczność, aby zgłaszać wszelkie opinie i sugestie do nowego repozytorium GitHub zestawu SDK.