Guía del desarrollador de PowerShell para Azure Functions

En este artículo se proporcionan detalles sobre cómo escribir en Azure Functions con PowerShell.

Una función de Azure de PowerShell (función) se representa como un script de PowerShell que se ejecuta cuando se desencadena. Cada script de función tiene un archivo function.json relacionado donde se define el comportamiento de la función, como su desencadenamiento y sus parámetros de entrada y salida. Para más información, consulte el artículo sobre los desencadenadores y los enlaces.

Al igual que otros tipos de funciones, las funciones de script de PowerShell toman parámetros que coinciden con los nombres de todos los enlaces de entrada definidos en el archivo function.json. También se pasa un parámetro TriggerMetadata que contiene información adicional sobre el desencadenador que inició la función.

En este artículo se supone que ya ha leído Referencia para desarrolladores de Azure Functions. También se asume que completó el inicio rápido de Functions para PowerShell para crear su primera función de PowerShell.

Estructura de carpetas

La estructura de carpetas necesaria para un proyecto de PowerShell tiene el siguiente aspecto. Este valor predeterminado se puede cambiar. Para más información, consulte la sección scriptFile.

PSFunctionApp
 | - MyFirstFunction
 | | - run.ps1
 | | - function.json
 | - MySecondFunction
 | | - run.ps1
 | | - function.json
 | - Modules
 | | - myFirstHelperModule
 | | | - myFirstHelperModule.psd1
 | | | - myFirstHelperModule.psm1
 | | - mySecondHelperModule
 | | | - mySecondHelperModule.psd1
 | | | - mySecondHelperModule.psm1
 | - local.settings.json
 | - host.json
 | - requirements.psd1
 | - profile.ps1
 | - extensions.csproj
 | - bin

En la raíz del proyecto, hay un archivo host.json compartido que se puede usar para configurar la aplicación de función. Cada función tiene una carpeta con su propio archivo de código (.ps1) y archivo de configuración de enlace (function.json). El nombre del directorio primario del archivo function.json es siempre es el nombre de la función.

Determinados enlaces requieren la presencia de un archivo extensions.csproj. Las extensiones de enlace necesarias en la versión 2.x y posteriores del entorno en tiempo de ejecución de Functions se definen en el archivo extensions.csproj, con los archivos de biblioteca reales de la carpeta bin. Al desarrollar de forma local, debe registrar las extensiones de enlace. Al desarrollar funciones en Azure Portal, este registro se realiza automáticamente.

En las aplicaciones de funciones de PowerShell, podría tener opcionalmente un profile.ps1 que se ejecute cuando una aplicación de funciones empiece a ejecutarse (lo que también se conoce como arranque en frío). Para más información, consulte el Perfil de PowerShell.

Definición de un script de PowerShell como función

De forma predeterminada, el tiempo de ejecución de Functions busca la función en run.ps1, donde run.ps1 comparte el mismo directorio primario que su function.json correspondiente.

Varios argumentos se pasan al script durante la ejecución. Para controlar estos parámetros, agregue un bloque param a la parte superior del script como en el siguiente ejemplo:

# $TriggerMetadata is optional here. If you don't need it, you can safely remove it from the param block
param($MyFirstInputBinding, $MySecondInputBinding, $TriggerMetadata)

Parámetro TriggerMetadata

El parámetro TriggerMetadata se usa para proporcionar información adicional acerca del desencadenador. Estos metadatos varían de un enlace a otro, pero todos ellos contienen una propiedad sys con los siguientes datos:

$TriggerMetadata.sys

Propiedad	Descripción	Tipo
UtcNow	Cuándo se desencadenó la función (en formato UTC)	DateTime
MethodName	Nombre de la función desencadenada	string
RandGuid	GUID único para esta ejecución de la función	string

Cada tipo de desencadenador tiene un conjunto diferente de metadatos. Por ejemplo, $TriggerMetadata para QueueTrigger contiene InsertionTime, Id y DequeueCount, entre otras cosas. Para más información sobre los metadatos del desencadenador de cola, vaya a la documentación oficial de los desencadenadores de cola. Consulte la documentación sobre los desencadenadores con los que está trabajando para ver lo que está incluido en los metadatos de desencadenador.

Enlaces

