Usare le variabili nelle pipeline di versione classica
Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019
L'uso delle variabili nelle pipeline di versione classica è un modo pratico per scambiare e trasportare i dati in tutta la pipeline. Ogni variabile viene archiviata come stringa e il relativo valore può cambiare tra le esecuzioni della pipeline.
A differenza dei parametri di runtime, disponibili solo in fase di analisi dei modelli, le variabili nelle pipeline di versione classica sono accessibili durante l'intero processo di distribuzione
Quando si configurano attività per distribuire l'applicazione in ogni fase della pipeline di versione classica, le variabili possono essere utili:
Semplificare la personalizzazione: definire una pipeline di distribuzione generica una sola volta e adattarla facilmente per diverse fasi. Ad esempio, usare una variabile per rappresentare il stringa di connessione di una distribuzione Web, modificandone il valore in base alle esigenze per ogni fase. Queste variabili sono note come variabili personalizzate.
Sfruttare le informazioni contestuali: accedere ai dettagli sul contesto di rilascio, ad esempio una fase, un artefatto o l'agente che esegue la distribuzione. Ad esempio, gli script potrebbero richiedere il percorso di compilazione per il download o la directory di lavoro dell'agente per creare file temporanei. Queste variabili vengono definite variabili predefinite.
Nota
Per le pipeline YAML, vedere Variabili definite dall'utente e variabili predefinite per altri dettagli.
Variabili predefinite
Le variabili predefinite forniscono informazioni essenziali sul contesto di esecuzione per le attività e gli script in esecuzione. Queste variabili consentono di accedere ai dettagli relativi al sistema, alla versione, alla fase o all'agente in cui sono in esecuzione.
Ad eccezione di System.Debug, le variabili predefinite sono di sola lettura, con i relativi valori impostati automaticamente dal sistema.
Alcune delle variabili più significative sono descritte nelle tabelle seguenti. Per visualizzare l'elenco completo, vedere Visualizzare i valori correnti di tutte le variabili.
Variabili di sistema
| Nome variabile | Descrizione |
|---|---|
| System.TeamFoundationServerUri | URL della connessione al servizio in Azure Pipelines. Usare questo comando dagli script o dalle attività per chiamare le API REST di Azure Pipelines. Esempio: https://fabrikam.vsrm.visualstudio.com/ |
| System.TeamFoundationCollectionUri | URL della raccolta Team Foundation o di Azure Pipelines. Usarlo dagli script o dalle attività per chiamare le API REST in altri servizi, ad esempio build e controllo della versione. Esempio: https://dev.azure.com/fabrikam/ |
| System.CollectionId | ID della raccolta a cui appartiene la build o la versione. Esempio: 6c6f3423-1c84-4625-995a-f7f143a1e43d |
| System.DefinitionId | ID della pipeline di versione a cui appartiene la versione corrente. Esempio: 1 |
| System.TeamProject | Nome del progetto a cui appartiene la compilazione o la versione. Esempio: Fabrikam |
| System.TeamProjectId | ID del progetto a cui appartiene la compilazione o la versione. Esempio: 79f5c12e-3337-4151-be41-a268d2c73344 |
| System.ArtifactsDirectory | Directory in cui vengono scaricati gli artefatti durante la distribuzione di una versione. La directory viene cancellata prima di ogni distribuzione se è necessario scaricare elementi nell'agente. Uguale a Agent.ReleaseDirectory e System.DefaultWorkingDirectory. Esempio: C:\agent\_work\r1\a |
| System.DefaultWorkingDirectory | Directory in cui vengono scaricati gli artefatti durante la distribuzione di una versione. La directory viene cancellata prima di ogni distribuzione se è necessario scaricare elementi nell'agente. Uguale a Agent.ReleaseDirectory e System.ArtifactsDirectory. Esempio: C:\agent\_work\r1\a |
| System.WorkFolder | Directory di lavoro per questo agente, in cui vengono create sottocartelle per ogni build o versione. Uguale a Agent.RootDirectory e Agent.WorkFolder. Esempio: C:\agent\_work |
| System.Debug | Si tratta dell'unica variabile di sistema che può essere impostata dagli utenti. Impostare su true per eseguire la versione in modalità di debug per facilitare la ricerca degli errori. Esempio: true |
Variabili di rilascio
| Nome variabile | Descrizione |
|---|---|
| Release.AttemptNumber | Numero di volte in cui questa versione viene distribuita in questa fase. Esempio: 1 |
| Release.DefinitionEnvironmentId | ID della fase nella pipeline di versione corrispondente. Esempio: 1 |
| Release.DefinitionId | ID della pipeline di versione a cui appartiene la versione corrente. Esempio: 1 |
| Release.DefinitionName | Nome della pipeline di versione a cui appartiene la versione corrente. Esempio: fabrikam-cd |
| Release.Deployment.RequestedFor | Nome visualizzato dell'identità che ha attivato (avviato) la distribuzione attualmente in corso. Esempio: Mateo Escobedo |
| Release.Deployment.RequestedForEmail | Indirizzo di posta elettronica dell'identità che ha attivato (avviato) la distribuzione attualmente in corso. Esempio: mateo@fabrikam.com |
| Release.Deployment.RequestedForId | ID dell'identità che ha attivato (avviato) la distribuzione attualmente in corso. Esempio: 2f435d07-769f-4e46-849d-10d1ab9ba6ab |
| Release.DeploymentID | ID della distribuzione. Univoco per processo. Esempio: 254 |
| Release.DeployPhaseID | ID della fase in cui è in esecuzione la distribuzione. Esempio: 127 |
| Release.EnvironmentId | ID dell'istanza di fase in una versione in cui è in corso la distribuzione. Esempio: 276 |
| Release.EnvironmentName | Nome della fase in cui è in corso la distribuzione. Esempio: Dev |
| Release.EnvironmentUri | URI dell'istanza di fase in una versione in cui è in corso la distribuzione. Esempio: vstfs://ReleaseManagement/Environment/276 |
| Release.Environments. {stage-name}.status | Stato della distribuzione della fase. Esempio: InProgress |
| Release.PrimaryArtifactSourceAlias | Alias dell'origine dell'artefatto primario. Esempio: fabrikam\_web |
| Release.Reason | Motivo della distribuzione. I valori supportati sono:ContinuousIntegration - la versione avviata nella distribuzione continua dopo il completamento di una compilazione.Manual : la versione è stata avviata manualmente.None - Il motivo della distribuzione non è stato specificato.Schedule - la versione avviata da una pianificazione. |
| Release.ReleaseDescription | Descrizione del testo fornita al momento del rilascio. Esempio: Critical security patch |
| Release.ReleaseId | Identificatore del record di versione corrente. Esempio: 118 |
| Release.ReleaseName | Nome della versione corrente. Esempio: Release-47 |
| Release.ReleaseUri | URI della versione corrente. Esempio: vstfs://ReleaseManagement/Release/118 |
| Release.ReleaseWebURL | URL per questa versione. Esempio: https://dev.azure.com/fabrikam/f3325c6c/_release?releaseId=392&_a=release-summary |
| Release.RequestedFor | Nome visualizzato dell'identità che ha attivato la versione. Esempio: Mateo Escobedo |
| Release.RequestedForEmail | Indirizzo di posta elettronica dell'identità che ha attivato il rilascio. Esempio: mateo@fabrikam.com |
| Release.RequestedForId | ID dell'identità che ha attivato il rilascio. Esempio: 2f435d07-769f-4e46-849d-10d1ab9ba6ab |
| Release.SkipArtifactsDownload | Valore booleano che specifica se ignorare o meno il download degli artefatti nell'agente. Esempio: FALSE |
| Release.TriggeringArtifact.Alias | Alias dell'artefatto che ha attivato la versione. Questa operazione è vuota quando la versione è stata pianificata o attivata manualmente. Esempio: fabrikam\_app |
Variabili della fase di rilascio
| Nome variabile | Descrizione |
|---|---|
| Release.Environments. {nome fase}. Stato | Stato della distribuzione di questa versione all'interno di una fase specificata. Esempio: NotStarted |
Variabili dell'agente
| Nome variabile | Descrizione |
|---|---|
| Agent.Name | Nome dell'agente registrato con il pool di agenti. È probabile che sia diverso dal nome del computer. Esempio: fabrikam-agent |
| Agent.MachineName | Nome del computer in cui è configurato l'agente. Esempio: fabrikam-agent |
| Agent.Version | Versione del software dell'agente. Esempio: 2.109.1 |
| Agent.JobName | Nome del processo in esecuzione, ad esempio Release o Build. Esempio: Release |
| Agent.HomeDirectory | Cartella in cui è installato l'agente. Questa cartella contiene il codice e le risorse per l'agente. Esempio: C:\agent |
| Agent.ReleaseDirectory | Directory in cui vengono scaricati gli artefatti durante la distribuzione di una versione. La directory viene cancellata prima di ogni distribuzione se è necessario scaricare elementi nell'agente. Uguale a System.ArtifactsDirectory e System.DefaultWorkingDirectory. Esempio: C:\agent\_work\r1\a |
| Agent.RootDirectory | Directory di lavoro per questo agente, in cui vengono create sottocartelle per ogni build o versione. Uguale a Agent.WorkFolder e System.WorkFolder. Esempio: C:\agent\_work |
| Agent.WorkFolder | Directory di lavoro per questo agente, in cui vengono create sottocartelle per ogni build o versione. Uguale a Agent.RootDirectory e System.WorkFolder. Esempio: C:\agent\_work |
| Agent.DeploymentGroupId | ID del gruppo di distribuzione in cui è registrato l'agente. Questa opzione è disponibile solo nei processi del gruppo di distribuzione. Esempio: 1 |
Variabili release Artifacts
Per ogni artefatto a cui viene fatto riferimento in una versione, è possibile usare le variabili di artefatto seguenti. Si noti che non tutte le variabili si applicano a ogni tipo di artefatto. La tabella seguente elenca le variabili di artefatto predefinite e fornisce esempi dei relativi valori in base al tipo di artefatto. Se un esempio è vuoto, indica che la variabile non è applicabile per tale tipo di artefatto.
Sostituire il {alias} segnaposto con il valore specificato per l'alias di origine dell'artefatto o con il valore predefinito generato per la pipeline di versione.
| Nome variabile | Descrizione |
|---|---|
| Release.Artifacts. {alias}. DefinitionId | Identificatore della pipeline di compilazione o del repository. Esempi: Azure Pipelines: 1GitHub: fabrikam/asp |
| Release.Artifacts. {alias}. DefinitionName | Nome della pipeline di compilazione o del repository. Esempi: Azure Pipelines: fabrikam-ciTFVC: $/fabrikamGit: fabrikamGitHub: fabrikam/asp (main) |
| Release.Artifacts. {alias}. BuildNumber | Numero di build o identificatore del commit. Esempi: Azure Pipelines: 20170112.1Jenkins: 20170112.1TFVC: Changeset 3Git: 38629c964GitHub: 38629c964 |
| Release.Artifacts. {alias}. BuildId | Identificatore di compilazione. Esempi: Azure Pipelines: 130Jenkins: 130GitHub: 38629c964d21fe405ef830b7d0220966b82c9e11 |
| Release.Artifacts. {alias}. BuildURI | URL della compilazione. Esempi: Azure Pipelines: vstfs://build-release/Build/130GitHub: https://github.com/fabrikam/asp |
| Release.Artifacts. {alias}. SourceBranch | Percorso completo e nome del ramo da cui è stata compilata l'origine. Esempi: Azure Pipelines: refs/heads/main |
| Release.Artifacts. {alias}. SourceBranchName | Nome solo del ramo da cui è stata compilata l'origine. Esempi: Azure Pipelines: main |
| Release.Artifacts. {alias}. SourceVersion | Commit compilato. Esempi: Azure Pipelines: bc0044458ba1d9298cdc649cb5dcf013180706f7 |
| Release.Artifacts. {alias}. Repository.Provider | Tipo di repository da cui è stata compilata l'origine. Esempi: Azure Pipelines: Git |
| Release.Artifacts. {alias}. RequestedForID | Identificatore dell'account che ha attivato la compilazione. Esempi: Azure Pipelines: 2f435d07-769f-4e46-849d-10d1ab9ba6ab |
| Release.Artifacts. {alias}. RequestedFor | Nome dell'account che ha richiesto la compilazione. Esempi: Azure Pipelines: Mateo Escobedo |
| Release.Artifacts. {alias}. Digitare | Tipo di origine dell'artefatto, ad esempio Build.Examples Azure Pipelines: BuildJenkins: JenkinsTFVC: TFVCGit: GitGitHub: GitHub |
| Release.Artifacts. {alias}. PullRequest.TargetBranch | Percorso completo e nome del ramo che rappresenta la destinazione di una richiesta pull. Questa variabile viene inizializzata solo se la versione viene attivata da un flusso di richiesta pull. Esempi: Azure Pipelines: refs/heads/main |
| Release.Artifacts. {alias}. PullRequest.TargetBranchName | Nome solo del ramo che è la destinazione di una richiesta pull. Questa variabile viene inizializzata solo se la versione viene attivata da un flusso di richiesta pull. Esempi: Azure Pipelines: main |
Variabili dell'artefatto primario
Nelle pipeline di versione classica, se si usano più artefatti, è possibile designarne uno come artefatto primario. Azure Pipelines popola quindi le variabili seguenti per l'artefatto primario designato.
| Nome variabile | Uguale a |
|---|---|
| Build.DefinitionId | Release.Artifacts. {Alias artefatto primario}. DefinitionId |
| Build.DefinitionName | Release.Artifacts. {Alias artefatto primario}. DefinitionName |
| Build.BuildNumber | Release.Artifacts. {Alias artefatto primario}. BuildNumber |
| Build.BuildId | Release.Artifacts. {Alias artefatto primario}. BuildId |
| Build.BuildURI | Release.Artifacts. {Alias artefatto primario}. BuildURI |
| Build.SourceBranch | Release.Artifacts. {Alias artefatto primario}. SourceBranch |
| Build.SourceBranchName | Release.Artifacts. {Alias artefatto primario}. SourceBranchName |
| Build.SourceVersion | Release.Artifacts. {Alias artefatto primario}. SourceVersion |
| Build.Repository.Provider | Release.Artifacts. {Alias artefatto primario}. Repository.Provider |
| Build.RequestedForID | Release.Artifacts. {Alias artefatto primario}. RequestedForID |
| Build.RequestedFor | Release.Artifacts. {Alias artefatto primario}. RequestedFor |
| Build.Type | Release.Artifacts. {Alias artefatto primario}. Digitare |
| Build.PullRequest.TargetBranch | Release.Artifacts. {Alias artefatto primario}. PullRequest.TargetBranch |
| Build.PullRequest.TargetBranchName | Release.Artifacts. {Alias artefatto primario}. PullRequest.TargetBranchName |
Usare le variabili predefinite
È possibile usare le variabili predefinite in due modi: come parametri per le attività in una pipeline di versione o all'interno degli script.
È possibile usare una variabile predefinita direttamente come input per un'attività. Ad esempio, per passare Release.Artifacts.{Artifact alias}.DefinitionName come argomento a un'attività di PowerShell per un artefatto con ASPNET4.CI come alias, usare $(Release.Artifacts.ASPNET4.CI.DefinitionName).
Per usare una variabile predefinita nello script, è necessario innanzitutto sostituire nei . nomi delle variabili predefinite con _. Ad esempio, per stampare il valore di Release.Artifacts.{Artifact alias}.DefinitionName per un artefatto con ASPNET4.CI come alias in uno script di PowerShell, usare $env:RELEASE_ARTIFACTS_ASPNET4_CI_DEFINITIONNAME. Si noti che l'alias originale, ASPNET4.CI, viene sostituito con ASPNET4_CI.
Variabili personalizzate
Le variabili personalizzate possono essere definite in vari ambiti.
Gruppi di variabili: usare gruppi di variabili per condividere valori tra tutte le definizioni in un progetto. Ciò è utile quando si vogliono usare gli stessi valori in definizioni, fasi e attività all'interno di un progetto e gestirli da un'unica posizione. Definire e gestire gruppi di variabili nella libreria Pipelines>.
Variabili della pipeline di versione: usare le variabili della pipeline di versione per condividere i valori in tutte le fasi all'interno di una pipeline di versione. Questo è ideale per gli scenari in cui è necessario un valore coerente tra le fasi e le attività, con la possibilità di aggiornarlo da una singola posizione. Definire e gestire queste variabili nella scheda Variabili della pipeline di versione. Nella pagina Variabili pipeline impostare l'elenco a discesa Ambito su Rilascio quando si aggiunge una variabile.
Variabili di fase: usare le variabili di fase per condividere i valori all'interno di una fase specifica di una pipeline di versione. Ciò è utile per i valori che differiscono dalla fase alla fase, ma sono coerenti in tutte le attività all'interno di una fase. Definire e gestire queste variabili nella scheda Variabili della pipeline di versione. Nella pagina Variabili pipeline impostare l'elenco a discesa Ambito sull'ambiente appropriato quando si aggiunge una variabile.
L'uso di variabili personalizzate a livello di progetto, pipeline di versione e fase consente di:
Evitare di duplicare i valori, semplificando l'aggiornamento di tutte le occorrenze con una singola modifica.
Proteggere i valori sensibili impedendo loro di essere visualizzati o modificati dagli utenti. Per contrassegnare una variabile come sicura (segreto), selezionare l'icona
accanto alla variabile.Importante
I valori delle variabili nascoste (segreto) vengono archiviati in modo sicuro nel server e non possono essere visualizzati dagli utenti dopo il salvataggio. Durante la distribuzione, Azure Pipelines decrittografa questi valori quando si fa riferimento alle attività e li passa all'agente tramite un canale HTTPS sicuro.
Nota
La creazione di variabili personalizzate può sovrascrivere le variabili standard. Ad esempio, se si definisce una variabile Path personalizzata in un agente Windows, la variabile $env:Path potrebbe impedire l'esecuzione corretta di PowerShell.
Usare variabili personalizzate
Per usare variabili personalizzate nelle attività, racchiudere il nome della variabile tra parentesi e precederlo con un $ carattere. Ad esempio, se si dispone di una variabile denominata adminUserName, è possibile inserire il relativo valore corrente in un'attività come $(adminUserName).
Nota
Le variabili di gruppi diversi collegati a una pipeline nello stesso ambito (ad esempio, processo o fase) possono entrare in conflitto, causando risultati imprevedibili. Per evitare questo problema, assicurarsi che le variabili in tutti i gruppi di variabili abbiano nomi univoci.
Definire e modificare le variabili in uno script
Per definire o modificare una variabile da uno script, usare il task.setvariable comando di registrazione. Il valore della variabile aggiornato ha come ambito il processo in esecuzione e non viene mantenuto tra processi o fasi. Si noti che i nomi delle variabili vengono trasformati in lettere maiuscole, con "." e " " sostituiti con "_".
Ad esempio, Agent.WorkFolder diventa AGENT_WORKFOLDER.
- In Windows accedere a questa variabile come
%AGENT_WORKFOLDER%o$env:AGENT_WORKFOLDER. - In Linux e macOS usare
$AGENT_WORKFOLDER.
Suggerimento
È possibile eseguire uno script in:
- Un agente di Windows che usa un'attività script batch o un'attività di PowerShell.
- Un agente macOS o Linux usando un'attività script shell.
Script batch
Impostare le sauce variabili e secret.Sauce
@echo ##vso[task.setvariable variable=sauce]crushed tomatoes
@echo ##vso[task.setvariable variable=secret.Sauce;issecret=true]crushed tomatoes with garlic
Leggere le variabili
Argomenti
"$(sauce)" "$(secret.Sauce)"
Script
@echo off
set sauceArgument=%~1
set secretSauceArgument=%~2
@echo No problem reading %sauceArgument% or %SAUCE%
@echo But I cannot read %SECRET_SAUCE%
@echo But I can read %secretSauceArgument% (but the log is redacted so I do not spoil the secret)
Impostare le 
Impostare le Output della console dalla lettura delle variabili:
No problem reading crushed tomatoes or crushed tomatoes
But I cannot read
But I can read ******** (but the log is redacted so I do not spoil the secret)
Visualizzare i valori correnti di tutte le variabili
Selezionare Versioni pipeline>e quindi selezionare la pipeline di versione.
Aprire la visualizzazione di riepilogo per la versione e selezionare la fase a cui si è interessati. Nell'elenco dei passaggi scegliere Inizializza processo.
Verranno aperti i log per questo passaggio. Scorrere verso il basso per visualizzare i valori usati dall'agente per questo processo.
Eseguire una versione in modalità di debug
L'esecuzione di una versione in modalità di debug consente di diagnosticare e risolvere i problemi o gli errori visualizzando informazioni aggiuntive durante l'esecuzione del rilascio. È possibile abilitare la modalità di debug per l'intera versione o solo per le attività all'interno di una fase di rilascio specifica.
Per abilitare la modalità di debug per un'intera versione, aggiungere una variabile denominata
System.Debugcon il valoretruealla scheda Variabili della pipeline di versione.Per abilitare la modalità di debug per una fase specifica, aprire la finestra di dialogo Configura fase dal menu di scelta rapida della fase e aggiungere una variabile denominata
System.Debugcon il valoretruealla scheda Variabili .In alternativa, creare un gruppo di variabili contenente una variabile denominata
System.Debugcon il valoretruee collegare questo gruppo di variabili alla pipeline di versione.
Suggerimento
Se si verifica un errore relativo alle connessioni al servizio Azure Resource Manager, vedere Procedura: Risolvere i problemi relativi alle connessioni al servizio Azure Resource Manager per altri dettagli.