Guida per sviluppatori PowerShell per Funzioni di Azure

Questo articolo fornisce informazioni dettagliate su come scrivere Funzioni di Azure con PowerShell.

Una funzione di Azure di PowerShell (funzione) è rappresentata come uno script di PowerShell che viene eseguito quando viene attivato. Ogni script di funzione ha un file correlato function.json che definisce il comportamento della funzione, ad esempio il modo in cui viene attivato e i relativi parametri di input e output. Per altre informazioni, vedere l'articolo Trigger e binding.

Analogamente ad altri tipi di funzioni, le funzioni script di PowerShell accettano parametri che corrispondono ai nomi di tutti i binding di input definite nel file function.json. Viene inoltre passato un parametro TriggerMetadata che contiene informazioni aggiuntive sul trigger che ha avviato la funzione.

Questo articolo presuppone che siano già state lette le informazioni di riferimento per sviluppatori su Funzioni di Azure. È necessario aver completato anche la guida rapida di Funzioni per PowerShell per creare la prima funzione di PowerShell.

Struttura delle cartelle

La struttura di cartelle di output per un progetto PowerShell ha un aspetto simile alla seguente. Questa impostazione predefinita non può essere modificata. Per altre informazioni, vedere la sezione scriptFile di seguito.

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

Nella radice del progetto è presente un file host.json condiviso che può essere usato per configurare l'app per le funzioni. Per ogni funzione è presente una cartella con il file di codice (.ps1) e il file di configurazione dei binding (function.json) correlati. Il nome della directory padre del file di function.json è sempre il nome della funzione.

Alcune binding richiedono la presenza di un file extensions.csproj. Le estensioni di binding, richieste nella versione 2.x e successive del runtime di Funzioni, sono definite nel file extensions.csproj, con gli effettivi file di libreria inclusi nella cartella bin. Quando si sviluppa una funzione in locale, è necessario registrare le estensioni di associazione. Quando si sviluppano funzioni nel portale di Azure, la registrazione viene eseguita automaticamente.

Nelle app per le funzioni di PowerShell, è possibile che sia disponibile facoltativamente un oggetto profile.ps1 che viene eseguito quando un'app per le funzioni inizia a essere eseguita (altrimenti nota come avvio a freddo). Per altre informazioni, vedere profilo di PowerShell.

Definizione di uno script di PowerShell come funzione

Per impostazione predefinita, il runtime di Funzioni cerca la funzione in run.ps1, dove run.ps1 condivide la stessa directory padre del file function.json corrispondente.

Allo script vengono passati una serie di argomenti all'esecuzione. Per gestire questi parametri, aggiungere un blocco param all'inizio dello script come nell'esempio seguente:

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

Parametro TriggerMetadata

Il parametro TriggerMetadata viene usato per fornire informazioni aggiuntive sul trigger. I metadati aggiuntivi variano da binding a binding, ma contengono tutte una proprietà sys che contiene i dati seguenti:

$TriggerMetadata.sys

Proprietà	Descrizione	Tipo
UtcNow	Quando, in formato UTC, la funzione è stata attivata	Data/Ora
MethodName	Nome della funzione attivata	string
RandGuid	un guid univoco per questa esecuzione della funzione	string

Ogni tipo di trigger ha un set di metadati diverso. Ad esempio, $TriggerMetadata per QueueTrigger contiene InsertionTime, Id, DequeueCount, tra le altre cose. Per altre informazioni sui metadati del trigger della coda, vedere la documentazione ufficiale per i trigger della coda. Consultare la documentazione sui trigger con cui si sta lavorando per vedere cosa avviene all'interno dei metadati del trigger.

Bindings

In PowerShell, i binding vengono configurate e definite nel file function.json di una funzione. Le funzioni interagiscono con le associazioni in molti modi.

Lettura dei dati di trigger e di input