En PowerShell, los enlaces se configuran y definen en el archivo function.json de una función. Functions interactúa con los enlaces de varias maneras.

Lectura de datos del desencadenador y de entrada

Los desencadenadores y los enlaces de entrada se leen como parámetros que se pasan a la función. Los enlaces de entrada tienen un direction establecido en in en function.json. La propiedad name definida en function.json es el nombre del parámetro, en el bloque param. Dado que PowerShell utiliza parámetros con nombre para el enlace, no importa el orden de estos. Sin embargo, es un procedimiento recomendado seguir el orden de los enlaces definidos en el archivo function.json.

param($MyFirstInputBinding, $MySecondInputBinding)

Escritura de datos de salida

En Functions, un enlace de salida tiene un direction establecido en out en el archivo function.json. Puede escribir en un enlace de salida mediante el cmdlet Push-OutputBinding, disponible para Functions Runtime. En cualquier caso, la propiedad name del enlace tal como se define en function.json corresponde al parámetro Name del cmdlet Push-OutputBinding.

En el ejemplo siguiente se muestra cómo llamar a Push-OutputBinding en el script de la función:

param($MyFirstInputBinding, $MySecondInputBinding)

Push-OutputBinding -Name myQueue -Value $myValue

También puede pasar un valor para un enlace específico mediante la canalización.

param($MyFirstInputBinding, $MySecondInputBinding)

Produce-MyOutputValue | Push-OutputBinding -Name myQueue

Push-OutputBinding se comporta de forma distinta según el valor especificado para -Name:

• Cuando no se pueda resolver el nombre especificado en un enlace de salida válido, se producirá un error.

• Cuando el enlace de salida acepta una colección de valores, puede llamar a Push-OutputBinding varias veces para insertar varios valores.

• Cuando el enlace de salida solo acepta un valor singleton, volver a llamar aPush-OutputBinding produce un error.

Sintaxis de Push-OutputBinding

Los siguientes son parámetros válidos para llamar a Push-OutputBinding:

Nombre	Tipo	Posición	Descripción
-Name	String	1	Nombre del enlace de salida que quiere establecer.
-Value	Object	2	Valor del enlace de salida que desea establecer, aceptado desde la canalización ByValue.
-Clobber	SwitchParameter	con nombre	(Opcional) Cuando se especifica, se fuerza el establecimiento del valor para un enlace de salida especificado.

También se admiten los siguientes parámetros habituales:

• Verbose
• Debug
• ErrorAction
• ErrorVariable
• WarningAction
• WarningVariable
• OutBuffer
• PipelineVariable
• OutVariable

Para más información, consulte About Common Parameters (Acerca de los parámetros habituales).

Ejemplo de Push-OutputBinding: Respuestas HTTP

Un desencadenador HTTP devuelve una respuesta con un enlace de salida denominado response. En el siguiente ejemplo, el enlace de salida de response tiene el valor de "output #1":

PS >Push-OutputBinding -Name response -Value ([HttpResponseContext]@{
    StatusCode = [System.Net.HttpStatusCode]::OK
    Body = "output #1"
})

Dado que la salida es HTTP, que acepta solo un valor singleton, al volver a llamar a Push-OutputBinding se produce un error.

PS >Push-OutputBinding -Name response -Value ([HttpResponseContext]@{
    StatusCode = [System.Net.HttpStatusCode]::OK
    Body = "output #2"
})

Para las salidas que solo aceptan valores singleton, puede usar el parámetro -Clobber para invalidar el antiguo valor en lugar de intentar agregarlo a una colección. En el siguiente ejemplo se da por supuesto que ya ha agregado un valor. Mediante el uso de -Clobber, la respuesta de ejemplo siguiente invalida el valor existente para devolver un valor de "output #3":

PS >Push-OutputBinding -Name response -Value ([HttpResponseContext]@{
    StatusCode = [System.Net.HttpStatusCode]::OK
    Body = "output #3"
}) -Clobber

Ejemplo de Push-OutputBinding: Enlace de salida de cola

Push-OutputBinding se usa para enviar datos a los enlaces de salida como enlace de salida de Azure Queue Storage. En el siguiente ejemplo, el mensaje que se escribe en la cola tiene un valor de "output #1":

PS >Push-OutputBinding -Name outQueue -Value "output #1"

