Partekatu honen bidez:

Guía del SDK de PowerShell Durable Functions independiente

El SDK de PowerShell de Durable Functions (DF) ahora está disponible como módulo independiente en la Galería de PowerShell: AzureFunctions.PowerShell.Durable.SDK. Este SDK ya está disponible con carácter general (GA) y es el enfoque 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.

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 DF SDK integrado en el trabajador de PowerShell permanecerá disponible para PowerShell 7.4 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.4 y posteriores de PowerShell, forzando al worker 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 mediante Dependencias administradaso agrupados con el contenido de la aplicación. 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' = '2.*'
}

Opción de instalación 2: incluir el módulo sdk en el contenido de la aplicación

Para incluir el SDK DF independiente en el contenido de la aplicación, debe seguir las instrucciones sobre la inclusión de módulos en el contenido de la 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.

Referencia de SDK

Consulte Módulo AzureFunctions.PowerShell.Durable.SDK para obtener la referencia completa de los cmdlets del SDK y sus parámetros.

También puede usar el Get-Help cmdlet para obtener descripciones detalladas de los cmdlets del SDK. Para ello, primero debe importar el módulo, como se muestra en la sección anterior. Después, puede ejecutar el siguiente comando para obtener toda la lista de cmdlets:

Get-Help *-Durable*

Para obtener ayuda detallada sobre un cmdlet específico, incluidos ejemplos de uso, ejecute:

Get-Help Invoke-DurableOrchestration -Full

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 es un nuevo cmdlet que permite a los usuarios usar suborchestrators en sus flujos de trabajo.
  • Suspend-DurableOrchestration y Resume-DurableOrchestration son nuevos cmdlets que permiten a los usuarios suspender y reanudar orquestaciones, respectivamente.

Cmdlets modificados

  • El Get-DurableTaskResult cmdlet ahora solo acepta una sola tarea como argumento, en lugar de aceptar una lista de tareas.
  • Se cambia el nombre del New-DurableRetryOptions cmdlet a New-DurableRetryPolicy (se proporciona un alias para el nombre anterior para la compatibilidad con versiones anteriores).

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.

Obtener soporte técnico y proporcionar comentarios

Informe de los comentarios y sugerencias al repositorio de GitHub del SDK.