Guía del SDK de PowerShell Durable Functions independiente

El SDK de PowerShell Durable Functions independiente (AzureFunctions.PowerShell.Durable.SDK) es el enfoque recomendado para crear aplicaciones Durable Functions con PowerShell. Reemplaza el SDK integrado por una lógica de reproducción más rápida (el mismo motor que el SDK aislado de C#), el control de versiones independiente y el control de excepciones mejorado, el control de valores NULL y la serialización. El SDK integrado permanece disponible para PowerShell 7.4 y versiones anteriores, pero se quitará en una futura versión principal del trabajador de PowerShell.

Lista de comprobación para la migración

Use la siguiente lista de comprobación para realizar un seguimiento del progreso en cada paso de migración:

Paso Section
1. Comprobación de los requisitos previos Requisitos previos
2. Habilitación del SDK independiente Habilitación del SDK independiente
3. Instalación del paquete del SDK Instalación del paquete del SDK
4. Importación del SDK Importación del SDK
5. Ejecución de la aplicación Ejecución de la aplicación
6. Revisar la interfaz y los cambios de comportamiento Migración desde el SDK integrado

Instalación del SDK independiente

Siga estos pasos para instalar y habilitar el SDK independiente en la aplicación existente.

Comprobación de los requisitos previos

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

Habilitación del SDK 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 deshabilita el SDK duradero integrado para las versiones 7.4 y posteriores de PowerShell, lo que obliga al trabajador 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 del paquete del SDK

Tiene dos opciones para instalar el paquete del SDK. Usa dependencias administradas (recomendadas para la mayoría de las aplicaciones) o agrupa el módulo con el contenido de la aplicación si necesitas anclar una versión específica o la implementación no admite dependencias administradas. Solo se necesita una opción.

Para instalar el SDK como una dependencia administrada, siga las instrucciones de las dependencias administradas. En primer lugar, asegúrese de que host.json contiene un apartado managedDependency con enabled configurado en true:

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

A continuación, especifique una entrada para el SDK en el archivo requirements.psd1.

# 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 2: Incluir el módulo sdk en el contenido de la aplicación

Para agrupar el SDK con la aplicación, coloque el paquete del SDK dentro de un ".\Modules" directorio en la raíz de la aplicación. Para obtener más información, consulte Inclusión de módulos en el contenido de la aplicación.

Desde la raíz de la aplicación, cree el directorio y descargue el SDK:

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

Importación del SDK

Agregue la siguiente línea al archivo profile.ps1 para importar el SDK en cada inicialización en frío:

Import-Module AzureFunctions.PowerShell.Durable.SDK -ErrorAction Stop

Ejecución de la aplicación

Inicie la aplicación con func host start. El SDK independiente ahora está activo.

Migración desde el SDK integrado

Si va a migrar una aplicación existente desde el SDK integrado, revise la siguiente interfaz y los cambios de comportamiento.

Nuevos cmdlets

Cmdlet Descripción
Invoke-DurableSubOrchestrator Invoque suborquestadores dentro de un flujo de trabajo de orquestador.
Suspend-DurableOrchestration Suspender una instancia de orquestación en ejecución.
Resume-DurableOrchestration Reanude una instancia de orquestación suspendida anteriormente.

Cmdlets modificados

Cambio Detalles
Get-DurableTaskResult Ahora acepta un único Task como argumento en lugar de una lista de tareas.
New-DurableRetryOptions → New-DurableRetryPolicy Se ha cambiado el nombre. Se proporciona un alias para el nombre anterior para la compatibilidad con versiones anteriores.

Cambios de comportamiento

Control de excepciones en Wait-DurableTask

Las excepciones lanzadas por actividades programadas con Wait-DurableTask (patrón fan-out/fan-in) ya no se ignoran silenciosamente. El cmdlet ahora propaga la excepción al orquestador para que pueda controlarla en el código.

SDK integrado — las excepciones se ignoraban silenciosamente:

# Exceptions from failed activities were lost
$tasks = @()
$tasks += Invoke-DurableActivity -FunctionName "RiskyActivity" -Input "item1" -NoWait
$tasks += Invoke-DurableActivity -FunctionName "RiskyActivity" -Input "item2" -NoWait
$results = Wait-DurableTask -Task $tasks
# No error even if an activity failed

SDK independiente : las excepciones se propagan al orquestador:

try {
    $tasks = @()
    $tasks += Invoke-DurableActivity -FunctionName "RiskyActivity" -Input "item1" -NoWait
    $tasks += Invoke-DurableActivity -FunctionName "RiskyActivity" -Input "item2" -NoWait
    $results = Wait-DurableTask -Task $tasks
} catch {
    # Handle the activity failure
    Write-Host "An activity failed: $_"
}

Valores nulos conservados en los resultados de Wait-DurableTask

Los valores NULL ya no se quitan de la lista de resultados de una Wait-DurableTask invocación (WhenAll). Una llamada correcta sin el indicador -Any ahora devuelve una matriz del mismo tamaño que el número de tareas programadas, incluidas las entradas $null para las actividades que devolvieron null.

SDK integrado: se eliminaron los resultados nulos.

# 3 tasks scheduled, but if one returned $null, results had only 2 items
$results = Wait-DurableTask -Task $tasks
$results.Count  # Could be 2 instead of 3

SDK independiente: se conservan los resultados nulos.

# 3 tasks scheduled, results always has 3 items
$results = Wait-DurableTask -Task $tasks
$results.Count  # Always 3, with $null for activities that returned null

Referencia de SDK

Para obtener la referencia completa del cmdlet, consulte AzureFunctions.PowerShell.Durable.SDK Module. Después de importar el módulo, también puede ejecutar Get-Help *-Durable* para mostrar todos los cmdlets disponibles, o Get-Help <cmdlet-name> -Full para obtener un uso detallado.

Obtener soporte técnico

Informe de errores y solicitudes de características en el repositorio GitHub del SDK.

Pasos siguientes

  • Last updated on