El enlace de salida para una cola de Storage acepta varios valores de salida. En este caso, llamar al siguiente ejemplo después del primero hace que se escriba en la cola una lista con dos elementos: "output #1" y "output #2".

PS >Push-OutputBinding -Name outQueue -Value "output #2"

Cuando se llama al siguiente ejemplo después de los dos anteriores, se agregan dos valores más a la colección de salida:

PS >Push-OutputBinding -Name outQueue -Value @("output #3", "output #4")

Cuando se escribe en la cola, el mensaje contiene estos cuatro valores: "output #1", "output #2", "output #3" y "output #4".

Cmdlet Get-OutputBinding

Puede usar el cmdlet Get-OutputBinding para recuperar los valores establecidos actualmente para los enlaces de salida. Este cmdlet recupera una tabla hash que contiene los nombres de los enlaces de salida con sus respectivos valores.

El siguiente es un ejemplo del uso de Get-OutputBinding para devolver valores de enlace actuales:

Get-OutputBinding

Name                           Value
----                           -----
MyQueue                        myData
MyOtherQueue                   myData

Get-OutputBinding también contiene un parámetro denominado -Name que se puede usar para filtrar el enlace devuelto, como en el siguiente ejemplo:

Get-OutputBinding -Name MyQ*

Name                           Value
----                           -----
MyQueue                        myData

En Get-OutputBinding se admiten caracteres comodín (*).

Registro

El inicio de sesión en las funciones de PowerShell funciona como el inicio de sesión normal de PowerShell. Puede usar los cmdlets de registro para escribir en cada flujo de salida. Cada cmdlet se asigna a un nivel de registro utilizado por Functions.

Nivel de registro de Functions	cmdlet de registro
Error	Write-Error
Advertencia	Write-Warning
Information	Write-Information Write-Host Write-Output Escribe en el nivel de registro Information.
Depurar	Write-Debug
Seguimiento	Write-Progress Write-Verbose

Además de estos cmdlets, todo lo escrito en la canalización se redirige al nivel de registro Information y se muestra con el formato predeterminado de PowerShell.

Importante

El uso de los cmdlets Write-Verbose o Write-Debug no es suficiente para ver los niveles de registro detallado y de depuración. También debe configurar el umbral de nivel de registro que declara qué nivel de registro es realmente importante para usted. Para más información, consulte el artículo de Configuración del nivel de registro de la aplicación de funciones.

Configuración del nivel de registro de la aplicación de funciones

Azure Functions permite definir el nivel umbral para facilitar el control de la manera en que Functions escribe en los registros. Para establecer el umbral para todos los seguimientos que se escriben en la consola, use la propiedad logging.logLevel.default en el archivo host.json. Esta configuración se aplica a todas las funciones de Function App.

En el siguiente ejemplo se establece el umbral para habilitar el registro detallado para todas las funciones, pero establece el umbral para habilitar el registro de depuración para una función denominada MyFunction:

{
    "logging": {
        "logLevel": {
            "Function.MyFunction": "Debug",
            "default": "Trace"
        }
    }
}  

Para más información, consulte la Referencia de host.json.

Visualización de los registros

Si la aplicación de funciones se ejecuta en Azure, puede usar Application Insights para supervisarla. Consulte cómo supervisar Azure Functions para obtener más información sobre cómo ver y consultar registros de la función.

Si la aplicación de funciones se ejecuta localmente para el desarrollo, los registros están de manera predeterminada en el sistema de archivos. Para ver los registros en la consola, establezca la variable de entorno AZURE_FUNCTIONS_ENVIRONMENT en Development antes de iniciar la aplicación de funciones.

Tipos de desencadenadores y enlaces

Hay muchos desencadenadores y enlaces disponibles para usar con la aplicación de funciones. La lista completa de los desencadenadores y enlaces se encuentra aquí.

Todos los desencadenadores y enlaces se representan en código como tipos de datos reales:

• Hashtable
• string
• byte[]
• int
• double
• HttpRequestContext
• HttpResponseContext

Los cinco primeros tipos de esta lista son tipos de .NET estándar. Los dos últimos los usa únicamente el desencadenador HttpTrigger.

Todos los parámetros de enlace de las funciones deben ser de uno de estos tipos.

Desencadenadores y enlaces HTTP

