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 come 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. Si presuppone anche di aver completato l'avvio rapido 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 .

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 nella portale di Azure, questa registrazione viene eseguita per l'utente.

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.

Lo script viene passato a diversi argomenti durante l'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. Questi metadati variano da binding a binding, ma contengono tutte una sys proprietà 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 diversi 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.

L'esempio seguente illustra 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'associazione 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 molti trigger e associazioni 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 è di 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 HttpResponseContext oggetto per restituire una risposta, come illustrato nell'esempio seguente:

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 di Funzioni di Azure runtime, 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 tramite 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

La gestione dei moduli in Funzioni di Azure scritti in PowerShell può essere affrontata in due modi: usando la funzionalità Dipendenze gestite o includendo i moduli direttamente nel contenuto dell'app. Ogni metodo ha i propri vantaggi e la scelta di quella giusta dipende dalle proprie esigenze specifiche.

Scelta dell'approccio di gestione dei moduli appropriato

Perché usare la funzionalità Dipendenze gestite?

• Installazione iniziale semplificata: gestisce automaticamente l'installazione del modulo in base al requirements.psd1 file.
• Aggiornamenti automatici: i moduli vengono aggiornati automaticamente, incluse le correzioni di sicurezza, senza richiedere l'intervento manuale.

Perché includere moduli nel contenuto dell'app?

• Nessuna dipendenza da PowerShell Gallery: i moduli vengono raggruppati con l'app, eliminando le dipendenze esterne.
• Maggiore controllo: evita il rischio di regressioni causate dagli aggiornamenti automatici, offrendo il controllo completo sulle versioni dei moduli usate.
• Compatibilità: funziona sul consumo flessibile ed è consigliato per altri SKU Linux.

Funzionalità Dipendenze gestite

La funzionalità Dipendenze gestite consente Funzioni di Azure di scaricare e gestire automaticamente i moduli di PowerShell specificati nel requirements.psd1 file. Questa funzionalità è abilitata per impostazione predefinita nelle nuove app per le funzioni di PowerShell.

Configurazione di requirements.psd1

Per usare le dipendenze gestite in Funzioni di Azure con PowerShell, è necessario configurare un requirements.psd1 file. Questo file specifica i moduli richiesti dalla funzione e Funzioni di Azure scarica e aggiorna automaticamente questi moduli per garantire che l'ambiente rimanga aggiornato.

Ecco come configurare e configurare il requirements.psd1 file:

1. Creare un requirements.psd1 file nella directory radice della funzione di Azure, se non ne esiste già uno.
2. Definire i moduli e le relative versioni in una struttura di dati di PowerShell.

File requirements.psd1 di esempio:

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

Inclusione di moduli nel contenuto dell'app

Per un maggiore controllo sulle versioni del modulo e per evitare dipendenze da risorse esterne, è possibile includere moduli direttamente nel contenuto dell'app per le funzioni.

Per includere moduli personalizzati:

1. Creare una Modules cartella nella radice dell'app per le funzioni.

   mkdir ./Modules
   

2. Copiare i moduli nella Modules cartella usando uno dei metodi seguenti:

   • Se i moduli sono già disponibili in locale:

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

   • Uso Save-Module di per recuperare da PowerShell Gallery:

     Save-Module -Name MyCustomModule -Path ./Modules
     

   • Uso Save-PSResource del PSResourceGet modulo:

     Save-PSResource -Name MyCustomModule -Path ./Modules
     

L'app per le funzioni deve avere la struttura 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.

Risoluzione dei problemi relativi alle dipendenze gestite

Abilitazione delle dipendenze gestite

Affinché le dipendenze gestite funzionino, la funzionalità deve essere abilitata in host.json:

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

Versioni specifiche di destinazione

Quando è destinata a versioni specifiche del modulo, è importante seguire entrambi i passaggi seguenti per assicurarsi che venga caricata la versione corretta del modulo:

1. Specificare la versione del modulo in requirements.psd1:

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

2. Aggiungere un'istruzione import a profile.ps1:

   Import-Module Az.Accounts -RequiredVersion '1.9.5'
   

Seguendo questa procedura si garantisce che la versione specificata venga caricata all'avvio della funzione.

Configurare impostazioni specifiche dell'intervallo di dipendenze gestite

È possibile configurare il modo in cui le dipendenze gestite vengono scaricate e installate usando le impostazioni dell'app seguenti:

Impostazione	Valore predefinito	Descrizione
MDMaxBackgroundUpgradePeriod	7.00:00:00 (7 giorni)	Controlla il periodo di aggiornamento in background per le app per le funzioni di PowerShell.
MDNewSnapshotCheckPeriod	01:00:00 (un'ora)	Specifica la frequenza con cui il ruolo di lavoro di PowerShell controlla la disponibilità di aggiornamenti.
MDMinBackgroundUpgradePeriod	1.00:00:00 (un giorno)	Tempo minimo tra i controlli di aggiornamento.

Considerazioni sulla gestione delle dipendenze

• Accesso a Internet: le dipendenze gestite richiedono l'accesso a per https://www.powershellgallery.com scaricare i moduli. Assicurarsi che l'ambiente consenta questo accesso, inclusa la modifica delle regole del firewall o della rete virtuale in base alle esigenze.
• Accettazione della licenza: le dipendenze gestite non supportano i moduli che richiedono l'accettazione della licenza.
• Piano a consumo flessibile: la funzionalità Dipendenze gestite non è supportata nel piano Flex Consumption. Usare invece moduli personalizzati.
• Percorsi modulo: nel computer locale i moduli vengono in genere installati in una delle cartelle disponibili a livello globale in $env:PSModulePath. Quando si esegue in Azure, per $env:PSModulePath un'app per le funzioni di PowerShell è diverso da $env:PSModulePath uno script di PowerShell normale e conterrà sia la cartella caricata con il contenuto dell'app Modules che una posizione separata gestita dalle dipendenze gestite.

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. L'aumento di questa impostazione consente di gestire le chiamate di funzione in più processi all'interno della stessa istanza, che introduce un certo sovraccarico di CPU e memoria. In generale, le funzioni associate a I/O non risentono di questo sovraccarico. Per le funzioni associate alla CPU, l'impatto può essere significativo.

• Aumentare il valore dell'impostazione dell'app PSWorkerInProcConcurrencyUpperBound. L'aumento di questa impostazione consente di 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 dell'app per le funzioni è 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

Le funzioni di PowerShell in questo articolo vengono visualizzate con il 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à.

Evitare di usare Install-Module

L'esecuzione Install-Module nello script della funzione in ogni chiamata può causare problemi di prestazioni. Usare invece Save-Module o Save-PSResource prima di pubblicare l'app per le funzioni per aggregare i moduli necessari.

Per altre informazioni, vedere la sezione Gestione dipendenze.

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