I trigger e i binding di input vengono letti come parametri passati alla funzione. I binding di input hanno un valore direction impostato su in in function.json. La proprietà name definita in function.json è il nome del parametro, nel blocco param. Poiché PowerShell usa parametri denominati per i binding, l'ordine dei parametri non è rilevante. Tuttavia, è consigliabile seguire l'ordine dei binding definite in function.json.

param($MyFirstInputBinding, $MySecondInputBinding)

Scrittura dei dati di output

In Funzioni, un binding d output ha direction impostato su out nella function.json. È possibile scrivere in un binding di output usando il cmdlet Push-OutputBinding, disponibile per il runtime di Funzioni. In tutti i casi, la proprietà name del binding come definito in function.json corrisponde al parametro Name del cmdlet Push-OutputBinding.

Di seguito, viene illustrato come chiamare Push-OutputBinding nello script della funzione:

param($MyFirstInputBinding, $MySecondInputBinding)

Push-OutputBinding -Name myQueue -Value $myValue

È anche possibile passare un valore per un binding specifica tramite la pipeline.

param($MyFirstInputBinding, $MySecondInputBinding)

Produce-MyOutputValue | Push-OutputBinding -Name myQueue

Push-OutputBinding si comporta in modo diverso in base al valore specificato per -Name:

• Quando il nome specificato non può essere risolto in un binding di output valida, viene generato un errore.

• Quando binding di output accetta una raccolta di valori, è possibile chiamare Push-OutputBinding ripetutamente per eseguire il push di più valori.

• Quando il binding di output accetta solo un valore singleton, chiamare Push-OutputBinding una seconda volta genera un errore.

Sintassi Push-OutputBinding

Di seguito sono riportati i parametri validi per la chiamata a Push-OutputBinding:

Nome	Type	Posizione	Descrizione
-Name	Stringa	1	Nome del binding di output da impostare.
-Value	Object	2	Valore del binding di output da impostare, accettato dalla pipeline ByValue.
-Clobber	SwitchParameter	denominata	(Facoltativo) Se specificato, forza l'impostazione del valore per un binding di output specificato.

Sono supportati anche i parametri comuni seguenti:

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

Per altre informazioni, vedere Informazioni su CommonParameters.

Esempio push-OutputBinding: risposte HTTP

Un trigger HTTP restituisce una risposta usando un binding di output denominato response. Nell'esempio seguente il binding di output di response ha il valore "output #1":

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

Poiché l'output è in HTTP, che accetta solo un valore singleton, viene generato un errore quando Push-OutputBinding viene chiamato una seconda volta.

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

Per gli output che accettano solo valori singleton, è possibile usare il parametro -Clobber per eseguire l'override del valore precedente anziché tentare di aggiungere a una raccolta. Nell'esempio seguente si presuppone che sia già stato aggiunto un valore. Usando -Clobber, la risposta dell'esempio seguente esegue l'override del valore esistente per restituire il valore "output #3":

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

Esempio push-OutputBinding: binding di output della coda

Push-OutputBinding viene usato per inviare dati ai binding di output, ad esempio un binding di output dell'archiviazione code di Azure. Nell'esempio seguente il messaggio scritto nella coda ha il valore "output #1":

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

Il binding di output per una coda di archiviazione accetta più valori di output. In questo caso, chiamando l'esempio seguente dopo la prima scrittura nella coda un elenco con due elementi: "output 1" e "output 2".

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

Nell'esempio seguente, quando viene chiamato dopo i due precedenti, vengono aggiunti altri due valori alla raccolta di output:

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

Quando viene scritto nella coda, il messaggio contiene questi quattro valori: "output #1", "output #2", "output #3" e "output #4".

Cmdlet Get-OutputBinding

È possibile usare il Get-OutputBinding cmdlet per recuperare i valori attualmente impostati per i binding di output. Questo cmdlet recupera una tabella hash contenente i nomi dei binding di output con i rispettivi valori.

Di seguito è riportato un esempio di utilizzo Get-OutputBinding per restituire i valori di binding correnti:

Get-OutputBinding

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

Get-OutputBinding contiene anche un parametro denominato -Name, che può essere usato per filtrare il binding restituito, come nell'esempio seguente:

Get-OutputBinding -Name MyQ*

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

I caratteri jolly (*) sono supportati in Get-OutputBinding.

Registrazione

La registrazione nelle funzioni di PowerShell funziona come la normale registrazione di PowerShell. È possibile usare i cmdlet di registrazione per scrivere in ogni flusso di output. Ogni cmdlet esegue il mapping a un livello di log usato da Funzioni.

Livello di registrazione delle funzioni	Cmdlet di registrazione
Errore	Write-Error
Avviso	Write-Warning
Informazioni	Write-Information Write-Host Write-Output Scrive al livello di log Information.
Debug	Write-Debug
Traccia	Write-Progress Write-Verbose

Oltre a questi cmdlet, qualsiasi elemento scritto nella pipeline viene reindirizzato al livello di log Information e visualizzato con la formattazione predefinita di PowerShell.

Importante

L'uso dei cmdlet Write-Verbose o Write-Debug non è sufficiente per visualizzare la registrazione dettagliata e a livello di debug. È anche necessario configurare la soglia a livello di log, che dichiara il livello di log di cui si è effettivamente preoccupati. Per altre informazioni, vedere Configurare il livello di log dell'app per le funzioni.

Configurare il livello di log dell'app per le funzioni

Funzioni di Azure consente di definire il livello di soglia per semplificare il controllo del modo in cui Funzioni scrive nei log. Per impostare la soglia per tutte le tracce scritte nella console, usare la proprietà logging.logLevel.default nel host.jsonfile. Questa impostazione si applica a tutte le funzioni dell'app per le funzioni.

L'esempio seguente imposta la soglia per abilitare la registrazione dettagliata per tutte le funzioni, ma imposta la soglia per abilitare la registrazione di debug per una funzione denominata MyFunction:

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

Per altre informazioni, vedere il riferimento su host.json.

Visualizzazione dei log

Se l'app per le funzioni è in esecuzione in Azure, è possibile usare Application Insights per monitorarla. Vedere Monitoraggio di Funzioni di Azure per altre informazioni sulla visualizzazione e sull'esecuzione di query su log di funzioni.

Se si esegue l'app per le funzioni in locale per lo sviluppo, i log vengono eseguiti per impostazione predefinita nel file system. Per visualizzare i log nella console, impostare la variabile di ambiente AZURE_FUNCTIONS_ENVIRONMENT su Development prima di avviare l'app per le funzioni.

Tipi di trigger e binding

Sono disponibili diversi trigger e binding da usare con l'app per le funzioni. L'elenco completo di trigger e binding è disponibile qui.

Tutti i trigger e i binding sono rappresentati nel codice come alcuni tipi di dati reali:

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

I primi cinque tipi in questo elenco sono tipi .NET standard. Gli ultimi due vengono usati solo dal trigger HttpTrigger.

Ogni parametro di binding nelle funzioni deve essere uno di questi tipi.

Trigger e associazioni HTTP

I trigger e i webhook HTTP e le associazioni di output HTTP usano oggetti di richiesta e risposta per rappresentare la messaggistica HTTP.

Oggetto della richiesta

L'oggetto richiesta passato nello script è del tipo HttpRequestContext, che ha le proprietà seguenti:

Proprietà	Descrizione	Tipo
Body	Oggetto che contiene il corpo della richiesta. Body viene serializzato nel tipo migliore in base ai dati. Ad esempio, se i dati sono JSON, vengono passati come tabella hash. Se i dati sono una stringa, vengono passati come stringa.	oggetto
Headers	Dizionario che contiene le intestazioni della richiesta.	Dizionario<stringa, stringa>*
Method	Metodo HTTP della richiesta.	string
Params	Oggetto che contiene i parametri di routing della richiesta.	Dizionario<stringa, stringa>*
Query	Oggetto che contiene i parametri di query della richiesta.	Dizionario<stringa, stringa>*
Url	URL della richiesta.	string