Los desencadenadores HTTP y de webhook trigger y los enlaces de salida HTTP usan objetos de solicitud y respuesta para representar la mensajería HTTP.

Objeto de solicitud

El objeto de solicitud que se pasa al script es del tipo HttpRequestContext, con las siguientes propiedades:

Propiedad	Descripción	Tipo
Body	Objeto que contiene el cuerpo de la solicitud. Body se serializa al mejor tipo en función de los datos. Por ejemplo, si los datos son JSON, se pasa como tabla hash. Si los datos están una cadena, se pasan en forma de cadena.	object
Headers	Diccionario que contiene los encabezados de la solicitud.	Dictionary<string,string>*
Method	Método HTTP de la solicitud.	string
Params	Objeto que contiene los parámetros de enrutamiento de la solicitud.	Dictionary<string,string>*
Query	Objeto que contiene los parámetros de consulta.	Dictionary<string,string>*
Url	Dirección URL de la solicitud.	string

^*Todas las claves Dictionary<string,string> distinguen mayúsculas de minúsculas.

Objeto de respuesta

El objeto de respuesta que debe enviar de vuelta es de tipo HttpResponseContext, que tiene las siguientes propiedades:

Propiedad	Descripción	Tipo
Body	Objeto que contiene el cuerpo de la respuesta.	object
ContentType	Una mano corta para establecer el tipo de contenido para la respuesta.	string
Headers	Objeto que contiene los encabezados de la respuesta.	Diccionario o tabla hash
StatusCode	Código de estado HTTP de la respuesta.	cadena o entero

Acceso a solicitudes y respuestas

Al trabajar con desencadenadores HTTP, puede acceder a la solicitud HTTP del mismo modo que lo haría con cualquier otro enlace de entrada. Se encuentra en el bloque param.

Use un objeto HttpResponseContext para devolver una respuesta, tal y como se muestra en el ejemplo siguiente:

function.json

{
  "bindings": [
    {
      "type": "httpTrigger",
      "direction": "in",
      "authLevel": "anonymous"
    },
    {
      "type": "http",
      "direction": "out",
      "name": "Response"
    }
  ]
}

run.ps1

param($req, $TriggerMetadata)

$name = $req.Query.Name

Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{
    StatusCode = [System.Net.HttpStatusCode]::OK
    Body = "Hello $name!"
})

El resultado de invocar esta función sería:

PS > irm http://localhost:5001?Name=Functions
Hello Functions!

Conversión de tipos de desencadenadores y enlaces

Para determinados enlaces como el enlace de blobs, podrá especificar el tipo del parámetro.

Por ejemplo, para que los datos de Blob Storage se proporcionen como cadena, agregue la siguiente conversión de tipo de mi bloque param:

param([string] $myBlob)

Perfil de PowerShell

En PowerShell, existe el concepto de "perfil de PowerShell". Si no está familiarizado con los perfiles de PowerShell, consulte About profiles (Acerca de los perfiles).

En las funciones de PowerShell, el script de perfil se ejecuta una vez por instancia de trabajo de PowerShell en la aplicación cuando se implementa por primera vez y después de estar inactivo (arranque en frío. Cuando se habilita la simultaneidad estableciendo el valor PSWorkerInProcConcurrencyUpperBound, el script de perfil se ejecuta para cada espacio de ejecución creado.

Al crear una aplicación de funciones con herramientas como Visual Studio Code y Azure Functions Core Tools, el profile.ps1 predeterminado se crea automáticamente. El perfil predeterminado se mantiene en el repositorio de GitHub de Core Tools y contiene:

• La autenticación automática de MSI en Azure.
• La capacidad de activar los alias de PowerShell para AzureRM de Azure PowerShell, si lo desea.

Versiones de PowerShell

En la tabla siguiente se muestran las versiones de PowerShell disponibles para cada versión principal de Functions Runtime, así como la versión necesaria de .NET:

Versión de Functions	Versión de PowerShell	Versión de .NET
4.x	PowerShell 7.4	.NET 8
4.x	PowerShell 7.2 (finalización de la compatibilidad)	.NET 6

Puede ver la versión actual mediante la impresión de $PSVersionTable desde cualquier función.

Para más información sobre la directiva de compatibilidad con el entorno de ejecución de Azure Functions, consulte este artículo.

Nota:

La compatibilidad con PowerShell 7.2 en Azure Functions finaliza el 8 de noviembre de 2024. Es posible que tenga que resolver algunos cambios importantes al actualizar las funciones de PowerShell 7.2 para que se ejecuten en PowerShell 7.4. Siga esta guía de migración para actualizar a PowerShell 7.4.

Ejecución local en una versión específica

Al ejecutar las funciones de PowerShell localmente, debe agregar la configuración "FUNCTIONS_WORKER_RUNTIME_VERSION" : "7.4" a la matriz Values en el archivo local.setting.json en la raíz del proyecto. Cuando se ejecuta localmente en PowerShell 7.4, el archivo de local.settings.json es similar al ejemplo siguiente:

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "",
    "FUNCTIONS_WORKER_RUNTIME": "powershell",
    "FUNCTIONS_WORKER_RUNTIME_VERSION" : "7.4"
  }
}

