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

O SDK do PowerShell do Durable Functions (DF) agora está disponível, em versão prévia, como um pacote autônomo no Galeria do PowerShell: AzureFunctions.PowerShell.Durable.SDK. Depois que esse pacote do SDK for GA, ele será o meio recomendado de criar aplicativos do Durable Functions com o PowerShell. Neste artigo, explicamos os benefícios dessa alteração e quais alterações você pode esperar ao adotar esse novo pacote.

Observação

O pacote está atualmente em versão prévia.

Motivação por trás do SDK autônomo

O SDK do DF anterior foi integrado ao trabalho de linguagem do PowerShell. Essa abordagem veio com o benefício de que os aplicativos do Durable Functions poderiam ser criados prontos para usuários do PowerShell do Azure Functions. No entanto, ele também veio com várias deficiências:

• Novos recursos, correções de bugs e outras alterações dependiam da cadência de versão de trabalho do PowerShell.
• Devido à natureza de atualização automática do trabalho do PowerShell, o SDK do DF precisava ser conservador sobre a correção de bugs, pois qualquer alteração de comportamento poderia constituir uma alteração interruptiva.
• O algoritmo de reprodução utilizado pelo SDK interno do DF estava desatualizado: outros SDKs do DF já utilizavam uma implementação mais rápida e confiável.

Ao criar um pacote autônomo do SDK do PowerShell do DF, podemos superar essas deficiências. Esses são os benefícios de utilizar este novo pacote SDK autônomo:

• Esse SDK inclui muitas melhorias altamente solicitadas, como melhor tratamento de exceções e valores nulos, bem como correções de serialização.
• O pacote recebe uma versão independente do trabalho do PowerShell. Isso permite que os usuários incorporem novos recursos e correções assim que estiverem disponíveis, evitando também alterações interruptivas de atualizações automáticas.
• A lógica de reprodução é mais rápida e mais confiável: ela usa o mesmo mecanismo de reprodução que o SDK isolado do DF para C#.

Plano de substituição para o SDK interno do PowerShell do DF

O SDK DF interno na função de trabalho do PowerShell permanecerá disponível para o PowerShell 7.4, 7.2 e versões anteriores.

Planejamos eventualmente lançar uma nova versão principal do trabalho do PowerShell sem o SDK interno. Nesse ponto, os usuários precisariam instalar o SDK separadamente utilizando esse pacote autônomo; as etapas de instalação estão descritas abaixo.

Instalar e habilitar o SDK

Confira esta seção para saber como instalar e habilitar o novo SDK autônomo em seu aplicativo existente.

Pré-requisitos

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

• Azure Functions Runtime v4.16+
• Azure Functions Core Tools v4.0.5095+ (se em execução localmente)
• Aplicativo do PowerShell do Azure Functions para PowerShell 7.2 ou superior

Aceitar o SDK autônomo do DF

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 desabilitará o SDK interno do Durable para as versões 7.2 e posteriores do PowerShell, forçando o trabalhador a utilizar 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:

CLI do Azure

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"

PowerShell do Azure

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

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

Código do VS

1. Verifique se você tem a extensão do Azure Functions para VS Code instalada
2. Pressione F1 para abrir a paleta de comandos. Na paleta de comandos, pesquise e selecione Azure Functions: Add New Setting....
3. Escolha sua assinatura e aplicativo de funções quando solicitado
4. Para o nome, digite ExternalDurablePowerShellSDK e pressione Enter.
5. Para o valor, digite "true" e pressione Enter.

Instalar e importar o SDK

Você tem duas opções para instalar o pacote do SDK: ele pode ser instalado como uma dependência gerenciada ou como um módulo personalizado. Nesta seção, descrevemos as duas opções, mas apenas uma delas é necessária.

Opção de instalação 1: usar dependências gerenciadas

Para instalar o SDK como uma dependência gerenciada, você precisará seguir as diretrizes de dependências gerenciadas. Examine as diretrizes para obter detalhes. Em resumo, primeiro você precisa garantir que o host.json contenha uma seção managedDependency com uma propriedade enabled definida como true. Veja abaixo um exemplo host.json que atende a esse requisito:

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

Em seguida, basta especificar uma entrada para o SDK do DF em seu arquivo requirements.psd1, como no exemplo abaixo:

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

Opção de instalação 2: usar módulos personalizados

Para instalar o SDK do DF autônomo como um módulo personalizado, você precisa seguir as diretrizes sobre como criar uma pasta de módulos no nível do aplicativo. Examine os documentos mencionados anteriormente para obter detalhes. Em resumo, você precisará colocar o pacote do SDK dentro de um diretório ".\Modules" localizado na raiz do aplicativo.

Por exemplo, de dentro da raiz do aplicativo e depois de criar um diretório ".\Modules", você pode baixar o SDK autônomo no diretório de módulos como tal:

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

Importando o SDK

A etapa final é importar o SDK para a sessão do código. Para fazer isso, importe o SDK do PowerShell por meio de Import-Module AzureFunctions.PowerShell.Durable.SDK -ErrorAction Stop em seu arquivo profile.ps1. Por exemplo, se o aplicativo sofreu scaffolding por meio de modelos, seu arquivo profile.ps1 pode acabar se parecendo com o seguinte:

# 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

Essas são todas as etapas necessárias para utilizar o próximo SDK do PowerShell. Execute seu aplicativo normalmente, por meio de func host start em seu terminal, para começar a usar o SDK.

Guia de migração

Nesta seção, descrevemos a interface e as alterações comportamentais que você pode esperar ao utilizar o novo SDK.

Novos cmdlets

• Invoke-DurableSubOrchestrator -FunctionName <Name> -Input <Input> é um novo CmdLet que permite que os usuários utilizem suborquestradores em seus fluxos de trabalho.

Cmdlets modificados

• O CmdLet Get-DurableTaskResult -Task <task> agora aceita apenas uma única tarefa como argumento, em vez de aceitar uma lista de tarefas.

Alterações de comportamento

• Exceções geradas por atividades agendadas com Wait-DurableTask (como no padrão Fan-Out/Fan-In) não são mais ignoradas silenciosamente. Em vez disso, em uma exceção, o CmdLet propaga essa exceção para o orquestrador para que ele possa ser tratado pelo código do usuário.
• Os valores nulos não são mais removidos da lista de resultados de uma invocação Wait-DurableTask (ou seja, WhenAll). Isso significa que uma invocação bem-sucedida de Wait-DurableTask sem o sinalizador -Any deve retornar uma matriz do mesmo tamanho que o número de tarefas agendadas por ela.

Onde obter suporte, fornecer comentários e sugerir alterações

Durante a fase de visualização desta versão, o SDK autônomo pode introduzir mais algumas alterações. Essas alterações podem ser influenciadas pela comunidade, portanto, relate comentários e sugestões ao novo repositório GitHub do SDK.