^* Tutte le chiavi Dictionary<string,string> non fanno distinzione tra maiuscole e minuscole.

Oggetto della risposta

L'oggetto risposta da inviare è del tipo HttpResponseContext, che ha le proprietà seguenti:

Proprietà	Descrizione	Tipo
Body	Oggetto che contiene il corpo della risposta.	oggetto
ContentType	Breve mano per impostare il tipo di contenuto per la risposta.	string
Headers	Oggetto che contiene le intestazioni della risposta.	Dizionario o Hashtable
StatusCode	Codice di stato HTTP della risposta.	stringa o numero intero

Accesso a richiesta e risposta

Quando si usano i trigger HTTP, è possibile accedere alla richiesta HTTP allo stesso modo con qualsiasi altr binding di input. È nel blocco param.

Usare un oggetto HttpResponseContext per restituire una risposta, come illustrato di seguito:

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!"
})

Il risultato della chiamata di questa funzione è:

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

Cast dei tipi per trigger e binding

Per determinate binding come il binding BLOB, è possibile specificare il tipo del parametro.

Ad esempio, per fare in modo che i dati dell'archivio BLOB siano forniti come stringa, aggiungere il tipo seguente al blocco param:

param([string] $myBlob)

Profilo di PowerShell

In PowerShell è presente il concetto di profilo di PowerShell. Se non si ha familiarità con i profili di PowerShell, vedere Informazioni sui profili.

In Funzioni di PowerShell lo script del profilo viene eseguito una volta per ogni istanza del ruolo di lavoro di PowerShell nell'app al primo distribuiti e dopo essere stato inattito (avvio a freddo). Quando la concorrenza è abilitata impostando il valore PSWorkerInProcConcurrencyUpperBound, lo script del profilo viene eseguito per ogni spazio di esecuzione creato.

Quando si crea un'app per le funzioni usando strumenti, ad esempio Visual Studio Code e Azure Functions Core Tools, viene creata automaticamente un'impostazione predefinita profile.ps1. Il profilo predefinito viene mantenuto nel repository GitHub core tools e contiene:

• Autenticazione MSI automatica in Azure.
• Possibilità di attivare gli alias di Azure PowerShell AzureRM PowerShell se si vuole.

Versioni di PowerShell

La tabella seguente illustra le versioni di PowerShell disponibili per ogni versione principale del runtime di Funzioni e la versione di .NET necessaria:

Versione di Funzioni	Versione PowerShell	Versione di .NET
4.x	PowerShell 7.4	.NET 8
4.x	PowerShell 7.2 (fine del supporto)	.NET 6

È possibile visualizzare la versione corrente stampando $PSVersionTable da qualsiasi funzione.

Per altre informazioni sui criteri di supporto del runtime di Funzioni di Azure, vedere questo articolo

Nota

Il supporto per PowerShell 7.2 in Funzioni di Azure termina l'8 novembre 2024. Potrebbe essere necessario risolvere alcune modifiche di rilievo durante l'aggiornamento delle funzioni di PowerShell 7.2 per l'esecuzione in PowerShell 7.4. Seguire questa guida alla migrazione per eseguire l'aggiornamento a PowerShell 7.4.

Esecuzione locale in una versione specifica

Quando si eseguono le funzioni di PowerShell in locale, è necessario aggiungere l'impostazione "FUNCTIONS_WORKER_RUNTIME_VERSION" : "7.4" alla matrice Values nel file local.setting.json nella radice del progetto. Quando si esegue localmente in PowerShell 7.4, il file local.settings.json è simile all'esempio seguente:

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

Nota