Nota:

En funciones de PowerShell, el valor "~7" para FUNCTIONS_WORKER_RUNTIME_VERSION hace referencia a "7.0.x". No actualizamos automáticamente las aplicaciones de funciones de PowerShell que tienen "~7" a "7.4". En el futuro, para las aplicaciones de funciones de PowerShell, es necesario que las aplicaciones especifiquen la versión principal y secundaria que quieren tener como destino. Por lo tanto, es necesario mencionar "7.4" si desea dirigirse a "7.4.x"

Cambio de la versión de PowerShell

Tenga en cuenta estas consideraciones antes de migrar la aplicación de funciones de PowerShell a PowerShell 7.4:

• Dado que la migración podría introducir cambios importantes en la aplicación, revise esta guía de migración antes de actualizar la aplicación a PowerShell 7.4.

• Asegúrese de que la aplicación de funciones se ejecuta en la versión más reciente del entorno de ejecución de Functions en Azure, que es la versión 4.x. Para obtener más información, vea Ver y actualizar la versión actual del entorno de ejecución.

Siga estos pasos para cambiar la versión de PowerShell que usa la aplicación de funciones. Realice esta operación en Azure Portal o mediante PowerShell.

Portal

1. En Azure Portal, vaya a la aplicación de función.

2. En las opciones de configuración haga clic en Configuración. En la pestaña Configuración general, busque la versión de PowerShell.

   

3. Elija la versión de PowerShell Core que quiera y seleccione Guardar. Cuando se le advierta sobre el reinicio pendiente, elija Continuar. La aplicación de funciones se reinicia en la versión de PowerShell elegida.

Nota:

La compatibilidad de Azure Functions con PowerShell 7.4 está disponible con carácter general (GA). Es posible que vea PowerShell 7.4 todavía indicado como versión preliminar en Azure Portal, pero esto se actualizará pronto para reflejar el estado de disponibilidad general.

PowerShell

Ejecute el siguiente script para cambiar la versión de PowerShell:

Set-AzResource -ResourceId "/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/providers/Microsoft.Web/sites/<FUNCTION_APP>/config/web" -Properties @{  powerShellVersion  = '<VERSION>' } -Force -UsePatchSemantics

Reemplace <SUBSCRIPTION_ID>, <RESOURCE_GROUP> y <FUNCTION_APP> por el identificador de la suscripción de Azure, el nombre del grupo de recursos y la aplicación de funciones, respectivamente. Además, reemplace <VERSION> por 7.4. Puede comprobar el valor actualizado de la configuración powerShellVersion en Properties de la tabla hash devuelta.

La aplicación de funciones se reinicia después de realizar el cambio en la configuración.

Administración de dependencias

La administración de módulos en Azure Functions escritos en PowerShell se puede abordar de dos maneras: mediante la característica de dependencias administradas o la inclusión de los módulos directamente en el contenido de la aplicación. Cada método tiene sus propias ventajas y elegir la adecuada depende de sus necesidades específicas.

Elección del enfoque adecuado de administración de módulos

¿Por qué usar la característica de dependencias administradas?

• Instalación inicial simplificada: controla automáticamente la instalación del módulo en función del archivo requirements.psd1.
• Actualizaciones automáticas: los módulos se actualizan automáticamente sin necesidad de intervención manual, incluyendo las correcciones de seguridad.

