Condividi tramite


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: 1
GitHub: fabrikam/asp
Release.Artifacts. {alias}. DefinitionName Nome della pipeline di compilazione o del repository. Esempi:

Azure Pipelines: fabrikam-ci
TFVC: $/fabrikam
Git: fabrikam
GitHub: fabrikam/asp (main)
Release.Artifacts. {alias}. BuildNumber Numero di build o identificatore del commit. Esempi:

Azure Pipelines: 20170112.1
Jenkins: 20170112.1
TFVC: Changeset 3
Git: 38629c964
GitHub: 38629c964
Release.Artifacts. {alias}. BuildId Identificatore di compilazione. Esempi:

Azure Pipelines: 130
Jenkins: 130
GitHub: 38629c964d21fe405ef830b7d0220966b82c9e11
Release.Artifacts. {alias}. BuildURI URL della compilazione. Esempi:

Azure Pipelines: vstfs://build-release/Build/130
GitHub: 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: Build
Jenkins: Jenkins
TFVC: TFVC
Git: Git
GitHub: 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).

Screenshot che mostra come usare una variabile predefinita come argomento.

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.

Screenshot che mostra come usare una variabile predefinita in uno script di PowerShell inline.

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 lucchetto 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:

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)

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

  1. Selezionare Versioni pipeline>e quindi selezionare la pipeline di versione.

  2. Aprire la visualizzazione di riepilogo per la versione e selezionare la fase a cui si è interessati. Nell'elenco dei passaggi scegliere Inizializza processo.

    Screenshot che mostra il passaggio di inizializzazione del processo.

  3. Verranno aperti i log per questo passaggio. Scorrere verso il basso per visualizzare i valori usati dall'agente per questo processo.

    Screenshot che mostra le variabili usate dall'agente.

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.Debug con il valore true alla 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.Debug con il valore true alla scheda Variabili .

  • In alternativa, creare un gruppo di variabili contenente una variabile denominata System.Debug con il valore truee 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.