Partilhar via

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

O SDK do PowerShell de Funções Duráveis (DF) agora está disponível como um módulo autônomo na Galeria do PowerShell: AzureFunctions.PowerShell.Durable.SDK. Esse SDK agora está disponível em geral (GA) e é a abordagem recomendada para criar aplicativos de Funções Duráveis com o PowerShell. Neste artigo, explicamos os benefícios dessa mudança e quais mudanças você pode esperar ao adotar esse novo pacote.

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 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.4 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' = '2.*'
}

Opção de instalação 2: inclua o módulo SDK no conteúdo do aplicativo

Para incluir o SDK DF autônomo no conteúdo do aplicativo, 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.

Referência do SDK

Consulte Módulo AzureFunctions.PowerShell.Durable.SDK para obter a referência completa dos cmdlets do SDK e seus parâmetros.

Você também pode usar o Get-Help cmdlet para obter descrições detalhadas dos cmdlets do SDK. Para fazer isso, você precisa importar o módulo primeiro, como mostrado na seção anterior. Depois disso, você pode executar o seguinte comando para obter toda a lista de cmdlets:

Get-Help *-Durable*

Para obter ajuda detalhada sobre um cmdlet específico, incluindo exemplos de uso, execute:

Get-Help Invoke-DurableOrchestration -Full

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 é um novo cmdlet que permite que os usuários utilizem suborquestradores em seus fluxos de trabalho.
  • Suspend-DurableOrchestration e Resume-DurableOrchestration são novos cmdlets que permitem aos usuários suspender e retomar orquestrações, respectivamente.

Cmdlets modificados

  • O Get-DurableTaskResult cmdlet agora só aceita uma única Tarefa como argumento, em vez de aceitar uma lista de Tarefas.
  • O New-DurableRetryOptions cmdlet é renomeado para New-DurableRetryPolicy (um alias para o nome antigo é fornecido para compatibilidade com versões anteriores).

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.

Obtenha suporte e forneça feedback

Por favor, informe quaisquer comentários e sugestões para o repositório GitHub do SDK.

  • Last updated on