¿Por qué incluir módulos en el contenido de la aplicación?

• Ninguna dependencia de la Galería de PowerShell: los módulos se agrupan con la aplicación, lo que elimina las dependencias externas.
• Más control: se evita el riesgo de regresiones causadas por actualizaciones automáticas, lo que proporciona control total sobre qué versiones de módulo se usan.
• Compatibilidad: funciona en Consumo flexible y se recomienda para otras SKU de Linux.

Característica de dependencias administradas

La característica de dependencias administradas permite a Azure Functions descargar y administrar automáticamente los módulos de PowerShell especificados en el archivo requirements.psd1. Esta característica se habilita de manera predeterminada en las nuevas aplicaciones de funciones de PowerShell.

Configuración de requirements.psd1

Para usar las dependencias administradas en Azure Functions con PowerShell, es necesario configurar un archivo requirements.psd1. Este archivo especifica los módulos que requiere la función, y Azure Functions descarga y actualiza automáticamente estos módulos para asegurarse de que el entorno permanezca actualizado.

Aquí se muestra cómo configurar el archivo requirements.psd1:

1. Cree un archivo requirements.psd1 en el directorio raíz de Azure Functions en caso de que aún no exista uno.
2. Defina los módulos y sus versiones en una estructura de datos de PowerShell.

Archivo requirements.psd1 de ejemplo:

@{
    'Az' = '9.*'  # Specifies the Az module and will use the latest version with major version 9
}

Inclusión de módulos en el contenido de la aplicación

Para disfrutar de más control sobre las versiones de los módulos y evitar dependencias en recursos externos, incluya los módulos directamente en el contenido de la aplicación de funciones.

Para incluir módulos personalizados:

1. Cree una carpeta Modules en la raíz de la aplicación de funciones.

   mkdir ./Modules
   

2. Copie los módulos en la carpeta Modules con uno de los métodos siguientes:

   • Si los módulos ya estuvieran disponibles localmente:

     Copy-Item -Path /mymodules/mycustommodule -Destination ./Modules -Recurse
     

   • Uso de Save-Module para recuperar desde la Galería de PowerShell:

     Save-Module -Name MyCustomModule -Path ./Modules
     

   • Uso de Save-PSResource del módulo PSResourceGet:

     Save-PSResource -Name MyCustomModule -Path ./Modules
     

La aplicación de funciones debería tener la estructura siguiente:

PSFunctionApp
 | - MyFunction
 | | - run.ps1
 | | - function.json
 | - Modules
 | | - MyCustomModule
 | | - MyOtherCustomModule
 | | - MySpecialModule.psm1
 | - local.settings.json
 | - host.json
 | - requirements.psd1

Al inicia la aplicación de funciones, el trabajo de lenguaje de PowerShell agrega esta carpeta Modules a $env:PSModulePath, de manera que pueda confiar en la carga automática del módulo del mismo modo que lo haría en un script de PowerShell normal.

Solución de problemas de las dependencias administradas

Habilitación de las dependencias administradas

Para que las dependencias administradas funcionen, la característica debe estar habilitada en host.json:

{
  "managedDependency": {
          "enabled": true
       }
}

Versiones de destino específicas

Al enfocarse en versiones de módulo específicas, es importante que siga los dos pasos siguientes para asegurarse de que se cargue la versión correcta del módulo:

1. Especificar la versión del módulo en requirements.psd1:

   @{
     'Az.Accounts' = '1.9.5'
   }
   

2. Adición de instrucciones de importación en profile.ps1:

   Import-Module Az.Accounts -RequiredVersion '1.9.5'
   

Al seguir estos pasos se garantiza que se cargue la versión especificada al iniciar la función.

Establecer la configuración específica del intervalo de dependencia administrada

Es posible configurar cómo se descargan e instalan las dependencias administradas con las siguientes opciones de configuración de la aplicación:

Configuración	Valor predeterminado	Descripción
MDMaxBackgroundUpgradePeriod	7.00:00:00 (siete días)	Controla el período de actualización en segundo plano para las aplicaciones de funciones de PowerShell.
MDNewSnapshotCheckPeriod	01:00:00 (una hora)	Especifica la frecuencia con la que el trabajo de PowerShell comprobará que haya actualizaciones.
MDMinBackgroundUpgradePeriod	1.00:00:00 (un día)	Tiempo mínimo entre comprobaciones de actualizaciones.