In Funzioni di PowerShell il valore "~7" per FUNCTIONS_WORKER_RUNTIME_VERSION fa riferimento a "7.0.x". Le app per le funzioni di PowerShell non vengono aggiornate automaticamente con "~7" a "7.4". In futuro, per le app per le funzioni di PowerShell, sarà necessario che le app specifichino sia la versione principale che quella secondaria di destinazione. Di conseguenza, è necessario menzionare "7.4" se si vuole impostare come destinazione "7.4.x"

Modifica della versione di PowerShell

Prendere in considerazione queste considerazioni prima di eseguire la migrazione dell'app per le funzioni di PowerShell a PowerShell 7.4:

• Poiché la migrazione potrebbe introdurre modifiche di rilievo nell'app, esaminare questa guida alla migrazione prima di aggiornare l'app a PowerShell 7.4.

• Assicurarsi che l'app per le funzioni sia in esecuzione nella versione più recente del runtime di Funzioni in Azure, ovvero la versione 4.x. Per altre informazioni, vedere Visualizzare e aggiornare la versionedi runtime corrente.

Usare la procedura seguente per modificare la versione di PowerShell usata dall'app per le funzioni. È possibile eseguire questa operazione nel portale di Azure o usando PowerShell.

Portale

1. Nel portale di Azure passare all'app per le funzioni.

2. In Impostazioni, scegliere Configurazione. Nella scheda Impostazioni generali, individuare la versione di PowerShell.

   

3. Scegliere la versione di PowerShell Core desiderata e selezionare Salva. Quando viene visualizzato un avviso relativo al riavvio in sospeso, scegliere Continua. L'app per le funzioni viene riavviata nella versione di PowerShell scelta.

Nota

Il supporto di Funzioni di Azure per PowerShell 7.4 è disponibile a livello generale. È possibile che PowerShell 7.4 sia ancora indicato come anteprima nel portale di Azure, ma questo verrà aggiornato presto per riflettere lo stato della disponibilità generale.

PowerShell

Eseguire lo script seguente per modificare la versione di PowerShell:

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

Sostituire <SUBSCRIPTION_ID>, <RESOURCE_GROUP> e <FUNCTION_APP> con l'ID della sottoscrizione di Azure, rispettivamente il nome del gruppo di risorse e dell'app per le funzioni. Sostituire anche <VERSION> con 7.4. È possibile verificare il valore aggiornato dell'impostazione powerShellVersion in Properties nella tabella hash restituita.

L'app per le funzioni viene riavviata dopo aver apportato la modifica alla configurazione.

Gestione delle dipendenze

Funzioni consente di sfruttare PowerShell Gallery per gestire le dipendenze. Con la gestione delle dipendenze abilitata, il file requirements.psd1 viene usato per scaricare automaticamente i moduli necessari. Per abilitare questo comportamento, impostare la proprietà managedDependency su true nella radice del file host.json, come nell'esempio seguente:

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

Quando si crea un nuovo progetto di funzioni di PowerShell, la gestione delle dipendenze è abilitata per impostazione predefinita, con il modulo Az di Azure incluso . Il numero massimo di moduli attualmente supportati è 10. La sintassi supportata è MajorNumber.* o la versione esatta del modulo, come illustrato nell'esempio requirements.psd1 seguente:

@{
	Az = '1.*'
	SqlServer = '21.1.18147'
}

Quando si aggiorna il file requirements.psd1, i moduli aggiornati vengono installati dopo un riavvio.

Versioni specifiche di destinazione

È possibile scegliere come destinazione una versione specifica di un modulo nel file requirements.psd1. Ad esempio, se si vuole usare una versione precedente di Az.Accounts rispetto a quella nel modulo Az incluso, è necessario specificare come destinazione una versione specifica, come illustrato nell'esempio seguente:

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

In questo caso, è anche necessario aggiungere un'istruzione import all'inizio del file profile.ps1, simile all'esempio seguente:

Import-Module Az.Accounts -RequiredVersion '1.9.5'

