Share via

Przewodnik po autonomicznym zestawie SDK programu PowerShell Durable Functions

  • Artykuł

Zestaw SDK programu PowerShell 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 za autonomicznym zestawem SDK

Poprzedni zestaw SDK systemu plików DF został wbudowany w proces roboczy języka programu PowerShell. Takie podejście jest korzystne, że Durable Functions aplikacje mogą zostać utworzone w pudełku dla użytkowników programu Azure Functions PowerShell. Jednak przyszedł również z różnymi niedociągnięciami:

  • Nowe funkcje, poprawki błędów i inne zmiany były zależne od cykli wydania procesu roboczego programu PowerShell.
  • Ze względu na charakter automatycznego uaktualniania procesu roboczego programu PowerShell zestaw SDK systemu plików DF musi być konserwatywny w zakresie naprawiania 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 już korzystały z szybszej i bardziej niezawodnej implementacji.

Tworząc autonomiczny pakiet zestawu SDK programu PowerShell dla systemu plików DF, możemy przezwyciężyć te wady. Są to korzyści wynikające z 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 zaraz 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ą główną wersję procesu roboczego programu PowerShell bez wbudowanego zestawu SDK. W tym momencie użytkownicy musieliby zainstalować zestaw SDK oddzielnie przy użyciu tego autonomicznego pakietu; kroki instalacji opisano 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:

Włączanie autonomicznego zestawu 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 korzystasz lokalnie z narzędziami Azure Functions Core Tools, 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ć jako zależność zarządzaną lub jako moduł niestandardowy. 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, musisz najpierw upewnić się, że zawiera host.json sekcję managedDependency z właściwością ustawioną enabled na truewartość . 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 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 tworzenia folderu modułów na poziomie 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 znajdującym się w 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 modułów 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 Import-Module AzureFunctions.PowerShell.Durable.SDK -ErrorAction Stop pliku profile.ps1 . Jeśli na przykład aplikacja została utworzona szkieletem za pomocą szablonów, profile.ps1 plik może w końcu 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 wymagane do korzystania z następnego zestawu SDK programu PowerShell. Uruchom aplikację w normalny sposób, 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 CmdLets

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

Zmodyfikowane polecenia CmdLets

  • Polecenie CmdLet Get-DurableTaskResult -Task <task> akceptuje teraz tylko jedno zadanie, ponieważ jest to argument, zamiast akceptowania listy zadań.

Zmiany behawioralne

  • Wyjątki zgłaszane przez działania zaplanowane za pomocą Wait-DurableTask polecenia (jak w wzorcu wentylatora/wentylatora) nie są już ignorowane w trybie dyskretnym. Zamiast tego, w przypadku wyjątku, Narzędzie CmdLet propaguje ten wyjątek do orkiestratora, aby mógł być obsługiwany przez kod użytkownika.
  • Wartości null nie są już usuwane 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 dotyczące nowego repozytorium GitHub zestawu SDK.