Consideraciones de administración de dependencias

• Acceso a Internet: las dependencias administradas requieren acceso a https://www.powershellgallery.com para descargar módulos. Asegúrese de que el entorno permita este acceso, incluyendo la modificación de reglas de firewall o red virtual, según sea necesario.
• Aceptación de licencias: las dependencias administradas no admiten módulos que requieran la aceptación de licencias.
• Plan de consumo flexible: la característica de dependencias administradas no se admite en el plan de consumo flexible. Uso de módulos personalizados en su lugar.
• Ubicaciones de módulos: en el equipo local, los módulos se instalan normalmente en una de las carpetas disponibles a nivel global en $env:PSModulePath. Al ejecutarse en Azure, el $env:PSModulePath de una aplicación de funciones de PowerShell difiere de $env:PSModulePath en un script de PowerShell normal y contendrá tanto la carpeta Modules cargada con el contenido de la aplicación como una ubicación independiente administrada por las dependencias administradas.

Variables de entorno

En Functions, la configuración de la aplicación, como las cadenas de conexión del servicio, se exponen como variables de entorno durante la ejecución. Puede acceder a esta configuración mediante $env:NAME_OF_ENV_VAR, como se muestra en el siguiente ejemplo:

param($myTimer)

Write-Host "PowerShell timer trigger function ran! $(Get-Date)"
Write-Host $env:AzureWebJobsStorage
Write-Host $env:WEBSITE_SITE_NAME

Hay varias maneras de agregar, actualizar y eliminar opciones de configuración de la aplicación de función:

• En Azure Portal.
• Mediante la CLI de Azure.
• Mediante Azure PowerShell.

Para aplicar los cambios realizados en la configuración de la aplicación de funciones, es necesario reiniciar la aplicación de funciones.

Cuando se ejecuta localmente, la configuración de la aplicación se lee desde el archivo del proyecto local.settings.json.

Simultaneidad

De forma predeterminada, Function Runtime de PowerShell solo puede procesar una invocación de función a la vez. Sin embargo, este nivel de simultaneidad podría no ser suficiente en las siguientes situaciones:

• Al intentar controlar un gran número de invocaciones a la vez.
• Al disponer de funciones que invocan a otras dentro de la misma aplicación de funciones.

Hay algunos modelos de simultaneidad que se pueden explorar según el tipo de carga de trabajo:

• Aumente FUNCTIONS_WORKER_PROCESS_COUNT. El aumento de esta configuración permitirá controlar las invocaciones de funciones en varios procesos dentro de la misma instancia, lo que presenta cierta sobrecarga de CPU y memoria. En general, esta sobrecarga no afecta a las funciones enlazadas a E/S. En el caso de las funciones enlazadas a la CPU, el impacto puede ser significativo.

• Aumente el valor de la configuración de aplicación PSWorkerInProcConcurrencyUpperBound. El aumento de esta configuración permite crear varios espacios de ejecución en el mismo proceso, lo que reduce significativamente la sobrecarga de CPU y memoria.

Establezca estas variables de entorno en la configuración de la aplicación de la aplicación de funciones.

En función del caso de uso, Durable Functions puede mejorar significativamente la escalabilidad. Para obtener más información, vea Patrones de aplicación de Durable Functions.

Nota

Puede obtener advertencias que indiquen que "las solicitudes están en cola porque no hay espacios de ejecución disponibles". Tenga en cuenta que esto no es un error. El mensaje indica que las solicitudes se van a poner en cola y se controlarán cuando se completen las solicitudes anteriores.

Consideraciones para usar la simultaneidad

De forma predeterminada, PowerShell es un lenguaje de scripting uniproceso. Sin embargo, la simultaneidad puede agregarse mediante el uso de varios espacios de ejecución de PowerShell en el mismo proceso. El número de espacios de ejecución creados y, por tanto, el número de subprocesos simultáneos por trabajo está limitado por la configuración de la aplicación PSWorkerInProcConcurrencyUpperBound. De forma predeterminada, el número de espacios de ejecución se establece en 1000 en la versión 4.x del entorno de ejecución de Functions. En las versiones 3.x y posteriores, el número máximo de espacios de ejecución se establece en 1. El rendimiento de la aplicación de funciones se ve afectado por la cantidad de CPU y memoria disponibles en el plan seleccionado.

