Guida per sviluppatori PowerShell per Funzioni di Azure

  • Articolo

Questo articolo fornisce informazioni dettagliate su come scrivere Funzioni di Azure usando 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 tutte le associazioni di input definite nel function.json file. Viene inoltre passato un TriggerMetadata parametro 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 l'avvio rapido di Funzioni per PowerShell per creare la prima funzione di PowerShell.

Struttura delle cartelle

La struttura di cartelle necessaria per un progetto di PowerShell è 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 condiviso host.json che può essere usato per configurare l'app per le funzioni. Ogni funzione ha una cartella con il proprio file di codice (ps1) e il file di configurazione dell'associazione (function.json). Il nome della directory padre del file di function.json è sempre il nome della funzione.

Alcune associazioni richiedono la presenza di un extensions.csproj file. Le estensioni di associazione, necessarie nella versione 2.x e successive del runtime di Funzioni, sono definite nel extensions.csproj file, con i file di libreria effettivi nella bin cartella . 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.

Lo script viene passato un numero di argomenti all'esecuzione. Per gestire questi parametri, aggiungere un param blocco 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 TriggerMetadata parametro viene usato per fornire informazioni aggiuntive sul trigger. I metadati aggiuntivi 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 guid univoco per questa esecuzione della funzione string

Ogni tipo di trigger ha un set di metadati diverso. Ad esempio, per $TriggerMetadataQueueTrigger 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 le associazioni vengono configurate e definite nell'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 le associazioni di input vengono letti come parametri passati alla funzione. Le associazioni di input hanno un direction valore impostato su in in function.json. La name proprietà definita in function.json è il nome del parametro , nel param blocco . Poiché PowerShell usa parametri denominati per l'associazione, l'ordine dei parametri non è rilevante. Tuttavia, è consigliabile seguire l'ordine delle associazioni definite in function.json.

param($MyFirstInputBinding, $MySecondInputBinding)

Scrittura dei dati di output

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

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'associazione 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 l'associazione di output accetta una raccolta di valori, è possibile chiamare Push-OutputBinding ripetutamente per eseguire il push di più valori.

  • Quando l'associazione di output accetta solo un valore singleton, la chiamata Push-OutputBinding di una seconda volta genera un errore.

Sintassi Push-OutputBinding

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

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

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'associazione di output denominata response. Nell'esempio seguente l'associazione 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 per eseguire l'override -Clobber 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: associazione di output della coda

Push-OutputBindingviene usato per inviare dati alle associazioni di output, ad esempio un'associazione 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"

L'associazione 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 le associazioni di output. Questo cmdlet recupera una tabella hash contenente i nomi delle associazioni di output con i rispettivi valori.

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

Get-OutputBinding

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

Get-OutputBinding contiene anche un parametro denominato -Name, che può essere usato per filtrare l'associazione restituita, 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 a Information livello di log.
Debug Write-Debug
Traccia Write-Progress
Write-Verbose

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

Importante

L'uso dei Write-Verbose cmdlet 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, utilizzare la logging.logLevel.default proprietà nel host.json file . 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 AZURE_FUNCTIONS_ENVIRONMENT variabile di ambiente su Development prima di avviare l'app per le funzioni.

Trigger e tipi di associazioni

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

Tutti i trigger e le associazioni 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 associazione 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. Stringa dizionario<, stringa>*
Method Metodo HTTP della richiesta. string
Params Oggetto che contiene i parametri di routing della richiesta. Stringa dizionario<, stringa>*
Query Oggetto che contiene i parametri di query della richiesta. Stringa dizionario<, stringa>*
Url URL della richiesta. string

* Tutte le Dictionary<string,string> chiavi 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 altra associazione di input. È nel param blocco.

Usare un HttpResponseContext oggetto 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 associazioni

Per determinate associazioni come l'associazione 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 param blocco:

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 Funzioni di Azure Core Tools, viene creata automaticamente un'impostazione predefinitaprofile.ps1. Il profilo predefinito viene mantenuto nel repository GitHub core tools e contiene:

  • Autenticazione msi automatica in Azure.
  • Possibilità di attivare gli alias di PowerShell di Azure PowerShell AzureRM 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.2 .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

Esecuzione locale in una versione specifica

Il supporto per PowerShell 7.0 in Funzioni di Azure è terminato il 3 dicembre 2022. Per usare PowerShell 7.2 durante l'esecuzione in locale, è necessario aggiungere l'impostazione "FUNCTIONS_WORKER_RUNTIME_VERSION" : "7.2" alla Values matrice nel file local.setting.json nella radice del progetto. Quando si esegue localmente in PowerShell 7.2, il file di local.settings.json è simile all'esempio seguente:

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

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.2". 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.2" se si vuole impostare come destinazione "7.2.x"

Modifica della versione di PowerShell

Il supporto per PowerShell 7.0 in Funzioni di Azure è terminato il 3 dicembre 2022. Per aggiornare l'app per le funzioni a PowerShell 7.2, verificare che il valore di FUNCTIONS_EXTENSION_VERSION sia impostato su ~4. Per informazioni su come eseguire questa operazione, vedere Visualizzare e aggiornare la versione di 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.

  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.

    image

  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.

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 managedDependency proprietà 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 di Azure Az 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 per https://www.powershellgallery.com 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 -AcceptLicense un commutatore quando si richiama Install-Module.

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 Valore predefinito Descrizione
MDMaxBackgroundUpgradePeriod 7.00:00:00 (sette 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 all'interno di e il processo di aggiornamento viene completato all'interno MDMaxBackgroundUpgradePerioddi 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 per un'app per le $env:PSModulePath funzioni di PowerShell è diverso da $env:PSModulePath uno script di PowerShell normale.

In Funzioni PSModulePath contiene due percorsi:

  • Modules Cartella esistente nella radice dell'app per le funzioni.
  • Percorso di una Modules cartella 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 Modules cartella. 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 modules. Questi vengono archiviati localmente nella $env:LOCALAPPDATA/AzureFunctions cartella e nella /data/ManagedDependencies cartella quando vengono eseguiti nel cloud.

Per sfruttare i vantaggi della funzionalità del modulo personalizzato, creare una Modules cartella 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 Modules cartella, 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 Modules cartella 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, .nupkge 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 Modules funzioni.

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:

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 durable Functions.

Nota

È possibile che venga visualizzato l'avviso "le richieste vengono accodate a causa di spazi di esecuzione non 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 e stato a livello di processo 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, impostare l'impostazione dell'app PSWorkerInProcConcurrencyUpperBound su 1 e usare invece l'isolamento del livello del processo di lavoro per la concorrenza.

Configurare script di funzioneFile

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

La scriptFile proprietà in function.json può essere utilizzata per ottenere una struttura di cartelle simile all'esempio seguente:

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

In questo caso, per function.jsonmyFunction include una scriptFile proprietà 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 scriptFile campi 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 scriptFile proprietà che fa PSFunction.psm1riferimento a , che è un modulo di PowerShell in un'altra cartella. La entryPoint proprietà fa riferimento alla Invoke-PSTestFunc funzione , 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 run.ps1 .

Considerazioni sulle funzioni di PowerShell

Quando si lavora con le funzioni di PowerShell, tenere presenti le considerazioni riportate nelle sezioni seguenti.

Avvio a freddo

Quando si sviluppano Funzioni di Azure nel modello di hosting serverless, l'avvio a freddo è 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: