Partilhar via

Guia para o SDK do PowerShell de Funções Duráveis autônomo

  • Artigo

O SDK do PowerShell de Funções Duráveis (DF) agora está disponível, em visualização, como um pacote autônomo na Galeria do PowerShell: AzureFunctions.PowerShell.Durable.SDK. Quando esse pacote SDK for GA, ele será o meio recomendado de criar aplicativos Durable Functions com o PowerShell. Neste artigo, explicamos os benefícios dessa mudança e quais mudanças você pode esperar ao adotar esse novo pacote.

Nota

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

Motivação por trás do SDK independente

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

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

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

  • Esse SDK inclui muitos aprimoramentos altamente solicitados, como melhor tratamento de exceções e valores nulos e correções de serialização.
  • O pacote é versionado independentemente do trabalhador do PowerShell. Isso permite que os usuários incorporem novos recursos e correções assim que estiverem disponíveis, ao mesmo tempo em que evitam alterações de interrupções de atualizações automáticas.
  • A lógica de repetição é mais rápida e confiável: ela usa o mesmo mecanismo de reprodução que o SDK isolado DF para C#.

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

O SDK DF interno no trabalhador 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 trabalhador do PowerShell sem o SDK interno. Nesse ponto, os usuários precisariam instalar o SDK separadamente usando esse pacote autônomo; As etapas de instalação são descritas abaixo.

Instalar e ativar o SDK

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

Pré-requisitos

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

Aceitar o SDK DF autônomo

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

  • Nome: ExternalDurablePowerShellSDK
  • Valor: "true"

Essa configuração de aplicativo desabilitará o SDK durável interno para PowerShell versões 7.2 e superiores, forçando o trabalhador a usar o SDK externo.

Se você estiver executando localmente usando as Ferramentas Principais do Azure Functions, 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:

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

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

Instalar e importar o SDK

Você tem duas opções para instalar o pacote SDK: ele pode ser instalado usando Dependências Gerenciadas ou empacotado com o conteúdo do seu aplicativo. Nesta seção, descrevemos ambas as 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. Consulte as orientações para obter detalhes. Em resumo, primeiro você precisa garantir que contém host.json uma managedDependency seção com uma enabled propriedade definida como true. Abaixo está 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 DF SDK no seu requirements.psd1 arquivo, 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 DF autônomo como um módulo personalizado, você precisa seguir as orientações sobre a inclusão de módulos no conteúdo do aplicativo. Certifique-se de revisar os documentos acima mencionados para obter detalhes. Em resumo, você precisará colocar o pacote SDK dentro de um ".\Modules" diretório localizado na raiz do seu aplicativo.

Por exemplo, de dentro da raiz do seu aplicativo, e depois de criar um ".\Modules" diretório, você pode baixar o SDK autônomo para o diretório modules 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 via Import-Module AzureFunctions.PowerShell.Durable.SDK -ErrorAction Stop em seu profile.ps1 arquivo. Por exemplo, se seu aplicativo foi empacotado por meio de modelos, seu profile.ps1 arquivo pode acabar parecendo 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

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

Guia de migração

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

Novos CmdLets

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

CmdLets modificados

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

Mudanças comportamentais

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

Onde obter apoio, fornecer feedback 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 qualquer feedback e sugestões ao novo repositório GitHub do SDK.