독립 실행형 Durable Functions PowerShell SDK 가이드

아티클
02/23/2024

이제 DF(Durable Functions) PowerShell SDK를 PowerShell 갤러리 AzureFunctions.PowerShell.Durable.SDK에서 독립 실행형 패키지로서 미리 보기로 사용할 수 있습니다. 이 SDK 패키지가 GA이면 PowerShell을 사용하여 Durable Functions 앱을 작성하는 것이 좋습니다. 이 문서에서는 이 변경의 이점과 이 새 패키지를 채택할 때 기대할 수 있는 변경 내용에 대해 설명합니다.

참고 항목

이 패키지는 현재 미리 보기로 제공됩니다.

독립 실행형 SDK의 개발 동기

이전 DF SDK는 PowerShell 언어 작업자에 기본으로 제공되었습니다. 이 방법에는 Azure Functions PowerShell 사용자용 Durable Functions 앱을 바로 작성할 수 있다는 이점이 있습니다. 그러나 다음과 같은 몇 가지 단점이 있습니다.

새로운 기능, 버그 수정 및 기타 변경 내용은 PowerShell 작업자의 릴리스 주기에 따라 달라집니다.
PowerShell 작업자의 자동 업그레이드 특성으로 인해 DF SDK는 동작 변경에 따른 호환성 손상을 발생할 수 있으므로 버그 수정에 대해 보수적이어야 했습니다.
기본 제공 DF SDK에서 사용하는 재생 알고리즘은 오래된 것입니다. 다른 DF SDK는 이미 더 빠르고 신뢰할 수 있는 구현을 활용했습니다.

독립 실행형 DF PowerShell SDK 패키지를 만들어 이러한 단점을 극복할 수 있습니다. 다음은 이 새로운 독립 실행형 SDK 패키지를 활용할 때의 이점입니다.

이 SDK에는 더 나은 예외 및 null 값 처리, 직렬화 수정 등 요청이 많은 개선 사항이 포함되어 있습니다.
이 패키지는 PowerShell 작업자와는 독립적으로 버전이 지정됩니다. 이를 통해 사용자는 사용 가능한 즉시 새로운 기능과 수정 사항을 통합할 수 있으며 자동 업그레이드로 인한 호환성이 손상되는 변경을 방지할 수 있습니다.
재생 논리는 더 빠르고 안정적입니다. C#용 DF 격리 SDK와 동일한 재생 엔진을 사용합니다.

기본 제공 DF PowerShell SDK에 대한 사용 중단 플랜

PowerShell 작업자의 기본 제공 DF SDK는 PowerShell 7.4, 7.2 및 이전 릴리스에서 계속 사용할 수 있습니다.

결국 기본 제공 SDK 없이 PowerShell 작업자의 새 주 버전을 출시할 계획입니다. 이 시점에서 사용자는 이 독립 실행형 패키지를 사용하여 SDK를 별도로 설치해야 합니다. 설치 단계는 아래에 설명되어 있습니다.

SDK 설치 및 사용

기존 앱에서 새 독립 실행형 SDK를 설치하고 사용하도록 설정하는 방법을 알아보려면 이 섹션을 참조하세요.

필수 조건

독립 실행형 PowerShell SDK에는 다음과 같은 최소 버전이 필요합니다.

Azure Functions 런타임 v4.16+
Azure Functions Core Tools v4.0.5095+(로컬로 실행되는 경우)
PowerShell 7.2 이상용 Azure Functions PowerShell 앱

독립 실행형 DF SDK에 옵트인

독립 실행형 PowerShell SDK를 실행하려면 다음 애플리케이션 설정이 필요합니다.

이름: ExternalDurablePowerShellSDK
값: "true"

이 애플리케이션 설정은 PowerShell 버전 7.2 이상에 대한 기본 제공 Durable SDK를 사용하지 않도록 설정하여 작업자가 외부 SDK를 강제로 사용하도록 합니다.

Azure Functions Core Tools를 사용하여 로컬로 실행하는 경우 이 설정을 local.settings.json 파일에 추가해야 합니다. Azure에서 실행하는 경우 선택한 도구를 사용하여 다음 단계를 수행합니다.

<FUNCTION_APP_NAME> 및 <RESOURCE_GROUP_NAME>을 각각 함수 앱의 이름과 리소스 그룹의 이름으로 바꿉니다.

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

<FUNCTION_APP_NAME> 및 <RESOURCE_GROUP_NAME>을 각각 함수 앱의 이름과 리소스 그룹의 이름으로 바꿉니다.

