Come vengono eseguiti i WebJobs nel servizio app Azure

2025-05-05

I processi Web di Azure consentono di eseguire attività in background all'interno dell'app del servizio app, senza bisogno di un'infrastruttura separata. Queste attività vengono individuate e gestite dal motore Kudu, il servizio di distribuzione del servizio app predefinito e il servizio di gestione del runtime. Kudu gestisce l'esecuzione di processi Web, l'accesso al file system, la diagnostica e la raccolta di log in background.

Questo articolo illustra come vengono individuati i processi Web, come il runtime decide cosa eseguire e come configurare il comportamento usando il file facoltativo settings.job .

Note specifiche della piattaforma

WebJobs supportano una varietà di formati di script ed eseguibili, a seconda dell'ambiente di hosting dell'App Service. I tipi di file che è possibile eseguire e i runtime disponibili variano leggermente a seconda che si usi codice Windows, codice Linux o contenitori personalizzati. In generale, i runtime predefiniti sono disponibili per i linguaggi di scripting comuni e i tipi di file aggiuntivi sono supportati quando corrispondono al runtime del linguaggio dell'app o del contenitore.

Tipi di file supportati per script e programmi

Codice Windows
del contenitore Windows
Codice Linux
contenitore Linux

I seguenti tipi di file non sono supportati:

Uso di Cmd di Windows: .cmd, .bat, .exe
Uso di PowerShell: .ps1
Uso di Bash: .sh
Uso di Node.js: .js
Uso di Java: .jar

I runtime necessari per eseguire questi tipi di file sono già installati nell'istanza dell'app Web.

Importante

I processi Web che sono continui, pianificati o basati su eventi possono interrompere l'esecuzione se l'app Web che li ospita diventa inattiva. Le app Web possono scadere dopo 20 minuti di inattività e solo le richieste dirette all'app reimpostano questo timer di inattività. Le azioni come la visualizzazione del portale o l'accesso agli strumenti Kudu non mantengono attiva l'app. Per garantire che i processi Web vengano eseguiti in modo affidabile, abilitare l'impostazione Always On nel riquadro Configurazione del servizio app. Questa impostazione è disponibile solo nei piani tariffari Basic, Standard e Premium.

Scoperta dei lavori e struttura delle cartelle

I WebJobs sono archiviati nella cartella site/wwwroot/App_Data/jobs/ della tua app del Servizio App. Esistono due sottocartelle:

continuous/: per i processi a esecuzione prolungata che vengono avviati automaticamente ed eseguiti in modo continuo.
triggered/: per i processi eseguiti su richiesta o in base a una pianificazione.

Ogni processo ha una propria sottocartella sotto il rispettivo tipo, denominata secondo il WebJob. Per esempio:

App_Data/jobs/triggered/myjob/
App_Data/jobs/continuous/myjob/

All'interno della cartella di lavoro, il motore Kudu cerca un file da eseguire. Questo file può essere uno script o un eseguibile.

Rilevamento dei punti di ingresso

Il runtime di Processi Web usa un file denominato run.* (ad esempio run.py, run.sho run.js) come punto di ingresso esplicito per un processo. Questo file indica alla piattaforma quale script o file binario eseguire per primo, garantendo un comportamento coerente e prevedibile in tutti gli ambienti.

Il nome file deve essere esattamente run.* per essere rilevato automaticamente. I file come start.sh o job.py verranno ignorati a meno che non vengano attivati manualmente. Se non viene trovato alcun run.* file, la piattaforma tenta di rilevare un punto di ingresso di fallback selezionando il primo file supportato in base alla piattaforma di linguaggio del processo Web. Per esempio:

Un processo Web Python con più .py file ( ad esempio file1.py, file2.py) eseguirà il primo .py file trovato nell'archivio.
Un WebJob Node.js cerca il primo file .js.
Un WebJob basato su Bash cerca il primo .sh script.

Questo comportamento di fallback può causare un'esecuzione imprevedibile quando sono presenti più file di script, in particolare nei progetti multi-file, pertanto è consigliabile includere un run.* file per definire il punto di ingresso in modo esplicito.

Nei WebJobs su Linux, .sh gli script devono includere un shebang (#!) e devono essere impostati come eseguibili.

Configurazione di WebJob con settings.job

È possibile personalizzare il comportamento del processo Web usando un file facoltativo settings.job (formato JSON) inserito nella cartella radice del processo. Questo file supporta diverse proprietà:

Proprietà	Descrizione
`schedule`	(string) Espressione CRON usata per pianificare un processo attivato. Esempio: `"0 /15 * * *"`. Solo applicabile ai lavori attivati.
`is_singleton`	(bool) Garantisce che una sola istanza del processo venga eseguita in tutte le istanze scalate orizzontalmente. Impostazione predefinita: `true` per i processi continui, `false` per attivati/su richiesta.
`stopping_wait_time`	(numero, secondi) Periodo di tolleranza (impostazione predefinita 5s) assegnato allo script prima che venga terminato quando il processo Web viene arrestato (ad esempio, durante gli scambi o i riavvii del sito).
`shutdownGraceTimeLimit`	(numero, secondi) Tempo massimo (valore predefinito 0s, ovvero nessun limite) specificato per l'intero arresto del processo WebJob, incluso `stopping_wait_time`, prima che venga terminato forzatamente.
`run_mode`	(string) Valori: `continuous`, `scheduled`, `on_demand`. Sostituisce il rilevamento del tipo di lavoro in base alla cartella.

Annotazioni

stopping_wait_time si applica in modo specifico al periodo di grazia dello script in esecuzione, mentre shutdownGraceTimeLimit definisce il timeout complessivo dello spegnimento del processo. Per informazioni dettagliate sul comportamento, consultare la documentazione di Kudu.

Esempio

{
  "schedule": "0 0 * * * *", // Run once at the top of every hour
  "is_singleton": true,
  "stopping_wait_time": 60,
  "shutdownGraceTimeLimit": 120
}

Registrazione e diagnostica

I log dei processi Web vengono gestiti dal motore Kudu e sono disponibili nella cartella App_Data/jobs/<type>/<jobname>. Inoltre, i log possono essere visualizzati nel portale di Azure o accessibili tramite l'endpoint SCM (Kudu):

https://<your-app>.scm.azurewebsites.net/api/triggeredwebjobs/<job>/history

Per funzionalità di monitoraggio e query più avanzate, prendere in considerazione l'integrazione con Application Insights.

I WebJobs attivati includono una cronologia completa delle esecuzioni. WebJobs continui trasmettono i log in tempo reale.

Suggerimenti per la risoluzione dei problemi

Processo Web non avviato: Verificare la presenza di un file mancante o con nome non specificato run.* . Assicurarsi che si trovi nella cartella del lavoro corretta (triggered o continuous).
Errore di autorizzazioni (Linux): Verificare che lo script disponga delle autorizzazioni di esecuzione (chmod +x run.sh) e includa un shebang valido (ad esempio, #!/bin/bash).
Il lavoro non si arresta correttamente: Utilizzare settings.job per definire stopping_wait_time e potenzialmente shutdownGraceTimeLimit.
Processo pianificato non in esecuzione: Verificare che l'espressione CRON in settings.job sia corretta e che il piano di servizio app abbia "Always On" abilitato, se necessario.
Controllare i log di Kudu: Esaminare i log di esecuzione dettagliati e i log di distribuzione disponibili nella console Kudu (https://<your-app>.scm.azurewebsites.net/) sotto Strumenti > WebJobs e, se necessario, nel Log stream.