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 usando Dependências Gerenciadas ou agrupado com o conteúdo do aplicativo. 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 a inclusão de módulos no conteúdo 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.