Guía del SDK de PowerShell Durable Functions independiente

  • Artículo

El SDK de PowerShell Durable Functions (DF) ya está disponible, en versión preliminar, como un paquete independiente en la Galería de PowerShell: AzureFunctions.PowerShell.Durable.SDK. Una vez que este paquete de SDK sea de disponibilidad general, será el medio recomendado para crear aplicaciones de Durable Functions con PowerShell. En este artículo se explican las ventajas de este cambio y los cambios que puede esperar al adoptar este nuevo paquete.

Nota

Este paquete está actualmente en versión preliminar.

Motivación detrás del SDK independiente

El SDK DF anterior estaba integrado en el trabajo de lenguaje de PowerShell. Este enfoque llegó con la ventaja de que las aplicaciones de Durable Functions podrían crearse para su uso inmediato para los usuarios de PowerShell de Azure Functions. Sin embargo, también llegó con varias deficiencias:

  • Las nuevas características, correcciones de errores y otros cambios dependían de la cadencia de lanzamiento del trabajo de PowerShell.
  • Debido a la naturaleza de actualización automática del trabajo de PowerShell, el SDK DF necesitaba ser conservador sobre la corrección de errores, ya que los cambios de comportamiento podrían constituir un cambio importante.
  • El algoritmo de reproducción utilizado por el SDK DF integrado estaba obsoleto: otros SDK DF ya usaban una implementación más rápida y confiable.

Al crear un paquete independiente del SDK de PowerShell DF, podemos superar estas deficiencias. Estas son las ventajas de usar este nuevo paquete de SDK independiente:

  • Este SDK incluye muchas mejoras muy solicitadas, como un mejor control de excepciones y valores NULL, y correcciones de serialización.
  • El paquete tiene versiones independientes del trabajo de PowerShell. Esto permite a los usuarios incorporar nuevas características y correcciones tan pronto como estén disponibles, a la vez que evita cambios importantes de las actualizaciones automáticas.
  • La lógica de reproducción es más rápida y confiable: usa el mismo motor de reproducción que el SDK aislado de DF para C#.

Plan de desuso para el SDK de PowerShell DF integrado

El SDK de DF integrado en el trabajo de PowerShell seguirá estando disponible para PowerShell 7.4, 7.2 y versiones anteriores.

Tenemos previsto publicar una nueva versión principal del trabajo de PowerShell sin el SDK integrado. En ese momento, los usuarios tendrían que instalar el SDK por separado usando este paquete independiente; los pasos de instalación se describen a continuación.

Instalación y habilitación del SDK

Consulte esta sección para obtener información sobre cómo instalar y habilitar el nuevo SDK independiente en la aplicación existente.

Requisitos previos

El SDK de PowerShell independiente requiere las siguientes versiones mínimas:

Participar en el SDK DF independiente

La siguiente configuración de aplicación es necesaria para ejecutar el SDK de PowerShell independiente:

  • Nombre: ExternalDurablePowerShellSDK
  • Valor: "true"

Esta configuración de aplicación deshabilitará el SDK durable integrado para las versiones 7.2 y posteriores de PowerShell, lo que obligará al trabajo a usar el SDK externo.

Si se ejecuta localmente con Azure Functions Core Tools, debe agregar esta configuración al archivo local.settings.json. Si se ejecuta en Azure, siga estos pasos con la herramienta que prefiera:

Sustituya <FUNCTION_APP_NAME> y <RESOURCE_GROUP_NAME> por el nombre de su aplicación de función y grupo de recursos, respectivamente.

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

Instalación e importación del SDK

Tiene dos opciones para instalar el paquete del SDK: se puede instalar como una dependencia administrada o como un módulo personalizado. En esta sección, se describen ambas opciones, pero solo se necesita una de ellas.

Opción de instalación 1: uso de dependencias administradas

Para instalar el SDK como una dependencia administrada, deberá seguir las instrucciones de dependencias administradas. Revise la guía para obtener más detalles. En resumen, primero debe asegurarse de que host.json contiene una sección managedDependency con una propiedad enabled establecida en true. A continuación se muestra un ejemplo host.json que cumple este requisito:

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

A continuación, basta con especificar una entrada para el SDK DF en el archivo requirements.psd1, como en el ejemplo siguiente:

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

Opción de instalación 2: uso de módulos personalizados

Para instalar el SDK DF independiente como un módulo personalizado, debe seguir las instrucciones sobre la creación de una carpeta de módulos de nivel de aplicación. Asegúrese de revisar los documentos mencionados anteriormente para obtener más información. En resumen, deberá colocar el paquete del SDK dentro de un directorio ".\Modules" ubicado en la raíz de la aplicación.

Por ejemplo, desde dentro de la raíz de la aplicación, y después de crear un directorio ".\Modules" puede descargar el SDK independiente en el directorio de módulos como tal:

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

Importación del SDK

El último paso es importar el SDK en la sesión del código. Para ello, importe el SDK de PowerShell a través de Import-Module AzureFunctions.PowerShell.Durable.SDK -ErrorAction Stop en el archivo profile.ps1. Por ejemplo, si se ha aplicado scaffolding en la aplicación a través de plantillas, el archivo profile.ps1 puede acabar luciendo de la siguiente manera:

# 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

Estos son todos los pasos necesarios para usar el próximo SDK de PowerShell. Ejecute la aplicación de la forma habitual, a través de func host start en el terminal para empezar a usar el SDK.

Guía de migración

En esta sección, se describen los cambios de interfaz y comportamiento que puede esperar al usar el nuevo SDK.

Nuevos cmdlets

  • Invoke-DurableSubOrchestrator -FunctionName <Name> -Input <Input> es un nuevo cmdlet que permite a los usuarios usar suborquestadores en sus flujos de trabajo.

Cmdlets modificados

  • El cmdlet Get-DurableTaskResult -Task <task> ahora solo acepta una sola tarea como argumento, en lugar de aceptar una lista de tareas.

Cambios de comportamiento

  • Las excepciones producidas por las actividades programadas con Wait-DurableTask (como en el patrón para la distribución ramificada de entrada/salida) ya no se omiten de forma silenciosa. En su lugar, en una excepción, el cmdlet propaga esa excepción al orquestador para que el código de usuario pueda controlarla.
  • Los valores NULL ya no se quitan de la lista de resultados de una invocación Wait-DurableTask (es decir, WhenAll). Esto significa que una invocación correcta de Wait-DurableTask sin la marca -Any debe devolver una matriz del mismo tamaño que el número de tareas programadas.

Dónde obtener soporte técnico, proporcionar comentarios y sugerir cambios

Durante la fase de versión preliminar de esta versión, el SDK independiente puede introducir algunos cambios más. Estos cambios pueden verse influenciados por la comunidad, así que envíe sus comentarios y sugerencias al nuevo repositorio de GitHub del SDK.