Introduction

Azure Functions provides a serverless compute experience that allows you to run small pieces of code, called "functions," without explicitly provisioning or managing infrastructure. The PowerShell programming model enables you to leverage your existing PowerShell scripting skills within the Azure Functions environment.

Key benefits include:

• Familiarity: Use the PowerShell language you know and love.
• Integration: Seamlessly integrate with other Azure services and external APIs.
• Scalability: Automatically scales based on demand.
• Cost-Effective: Pay only for the compute time you consume.

Function Structure

A typical PowerShell Azure Function consists of a script file (e.g., run.ps1) and a function.json file that defines the function's triggers and bindings.

run.ps1

This script file contains the core logic of your function. It receives input data and returns output based on the configured triggers and bindings.

param($MyTimer, $MyQueueItem)

# Check if trigger data is available
if ($MyQueueItem) {
    Write-Host "PowerShell queue trigger function processed work item: $MyQueueItem"
    # Process the queue item...
} elseif ($MyTimer) {
    Write-Host "PowerShell timer trigger function executed at: $(Get-Date)"
    # Perform scheduled tasks...
} else {
    Write-Host "No trigger data received."
}

# Return output if applicable (e.g., to an output binding)
# Example: return "Processed: $MyQueueItem"

function.json

This JSON file defines the metadata for your function, including its entry point, trigger type, and input/output bindings. The file is located in a folder named after your function.

{
  "scriptFile": "run.ps1",
  "bindings": [
    {
      "name": "MyTimer",
      "type": "timerTrigger",
      "direction": "in",
      "schedule": "0 */5 * * * *"
    },
    {
      "name": "MyQueueItem",
      "type": "queueTrigger",
      "direction": "in",
      "queueName": "myqueue-items",
      "connection": "AzureWebJobsStorage"
    },
    {
      "name": "outputBlob",
      "type": "blob",
      "direction": "out",
      "path": "output-container/{queueTrigger}",
      "connection": "AzureWebJobsStorage"
    }
  ]
}

In this example:

• scriptFile specifies the PowerShell script to execute.
• The first binding is a timer trigger, set to run every 5 minutes. The input parameter name in run.ps1 is MyTimer.
• The second binding is a queue trigger, listening to the myqueue-items queue. The input parameter name is MyQueueItem.
• The third binding is a blob output, configured to write to a blob in the output-container, with the blob name derived from the queue trigger content. The parameter name for this output is implicitly handled by Azure Functions when using output bindings.

Triggers and Bindings

Triggers define how your function is invoked, while bindings simplify the integration with other services by providing declarative ways to connect to data and services.

• HTTP Trigger: Invokes your function via an HTTP request.
• Timer Trigger: Invokes your function on a schedule (CRON expression).
• Queue Trigger: Invokes your function when a message is added to a queue.
• Blob Trigger: Invokes your function when a blob is created or updated in Azure Blob Storage.

• HTTP Output: Returns an HTTP response.
• Blob Output: Writes data to Azure Blob Storage.
• Table Output: Writes data to Azure Table Storage.
• Queue Output: Adds a message to an Azure Storage Queue.
• DocumentDB/Cosmos DB Input/Output: Interact with Azure Cosmos DB.

You can find a comprehensive list of triggers and bindings in the Azure Functions triggers and bindings documentation.

Managing Dependencies

For PowerShell functions, you can manage external modules and dependencies using the requirements.psd1 file.

requirements.psd1

Place this file in the root of your function app project. It follows the standard PowerShell module manifest format.

#
# This file is used to install PowerShell modules for your Azure Functions.
# For more information, see: https://go.microsoft.com/fwlink/?LinkID=532799
#

# Specify module versions by listing them in the following format:
# Module = @{ ModuleName = 'RequiredVersion' }
# Example:
# Az = @{ Az = '2.0.0' }
# Pester = @{ Pester = '4.0.0' }

# Add your required modules here.
# For example, to include the Az module:
# Az = @{ Az = '5.0.0' }
# For a specific version:
# Az.Accounts = @{ Az.Accounts = '2.2.0' }

# If you don't need a specific version, just list the module name:
# SomeModule = 'SomeModule'

When your function app starts, Azure Functions will automatically install the modules listed in requirements.psd1.

Input and Output Parameters

The param() block in your run.ps1 script is crucial for receiving input from triggers and bindings. The parameter names must match the name property defined in your function.json bindings.

Accessing Trigger Data

Trigger data is passed as parameters to your script. For example, a queue trigger item is often passed as a string or a JSON object.

param($MyQueueItem)

if ($MyQueueItem) {
    $data = ConvertFrom-Json $MyQueueItem -ErrorAction SilentlyContinue
    if ($data) {
        Write-Host "Processing data: $($data.id)"
    } else {
        Write-Host "Received raw queue item: $MyQueueItem"
    }
}

Setting Output Bindings

To write data to an output binding, you typically assign values to a special object that represents the output binding. This is often done implicitly by returning a value from the script if the output binding is the primary return value, or by using specific cmdlets provided by the Azure Functions host.

In many cases, you can simply return a value from your script:

param($MyQueueItem, $MyOutputBlob)

# ... process MyQueueItem ...

# If you have an output binding named 'MyOutputBlob' in function.json
# and it's configured to accept a string or JSON:
return "Successfully processed item: $MyQueueItem"

For more complex output scenarios, or when dealing with multiple output bindings, you might use dedicated output binding objects or cmdlets provided by the Azure Functions runtime.

Error Handling and Logging

Effective logging and error handling are vital for debugging and monitoring your functions.

Logging

Use standard PowerShell cmdlets like Write-Host, Write-Verbose, Write-Warning, and Write-Error. These outputs are captured by the Azure Functions runtime and are visible in Application Insights and the Kudu console.

Write-Host "Starting function execution."
Write-Verbose "Detailed information about the process."
Write-Warning "A potential issue was detected."
Write-Error "An unrecoverable error occurred."

Error Handling

Use try...catch blocks to gracefully handle exceptions.

try {
    # Code that might throw an error
    $result = Invoke-RestMethod -Uri "http://invalid.url"
    Write-Host "Successfully called external service."
} catch {
    Write-Error "An error occurred during external service call: $($_.Exception.Message)"
    # You can re-throw the exception if you want the function to fail
    # throw $_
}

Advanced Topics

• Custom Handlers: For more control over the execution environment, you can use custom handlers.
• Durable Functions: Orchestrate long-running, stateful workflows with PowerShell Durable Functions.
• Configuration: Manage application settings and connection strings via Application Settings in your Azure Function App.