In questo modo, la versione precedente del modulo Az.Account viene caricata per prima quando viene avviata la funzione.

Considerazioni sulla gestione delle dipendenze

Quando si usa la gestione delle dipendenze, si applicano le considerazioni seguenti:

• Le dipendenze gestite richiedono l'accesso a https://www.powershellgallery.com per scaricare i moduli. Quando si esegue localmente, assicurarsi che il runtime possa accedere a questo URL aggiungendo eventuali regole del firewall necessarie.

• Le dipendenze gestite attualmente non supportano i moduli che richiedono all'utente di accettare una licenza, accettando la licenza in modo interattivo o fornendo un commutatore -AcceptLicense quando si richiama Install-Module.

• Le dipendenze gestite non sono supportate quando si ospita l'app per le funzioni in un piano Flex Consumption. È invece necessario definire moduli personalizzati.

Impostazioni dell'app di gestione delle dipendenze

Le impostazioni dell'applicazione seguenti possono essere usate per modificare la modalità di download e installazione delle dipendenze gestite.

Impostazione dell'app per le funzioni	Default value	Descrizione
MDMaxBackgroundUpgradePeriod	7.00:00:00 (7 giorni)	Controlla il periodo di aggiornamento in background per le app per le funzioni di PowerShell. Per altre informazioni, vedere MDMaxBackgroundUpgradePeriod.
MDNewSnapshotCheckPeriod	01:00:00 (un'ora)	Specifica la frequenza con cui ogni ruolo di lavoro di PowerShell controlla se sono stati installati gli aggiornamenti delle dipendenze gestite. Per altre informazioni, vedere MDNewSnapshotCheckPeriod.
MDMinBackgroundUpgradePeriod	1.00:00:00 (un giorno)	Periodo di tempo dopo un controllo dell'aggiornamento precedente prima dell'avvio di un altro controllo dell'aggiornamento. Per altre informazioni, vedere MDMinBackgroundUpgradePeriod.

Essenzialmente, l'aggiornamento dell'app viene avviato in MDMaxBackgroundUpgradePeriod e il processo di aggiornamento viene completato in circa MDNewSnapshotCheckPeriod.

Moduli personalizzati

L'uso di moduli personalizzati in Funzioni di Azure differisce da come si farebbe normalmente per PowerShell.

Nel computer locale il modulo viene installato in una delle cartelle disponibili a livello globale in $env:PSModulePath. Quando si esegue in Azure, non si ha accesso ai moduli installati nel computer. Ciò significa che $env:PSModulePath per un'app per le funzioni di PowerShell è diverso da $env:PSModulePath in uno script di PowerShell normale.

In Funzioni, PSModulePath contiene due percorsi:

• Una cartella Modules esistente nella radice dell'app per le funzioni.
• Un percorso a una cartella Modules controllata dal ruolo di lavoro del linguaggio di PowerShell.

Cartella moduli a livello di app per le funzioni

Per usare moduli personalizzati, è possibile inserire moduli da cui dipendono le funzioni in una cartella Modules. Da questa cartella, i moduli sono automaticamente disponibili per il runtime delle funzioni. Qualsiasi funzione nell'app per le funzioni può usare questi moduli.

Nota

I moduli specificati nel file requirements.psd1 vengono scaricati automaticamente e inclusi nel percorso in modo che non sia necessario includerli nella cartella moduli. Questi vengono archiviati localmente nella cartella $env:LOCALAPPDATA/AzureFunctions e nella cartella /data/ManagedDependencies quando vengono eseguiti nel cloud.

Per sfruttare i vantaggi della funzionalità del modulo personalizzato, creare una cartella Modules nella radice dell'app per le funzioni. Copiare i moduli da usare nelle funzioni in questo percorso.

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

Con una cartella Modules, l'app per le funzioni deve avere la struttura di cartelle seguente:

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

Quando si avvia l'app per le funzioni, il ruolo di lavoro del linguaggio di PowerShell aggiunge questa cartella Modules a $env:PSModulePath in modo che sia possibile basarsi sul caricamento automatico del modulo esattamente come si farebbe con uno script di PowerShell normale.

Cartella moduli a livello di ruolo di lavoro per la lingua

Diversi moduli vengono comunemente usati dal ruolo di lavoro del linguaggio di PowerShell. Questi moduli sono definiti nell'ultima posizione di PSModulePath.

L'elenco corrente dei moduli è il seguente:

• Microsoft.PowerShell.Archive: modulo usato per l'uso di archivi, ad esempio .zip, .nupkg e altri.
• ThreadJob: implementazione basata su thread delle API del processo di PowerShell.

Per impostazione predefinita, Funzioni usa la versione più recente di questi moduli. Per usare una versione specifica del modulo, inserire tale versione specifica nella cartella dell'app per le funzioni Modules.

Variabili di ambiente

In Funzioni, le impostazioni dell'app, come le stringhe di connessione al servizio, vengono esposte come variabili di ambiente durante l'esecuzione. È possibile accedere a queste impostazioni usando $env:NAME_OF_ENV_VAR, come illustrato nell'esempio seguente:

param($myTimer)

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

Esistono diversi modi per aggiungere, aggiornare ed eliminare le impostazioni dell'app per le funzioni:

• Nel portale di Azure.
• Tramite l'uso dell'interfaccia della riga di comando di Azure
• Usando Azure PowerShell.

Le modifiche apportate alle impostazioni dell'app per le funzioni richiedono il riavvio dell'app per le funzioni.

Per l'esecuzione in locale, le impostazioni dell'app vengono lette dal file di progetto local.settings.json.

Concorrenza

Per impostazione predefinita, il runtime di PowerShell di Funzioni può elaborare una sola chiamata di una funzione alla volta. Tuttavia, questo livello di concorrenza potrebbe non essere sufficiente nelle situazioni seguenti:

• Quando si sta provando a gestire un numero elevato di chiamate contemporaneamente.
• Quando si dispone di funzioni che richiamano altre funzioni all'interno della stessa app per le funzioni.

Esistono alcuni modelli di concorrenza che è possibile esplorare a seconda del tipo di carico di lavoro:

• Aumentare FUNCTIONS_WORKER_PROCESS_COUNT. Ciò consente di gestire le chiamate di funzione in più processi all'interno della stessa istanza, che introduce un determinato sovraccarico di CPU e memoria. In generale, le funzioni associate a I/O non subiranno questo sovraccarico. Per le funzioni associate alla CPU, l'impatto può essere significativo.

• Aumentare il valore dell'impostazione dell'app PSWorkerInProcConcurrencyUpperBound. In questo modo è possibile creare più spazi di esecuzione all'interno dello stesso processo, riducendo significativamente il sovraccarico di CPU e memoria.

Queste variabili di ambiente vengono impostate nelle impostazioni dell'app per le funzioni.

A seconda del caso d'uso, Durable Functions può migliorare significativamente la scalabilità. Per altre informazioni, vedere Modelli di applicazione di Durable Functions.

Nota

È possibile che venga visualizzato l'avviso "le richieste vengono accodate perché non ci sono spazi di esecuzione disponibili", si noti che non si tratta di un errore. Il messaggio indica che le richieste vengono accodate e che verranno gestite al termine delle richieste precedenti.

Considerazioni sull'uso della concorrenza

PowerShell è un linguaggio di scripting single_threaded per impostazione predefinita. Tuttavia, la concorrenza può essere aggiunta usando più spazi di esecuzione di PowerShell nello stesso processo. Il numero di spazi di esecuzione creati, e quindi il numero di thread simultanei per ruolo di lavoro, è limitato dall'impostazione dell'applicazione PSWorkerInProcConcurrencyUpperBound. Per impostazione predefinita, il numero di spazi di esecuzione è impostato su 1.000 nella versione 4.x del runtime di Funzioni. Nelle versioni 3.x e successive il numero massimo di spazi di esecuzione è impostato su 1. La velocità effettiva sarà influenzata dalla quantità di CPU e memoria disponibile nel piano selezionato.

Azure PowerShell usa alcuni contesti processo-livello e stati per evitare la digitazione in eccesso. Tuttavia, se si attiva la concorrenza nell'app per le funzioni e si richiamano azioni che cambiano stato, è possibile che si verifichino race condition. Queste condizioni di gara sono difficili da eseguire per il debug perché una chiamata si basa su un determinato stato e l'altra chiamata ha modificato lo stato.

Esiste un enorme valore nella concorrenza con Azure PowerShell, perché alcune operazioni possono richiedere una notevole quantità di tempo. Tuttavia, è necessario procedere con cautela. Se si sospetta che si stia verificando una race condition, configurare l'impostazione dell'app PSWorkerInProcConcurrencyUpperBound su 1 e usare invece l'isolamento del livello del processo di lavoro per la concorrenza.

Configurare la funzione scriptFile

Per impostazione predefinita, viene eseguita una funzione PowerShell da run.ps1, un file che condivide la stessa directory padre del file function.json corrispondente.

La proprietà scriptFile in function.json può essere usata per ottenere una struttura di cartelle simile a quella nell'esempio seguente:

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

In questo caso, function.json per myFunction include una proprietà scriptFile che fa riferimento al file con la funzione esportata da eseguire.

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

Usare i moduli di PowerShell configurando un entryPoint

Questo articolo ha illustrato le funzioni di PowerShell nel file di script predefinito run.ps1 generato dai modelli. Tuttavia, è anche possibile includere le funzioni nei moduli di PowerShell. È possibile fare riferimento al codice di funzione specifico nel modulo usando i campi scriptFile e entryPoint nel file di configurazione del function.json.

In questo caso, entryPoint è il nome di una funzione o di un cmdlet nel modulo di PowerShell a cui si fa riferimento in scriptFile.

Si consideri la struttura di cartelle seguente:

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

Dove PSFunction.psm1 contiene:

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

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

Export-ModuleMember -Function "Invoke-PSTestFunc"

In questo esempio, la configurazione per myFunction include una proprietà scriptFile che fa riferimento a PSFunction.psm1, che è un modulo di PowerShell in un'altra cartella. La proprietà entryPoint fa riferimento alla funzione Invoke-PSTestFunc, ovvero il punto di ingresso nel modulo.

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

Con questa configurazione, l'oggetto Invoke-PSTestFunc viene eseguito esattamente come sarebbe eseguito run.ps1.

Considerazioni sulle funzioni di PowerShell

Quando si usano funzioni PowerShell, tenere presente le considerazioni indicate nelle due sezioni seguenti.

Avvio a freddo

Quando si sviluppano Funzioni di Azure in un modello di hosting serverless, gli avvii a freddo sono una realtà. L'avvio a freddo si riferisce al periodo di tempo necessario per avviare l'esecuzione dell'app per le funzioni per elaborare una richiesta. L'avvio a freddo si verifica più frequentemente nel piano a consumo perché l'app per le funzioni viene arrestata durante i periodi di inattività.

Aggregare moduli invece di usare Install-Module

Lo script viene eseguito in ogni chiamata. Evitare di usare Install-Module nello script. Usare invece Save-Module prima della pubblicazione, in modo che la funzione non debba perdere tempo per scaricare il modulo. Se l'avvio a freddo influisce sulle funzioni, valutare la possibilità di distribuire l'app per le funzioni in un piano di servizio app impostato su always on o su un piano Premium.

Passaggi successivi

Per ulteriori informazioni, vedi le seguenti risorse:

• Procedure consigliate per Funzioni di Azure
• Guida di riferimento per gli sviluppatori a Funzioni di Azure
• Trigger e associazioni di Funzioni di Azure