Update-AzFunctionAppSetting -Name <FUNCTION_APP_NAME> -ResourceGroupName <RESOURCE_GROUP_NAME> -AppSetting @{"ExternalDurablePowerShellSDK" = "'true'"}

VS Code에 대한 Azure Functions 확장이 설치되어 있는지 확인합니다.
F1 키를 눌러 명령 팔레트를 엽니다. 명령 팔레트에서 Azure Functions: Add New Setting...을 검색하여 선택합니다.
메시지가 표시되면 구독 및 함수 앱 선택
이름으로 ExternalDurablePowerShellSDK를 입력하고 Enter 키를 누릅니다.
값에 "true"을 입력하고 Enter를 누릅니다.

SDK 설치 및 가져오기

SDK 패키지를 설치하는 두 가지 옵션이 있습니다. 즉, 관리되는 종속성을 사용하여 설치하거나 앱 콘텐츠와 함께 번들로 묶을 수 있습니다. 이 섹션에서는 두 옵션을 모두 설명하지만 그중 하나만 필요합니다.

설치 옵션 1: 관리형 종속성 사용

SDK를 관리형 종속성으로 설치하려면 관리형 종속성 지침을 따라야 합니다. 자세한 내용은 지침을 검토하세요. 요약하자면 먼저 host.json에는 enabled 속성이 true로 설정된 managedDependency 섹션이 포함되어 있는지 확인해야 합니다. 다음은 이 요구 사항을 충족하는 예제 host.json입니다.

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

그런 다음, 아래 예제와 같이 requirements.psd1 파일에서 DF SDK에 대한 항목을 지정하기만 하면 됩니다.

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

설치 옵션 2: 사용자 지정 모듈 사용

독립 실행형 DF SDK를 사용자 지정 모듈로 설치하려면 앱 콘텐츠에 모듈을 포함하는 방법에 대한 지침을 따라야 합니다. 자세한 내용은 앞에서 언급한 문서를 검토해야 합니다. 요약하면 앱의 루트에 있는 ".\Modules" 디렉터리 내에 SDK 패키지를 배치해야 합니다.

예를 들어 애플리케이션의 루트 내에서 ".\Modules" 디렉터리를 만든 후 다음과 같이 독립 실행형 SDK를 모듈 디렉터리에 다운로드할 수 있습니다.

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

SDK 가져오기

마지막 단계는 코드의 세션으로 SDK를 가져오는 것입니다. 이렇게 하려면 profile.ps1 파일에서 Import-Module AzureFunctions.PowerShell.Durable.SDK -ErrorAction Stop을 통해 PowerShell SDK를 가져옵니다. 예를 들어 앱이 템플릿을 통해 스캐폴드된 경우 profile.ps1 파일은 다음과 같이 표시될 수 있습니다.

# 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

다음 PowerShell SDK를 활용하는 데 필요한 모든 단계는 다음과 같습니다. 터미널에서 func host start를 통해 앱을 정상적으로 실행하여 SDK 사용을 시작합니다.

마이그레이션 가이드

이 섹션에서는 새 SDK를 활용할 때 예상할 수 있는 인터페이스 및 동작 변경에 대해 설명합니다.

새 cmdlet

Invoke-DurableSubOrchestrator -FunctionName <Name> -Input <Input>은 사용자가 워크플로에서 하위 호스트를 활용할 수 있는 새로운 cmdlet입니다.

수정된 cmdlet

이제 CmdLet Get-DurableTaskResult -Task <task>는 작업 목록을 수락하는 대신 단일 작업만 인수로 허용합니다.

동작 변경 내용

팬아웃/팬인 패턴과 같이 Wait-DurableTask로 예약된 활동에서 throw된 예외는 더 이상 자동으로 무시되지 않습니다. 대신 예외에서 이 CmdLet은 해당 예외를 오케스트레이터에 전파하여 사용자 코드에서 처리할 수 있도록 합니다.
Null 값은 더 이상 Wait-DurableTask(즉, WhenAll) 호출의 결과 목록에서 삭제되지 않습니다. 즉, -Any 플래그 없이 Wait-DurableTask를 성공적으로 호출하면 예약된 작업 수와 동일한 크기의 배열이 반환됩니다.

지원을 받고, 피드백을 제공하고, 변경 내용을 제안할 수 있는 위치

이 릴리스의 미리 보기 단계에서 독립 실행형 SDK는 몇 가지 변경 내용을 추가로 도입할 수 있습니다. 이러한 변경 내용은 커뮤니티의 영향을 받을 수 있으므로 SDK의 새 GitHub 리포지토리에 피드백과 제안 사항을 보고할 수 있습니다.

다음을 통해 공유