Guia para o SDK autónomo do PowerShell Durable Functions

O SDK autónomo PowerShell para Durable Functions (AzureFunctions.PowerShell.Durable.SDK) é a abordagem recomendada para criar aplicações Durable Functions com PowerShell. Substitui o SDK incorporado por uma lógica de replay mais rápida (o mesmo motor do SDK isolado em C#), versionamento independente e melhor tratamento de exceções, gestão de valor nulo e serialização. O SDK incorporado continua disponível para PowerShell 7.4 e versões anteriores, mas será removido numa futura versão maior do Worker PowerShell.

Lista de verificação da migração

Use a seguinte lista de verificação para acompanhar o seu progresso em cada etapa da migração:

Instala o SDK independente

Siga estes passos para instalar e ativar o SDK autónomo na sua aplicação existente.

Verificar os pré-requisitos

O SDK do PowerShell autônomo requer as seguintes versões mínimas:

• Funções do Azure Runtime v4.16+
• Funções do Azure Core Tools v4.0.5095+ (se executado localmente)
• Aplicativo PowerShell do Funções do Azure para PowerShell 7.4 ou superior

Ativar o SDK autónomo

A seguinte configuração de aplicativo é necessária para executar o SDK do PowerShell autônomo:

• Nome: ExternalDurablePowerShellSDK
• Valor: "true"

Esta configuração de aplicação desativa o SDK Durable incorporado para PowerShell versões 7.4 e superiores, obrigando o trabalhador a usar o SDK externo.

Se você estiver executando localmente usando as Ferramentas Principais do Funções do Azure, deverá adicionar essa configuração ao seu local.settings.json arquivo. Se você estiver executando no Azure, siga estas etapas com a ferramenta de sua escolha:

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

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

Instalar o pacote SDK

Tens duas opções para instalar o pacote SDK. Use dependências geridas (recomendadas para a maioria das aplicações) ou inclua o módulo com o conteúdo da sua aplicação se precisar de fixar uma versão específica ou se a sua implementação não suportar dependências geridas. Só é necessária uma opção.

Opção 1: Usar dependências geridas (recomendado)

Para instalar o SDK como uma dependência gerida, siga as orientações de dependências geridas. Primeiro, certifique-se de que o host.json contém uma secção managedDependency com enabled definido para true:

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

Depois especifica uma entrada para o SDK no teu requirements.psd1 ficheiro:

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

Opção 2: Incluir o módulo SDK no conteúdo da sua aplicação

Para agrupar o SDK com a sua aplicação, coloque o pacote do SDK dentro de um ".\Modules" diretório na raiz da sua aplicação. Para mais informações, consulte Incluir módulos no conteúdo da aplicação.

A partir da raiz da sua aplicação, crie o diretório e descarregue o SDK:

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

Importar o SDK

Adicione a seguinte linha ao seu profile.ps1 ficheiro para importar o SDK em cada arranque a frio:

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

Executar seu aplicativo

Comece a sua aplicação com func host start. O SDK standalone está agora ativo.

Migrar a partir do SDK incorporado

Se estiver a migrar uma aplicação existente a partir do SDK incorporado, reveja as seguintes alterações de interface e comportamento.

Novos cmdlets

Cmdlets modificados

Mudanças comportamentais

Tratamento de exceções em Wait-DurableTask

Exceções lançadas por atividades agendadas com Wait-DurableTask (padrão fan-out/fan-in) já não são ignoradas silenciosamente. O cmdlet agora propaga a exceção para o orquestrador para que possas tratá-la no teu código.

SDK incorporado — exceções foram silenciosamente absorvidas:

# Exceptions from failed activities were lost
$tasks = @()
$tasks += Invoke-DurableActivity -FunctionName "RiskyActivity" -Input "item1" -NoWait
$tasks += Invoke-DurableActivity -FunctionName "RiskyActivity" -Input "item2" -NoWait
$results = Wait-DurableTask -Task $tasks
# No error even if an activity failed

SDK independente — as exceções são propagadas para o orquestrador:

try {
    $tasks = @()
    $tasks += Invoke-DurableActivity -FunctionName "RiskyActivity" -Input "item1" -NoWait
    $tasks += Invoke-DurableActivity -FunctionName "RiskyActivity" -Input "item2" -NoWait
    $results = Wait-DurableTask -Task $tasks
} catch {
    # Handle the activity failure
    Write-Host "An activity failed: $_"
}

Valores nulos preservados nos Wait-DurableTask resultados

Os valores nulos já não são eliminados da lista de resultados de uma Wait-DurableTask invocação (WhenAll). Uma chamada bem-sucedida sem a -Any flag agora retorna um array do mesmo tamanho do número de tarefas agendadas, incluindo $null entradas para atividades que retornaram nulo.

SDK incorporado — os resultados nulos foram eliminados:

# 3 tasks scheduled, but if one returned $null, results had only 2 items
$results = Wait-DurableTask -Task $tasks
$results.Count  # Could be 2 instead of 3

SDK independente — os resultados nulos são preservados:

# 3 tasks scheduled, results always has 3 items
$results = Wait-DurableTask -Task $tasks
$results.Count  # Always 3, with $null for activities that returned null

Referência do SDK

Para a referência completa do cmdlet, veja AzureFunctions.PowerShell.Durable.SDK Module. Depois de importar o módulo, também pode executar Get-Help *-Durable* para listar todos os cmdlets disponíveis, ou Get-Help <cmdlet-name> -Full para uso detalhado.

Obtenha suporte

Reporte bugs e pedidos de funcionalidades no repositório GitHub do SDK.

Passos seguintes

• Criar uma aplicação Durable Functions com PowerShell
• Padrões e conceitos de funções duráveis
• Referência de desenvolvedor PowerShell para Funções do Azure