Guia para o SDK do PowerShell do Durable Functions autônomo

O SDK do PowerShell Durable Functions autônomo (AzureFunctions.PowerShell.Durable.SDK) é a abordagem recomendada para criar aplicativos Durable Functions com o PowerShell. Ele substitui o SDK interno por uma lógica de reprodução mais rápida (o mesmo mecanismo do SDK isolado do C#), controle de versão independente e manipulação de exceção aprimorada, tratamento de valor nulo e serialização. O SDK interno permanece disponível para o PowerShell 7.4 e anterior, mas será removido em uma futura versão importante do worker do PowerShell.

Lista de verificação de migração

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

Passo Seção
1. Verificar pré-requisitos Pré-requisitos
2. Habilitar o SDK autônomo Habilitar o SDK autônomo
3. Instalar o pacote do SDK Instalar o pacote do SDK
4. Importar o SDK Importar o SDK
5. Executar seu aplicativo Executar seu aplicativo
6. Revise a interface e as alterações comportamentais Migrar do SDK interno

Instalar o SDK autônomo

Siga estas etapas para instalar e habilitar o SDK autônomo em seu aplicativo existente.

Verificar pré-requisitos

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

Habilitar o SDK autônomo

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

  • Nome: ExternalDurablePowerShellSDK
  • Valor: "true"

Essa configuração de aplicativo desabilita o SDK Durável interno para as versões 7.4 e superiores do PowerShell, forçando o processo a usar o SDK externo.

Se você estiver executando localmente com o Azure Functions Core Tools, deverá adicionar essa configuração ao arquivo local.settings.json. Se você estiver executando no Azure, siga essas etapas com a ferramenta de sua preferência:

Substitua <FUNCTION_APP_NAME> e <RESOURCE_GROUP_NAME> pelo nome do seu aplicativo de funções e grupo de recursos, respectivamente.

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

Instalar o pacote do SDK

Você tem duas opções para instalar o pacote do SDK. Use dependências gerenciadas (recomendadas para a maioria dos aplicativos) ou incorpore o módulo ao conteúdo do seu aplicativo se você precisar especificar uma versão específica ou sua implementação não oferecer suporte a dependências gerenciadas. Apenas uma opção é necessária.

Para instalar o SDK como uma dependência gerenciada, siga as diretrizes de dependências gerenciadas. Primeiro, verifique se seu host.json contém uma managedDependency seção com enabled configurada para true.

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

Em seguida, especifique uma entrada para o SDK em seu requirements.psd1 arquivo:

# 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 do aplicativo

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

Na raiz do aplicativo, crie o diretório e baixe o SDK:

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

Importar o SDK

Adicione a seguinte linha ao arquivo profile.ps1 para importar o SDK em cada inicialização a frio:

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

Executar o aplicativo

Inicie seu aplicativo com func host start. O SDK autônomo agora está ativo.

Migrar do SDK interno

Se você estiver migrando um aplicativo existente do SDK interno, examine a interface e as alterações comportamentais a seguir.

Novos cmdlets

Cmdlet Descrição
Invoke-DurableSubOrchestrator Chame suborquestradores a partir de um fluxo de trabalho de orquestração.
Suspend-DurableOrchestration Suspender uma instância de orquestração em execução.
Resume-DurableOrchestration Retome uma instância de orquestração suspensa anteriormente.

Cmdlets modificados

Mudar Detalhes
Get-DurableTaskResult Agora aceita um único Task como argumento em vez de uma lista de tarefas.
New-DurableRetryOptions → New-DurableRetryPolicy Renomeado. Um alias para o nome antigo é fornecido para compatibilidade com versões anteriores.

Alterações comportamentais

Tratamento de exceção em Wait-DurableTask

Exceções geradas por atividades agendadas com Wait-DurableTask (padrão fan-out/fan-in) não são mais ignoradas silenciosamente. O cmdlet agora propaga a exceção para o orquestrador para que você possa lidar com ele em seu código.

SDK interno – exceções foram suprimidas silenciosamente.

# 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 autônomo — 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 em Wait-DurableTask resultados

Valores nulos não são mais removidos da lista de resultados de uma Wait-DurableTask invocação (WhenAll). Uma chamada bem-sucedida sem o -Any sinalizador agora retorna uma matriz do mesmo tamanho do número de tarefas agendadas, incluindo $null entradas para atividades que retornaram nulo.

SDK interno – os resultados nulos foram descartados:

# 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 autônomo – 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 obter a referência completa do cmdlet, consulte AzureFunctions.PowerShell.Durable.SDK Module. Depois de importar o módulo, você 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

Relatar bugs e solicitações de recursos no repositório GitHub do SDK.

Próximas Etapas 

  • Last updated on