Partilhar via

Guia para o SDK autónomo Durable Functions PowerShell

  • Artigo

O SDK do PowerShell do Durable Functions (DF) está agora disponível, em pré-visualização, como um pacote autónomo no Galeria do PowerShell: AzureFunctions.PowerShell.Durable.SDK. Assim que este pacote SDK for GA, será o meio recomendado para criar aplicações Durable Functions com o PowerShell. Neste artigo, explicamos os benefícios desta alteração e que alterações pode esperar ao adotar este novo pacote.

Nota

Este pacote está atualmente em pré-visualização.

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

O SDK DF anterior foi incorporado na função de trabalho de linguagem do PowerShell. Esta abordagem veio com o benefício de Durable Functions aplicações pudessem ser criadas fora da caixa para Funções do Azure utilizadores do PowerShell. No entanto, também veio com várias deficiências:

  • As novas funcionalidades, correções de erros e outras alterações estavam dependentes da cadência de lançamento da função de trabalho do PowerShell.
  • Devido à natureza da atualização automática da função de trabalho do PowerShell, o SDK DF precisava de ser conservador sobre a correção de erros, uma vez que quaisquer alterações de comportamento poderiam constituir uma alteração interrupcional.
  • O algoritmo de repetição utilizado pelo SDK DF incorporado estava desatualizado: outros SDKs DF já utilizavam uma implementação mais rápida e fiável.

Ao criar um pacote SDK do Df PowerShell autónomo, conseguimos ultrapassar estas falhas. Estas são as vantagens de utilizar este novo pacote SDK autónomo:

  • Este SDK inclui muitas melhorias altamente solicitadas, tais como melhor processamento de valores nulos e exceções e correções de serialização.
  • O pacote tem uma versão independente da função de trabalho do PowerShell. Isto permite que os utilizadores incorporem novas funcionalidades e correções assim que estiverem disponíveis, evitando também alterações interruptivas das atualizações automáticas.
  • A lógica de repetição é mais rápida e fiável: utiliza o mesmo motor de repetição que o SDK isolado DF para C#.

Plano de preterição para o SDK do PowerShell df incorporado

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

Planeamos, eventualmente, lançar uma nova versão principal da função de trabalho do PowerShell sem o SDK incorporado. Nessa altura, os utilizadores teriam de instalar o SDK separadamente com este pacote autónomo; os passos de instalação são descritos abaixo.

Instalar e ativar o SDK

Veja esta secção para saber como instalar e ativar o novo SDK autónomo na sua aplicação existente.

Pré-requisitos

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

Optar ativamente por participar no SDK DF autónomo

É necessária a seguinte definição de aplicação para executar o SDK autónomo do PowerShell:

  • Nome: ExternalDurablePowerShellSDK
  • Valor: "true"

Esta definição de aplicação irá desativar o SDK Durable incorporado para as versões 7.2 e superior do PowerShell, forçando a função de trabalho a utilizar o SDK externo.

Se estiver a executar localmente com Funções do Azure Ferramentas Principais, deve adicionar esta definição ao seu local.settings.json ficheiro. Se estiver a executar no Azure, siga estes passos com a ferramenta à sua escolha:

Substitua <FUNCTION_APP_NAME> e <RESOURCE_GROUP_NAME> pelo nome da aplicação de funções e do grupo de recursos, respetivamente.

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

Instalar e importar o SDK

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

Opção de instalação 1: Utilizar dependências geridas

Para instalar o SDK como uma dependência gerida, terá de seguir a documentação de orientação sobre dependências geridas. Reveja a documentação de orientação para obter detalhes. Em resumo, primeiro tem de garantir que contém uma managedDependency secção com uma enabled propriedade definida como true.host.json Segue-se um exemplo host.json que satisfaz este 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 DF no seu requirements.psd1 ficheiro, tal 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: utilizar módulos personalizados

Para instalar o SDK DF autónomo como um módulo personalizado, tem de seguir as orientações relativas à criação de uma pasta de módulos ao nível da aplicação. Certifique-se de que revê os documentos acima mencionados para obter detalhes. Em resumo, terá de colocar o pacote SDK dentro de um ".\Modules" diretório localizado na raiz da sua aplicação.

Por exemplo, a partir da raiz da sua aplicação e depois de criar um ".\Modules" diretório, pode transferir o SDK autónomo para o diretório de módulos como tal:

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

Importar o SDK

O passo final é importar o SDK para a sessão do código. Para tal, importe o SDK do PowerShell através Import-Module AzureFunctions.PowerShell.Durable.SDK -ErrorAction Stop do ficheiro profile.ps1 . Por exemplo, se a sua aplicação tiver sido estruturada através de modelos, o ficheiro profile.ps1 pode acabar por parecer como tal:

# 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

Estes são todos os passos necessários para utilizar o próximo SDK do PowerShell. Execute a sua aplicação normalmente, através do func host start seu terminal para começar a utilizar o SDK.

Guia de migração

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

Novos CmdLets

  • Invoke-DurableSubOrchestrator -FunctionName <Name> -Input <Input> é um novo CmdLet que permite aos utilizadores utilizar suborchestradores nos respetivos fluxos de trabalho.

CmdLets Modificados

  • Agora, o CmdLet Get-DurableTaskResult -Task <task> só aceita uma única Tarefa como argumento, em vez de aceitar uma lista de Tarefas.

Alterações comportamentais

  • As exceções emitidas por atividades agendadas com Wait-DurableTask (como no padrão Fan-Out/Fan-In) já não são ignoradas silenciosamente. Em vez disso, numa exceção, o CmdLet propaga essa exceção ao orquestrador para que possa ser processado pelo código de utilizador.
  • Os valores nulos já não são removidos da lista de resultados de uma Wait-DurableTask invocação (ou seja, WhenAll). Isto significa que uma invocação bem-sucedida de Wait-DurableTask sem o -Any sinalizador deve devolver uma matriz do mesmo tamanho que o número de tarefas agendadas.

Onde obter suporte, fornecer feedback e sugerir alterações

Durante a fase de pré-visualização desta versão, o SDK autónomo pode introduzir mais algumas alterações. Estas alterações podem ser influenciadas pela comunidade, pelo que comunicam comentários e sugestões ao novo repositório do GitHub do SDK.