Azure PowerShell usa algunos procesos y estados de nivel de proceso para que no tenga que escribir tanto. Sin embargo, si activa la simultaneidad en la aplicación de funciones e invoca acciones que cambien el estado, puede acabar con las condiciones de carrera. Estas condiciones de carrera son difíciles de depurar, ya que una invocación se basa en un estado determinado y la otra ha cambiado el estado.

La simultaneidad es muy valiosa con Azure PowerShell, ya que algunas operaciones pueden tardar un tiempo considerable. Sin embargo, debe proceder con precaución. Si sospecha que está experimentando una condición de carrera, establezca la configuración de la aplicación PSWorkerInProcConcurrencyUpperBound en 1 y, en su lugar, use el aislamiento de nivel de proceso de trabajo de lenguaje para la simultaneidad.

Configuración de la función scriptdFile

De forma predeterminada, se ejecuta una función de PowerShell desde run.ps1, un archivo que comparte el mismo directorio primario que su archivo function.json correspondiente.

La propiedad scriptFile de function.json se puede usar para obtener una estructura de carpetas que tenga el aspecto del siguiente ejemplo:

FunctionApp
 | - host.json
 | - myFunction
 | | - function.json
 | - lib
 | | - PSFunction.ps1

En este caso, el archivo function.json para myFunction incluye una propiedad scriptFile que hace referencia al archivo con la función exportada que se va a ejecutar.

{
  "scriptFile": "../lib/PSFunction.ps1",
  "bindings": [
    // ...
  ]
}

Uso de módulos de PowerShell mediante la configuración de entryPoint

Las funciones de PowerShell de este artículo se muestran en el archivo de script run.ps1 predeterminado generado por las plantillas. Sin embargo, también puede incluir las funciones en módulos de PowerShell. Puede hacer referencia a su código de función específico del módulo mediante los campos scriptFile y entryPoint del archivo de configuración function.json.

En este caso, entryPoint es el nombre de una función o un cmdlet del módulo de PowerShell a los que se hace referencia en scriptFile.

Considere la siguiente estructura de carpetas:

FunctionApp
 | - host.json
 | - myFunction
 | | - function.json
 | - lib
 | | - PSFunction.psm1

Donde PSFunction.psm1 contiene:

function Invoke-PSTestFunc {
    param($InputBinding, $TriggerMetadata)

    Push-OutputBinding -Name OutputBinding -Value "output"
}

Export-ModuleMember -Function "Invoke-PSTestFunc"

En este ejemplo, la configuración de myFunction incluye una propiedad scriptFile que hace referencia a PSFunction.psm1, que es un módulo de PowerShell de otra carpeta. La propiedad entryPoint hace referencia a la función Invoke-PSTestFunc, que es el punto de entrada del módulo.

{
  "scriptFile": "../lib/PSFunction.psm1",
  "entryPoint": "Invoke-PSTestFunc",
  "bindings": [
    // ...
  ]
}

Con esta configuración, Invoke-PSTestFunc se ejecuta exactamente como lo haría run.ps1.

Consideraciones para las funciones de PowerShell

Al trabajar con las funciones de PowerShell, tenga en cuenta las consideraciones de las siguientes secciones.

Arranque en frío

Al desarrollar Azure Functions en el modelo de hospedaje sin servidor, los arranques en frío son una realidad. El arranque en frío se refiere al período de tiempo tarda la aplicación de funciones en empezar a ejecutarse para procesar una solicitud. El arranque en frío se produce con mayor frecuencia en el plan Consumo, puesto que la aplicación de funciones se cierra durante los períodos de inactividad.

Evitar el uso de Install-Module

La ejecución de Install-Module en el script de funciones en cada invocación puede provocar problemas de rendimiento. En su lugar, use Save-Module o Save-PSResource antes de publicar la aplicación de funciones para agrupar los módulos necesarios.

Para obtener más información, consulte la sección Administración de dependencias.

Pasos siguientes

Para obtener más información, consulte los siguientes recursos:

• Procedimientos recomendados para Azure Functions
• Referencia para desarrolladores de Azure Functions
• Enlaces y desencadenadores de Azure Functions