Polecenia rejestrowania

Azure DevOps Services | Azure DevOps Server 2022 — Azure DevOps Server 2019

Polecenia rejestrowania to sposób, w jaki zadania i skrypty komunikują się z agentem. Obejmują one akcje, takie jak tworzenie nowych zmiennych, oznaczanie kroku jako nieudanego i przekazywanie artefaktów. Polecenia rejestrowania są przydatne podczas rozwiązywania problemów z potokiem.

Ważne

Staramy się maskować wpisy tajne przed pojawieniem się w danych wyjściowych usługi Azure Pipelines, ale nadal trzeba podjąć środki ostrożności. Nigdy nie powtarzaj wpisów tajnych jako danych wyjściowych. Niektóre argumenty wiersza polecenia dziennika systemów operacyjnych. Nigdy nie przekazuj wpisów tajnych w wierszu polecenia. Zamiast tego sugerujemy mapowania wpisów tajnych na zmienne środowiskowe.

Nigdy nie maskujemy podciągów wpisów tajnych. Jeśli na przykład "abc123" jest ustawiony jako wpis tajny, "abc" nie jest maskowany z dzienników. Jest to unikanie maskowania wpisów tajnych na zbyt szczegółowym poziomie, dzięki czemu dzienniki są nieczytelne. Z tego powodu wpisy tajne nie powinny zawierać danych strukturalnych. Jeśli na przykład "{ "foo": "bar" }" jest ustawiony jako wpis tajny, "pasek" nie jest maskowany z dzienników.

Typ	Polecenia
Polecenia zadań	AddAttachment, Complete, LogDetail, LogIssue, PrependPath, SetEndpoint, SetProgress, SetVariable, SetSecret, UploadFile, UploadSummary
Polecenia artefaktu	Kojarzenie, przekazywanie
Polecenia kompilacji	AddBuildTag, UpdateBuildNumber, UploadLog
Polecenia wydania	UpdateReleaseName

Format polecenia rejestrowania

Ogólny format polecenia rejestrowania to:

##vso[area.action property1=value;property2=value;...]message

Istnieje również kilka poleceń formatowania z nieco inną składnią:

##[command]message

Aby wywołać polecenie rejestrowania, echo polecenia za pośrednictwem standardowych danych wyjściowych.

Bash

#!/bin/bash
echo "##vso[task.setvariable variable=testvar;]testvalue"

Program PowerShell

Write-Host "##vso[task.setvariable variable=testvar;]testvalue"

Ścieżki plików powinny być podane jako ścieżki bezwzględne: rooted na dysku w systemie Windows lub począwszy od / w systemach Linux i macOS.

Uwaga

Pamiętaj, że nie można użyć set -x polecenia przed poleceniem rejestrowania w przypadku korzystania z systemu Linux lub macOS. Zobacz rozwiązywanie problemów, aby dowiedzieć się, jak tymczasowo wyłączyć set -x powłokę Bash.

Polecenia formatowania

Uwaga

Użyj kodowania UTF-8 na potrzeby poleceń rejestrowania.

Te polecenia to komunikaty do formatowania dziennika w usłudze Azure Pipelines. Oznaczają określone wiersze dziennika jako błędy, ostrzeżenia, zwijane sekcje itd.

Polecenia formatowania to:

##[group]Beginning of a group
##[warning]Warning message
##[error]Error message
##[section]Start of a section
##[debug]Debug text
##[command]Command-line being run
##[endgroup]

Polecenia formatowania można używać w zadaniu powłoki bash lub programu PowerShell.

Bash

steps:
- bash: |
    echo "##[group]Beginning of a group"
    echo "##[warning]Warning message"
    echo "##[error]Error message"
    echo "##[section]Start of a section"
    echo "##[debug]Debug text"
    echo "##[command]Command-line being run"
    echo "##[endgroup]"

Program PowerShell

steps:
- powershell: |
    Write-Host "##[group]Beginning of a group"
    Write-Host "##[warning]Warning message"
    Write-Host "##[error]Error message"
    Write-Host "##[section]Start of a section"
    Write-Host "##[debug]Debug text"
    Write-Host "##[command]Command-line being run"
    Write-Host "##[endgroup]"

Te polecenia będą renderowane w dziennikach w następujący sposób:

Ten blok poleceń można również zwinąć i wygląda następująco:

Polecenia zadań

LogIssue: rejestrowanie błędu lub ostrzeżenia

##vso[task.logissue]error/warning message

Użycie

Zarejestruj komunikat o błędzie lub ostrzeżeniu w rekordzie osi czasu bieżącego zadania.

Właściwości

• type = error lub warning (wymagane)
• sourcepath = lokalizacja pliku źródłowego
• linenumber = numer wiersza
• columnnumber = liczba kolumn
• code = kod błędu lub ostrzeżenia

Przykład: rejestrowanie błędu

Bash

#!/bin/bash
echo "##vso[task.logissue type=error]Something went very wrong."
exit 1

Program PowerShell

Write-Host "##vso[task.logissue type=error]Something went very wrong."
exit 1

Napiwek

exit 1 jest opcjonalne, ale często jest to polecenie, które będzie wystawiane wkrótce po zarejestrowaniu błędu. Jeśli wybierzesz pozycję Opcje sterowania: kontynuuj po błędzie, exit 1 spowoduje to częściowo pomyślną kompilację zamiast kompilacji zakończonej niepowodzeniem. Alternatywnie możesz również użyć polecenia task.logissue type=error.

Przykład: rejestrowanie ostrzeżenia o określonym miejscu w pliku

Bash

#!/bin/bash
echo "##vso[task.logissue type=warning;sourcepath=consoleapp/main.cs;linenumber=1;columnnumber=1;code=100;]Found something that could be a problem."

Program PowerShell

Write-Host "##vso[task.logissue type=warning;sourcepath=consoleapp/main.cs;linenumber=1;columnnumber=1;code=100;]Found something that could be a problem."

SetProgress: Pokaż wartość procentową ukończoną

##vso[task.setprogress]current operation

Użycie

Ustaw postęp i bieżącą operację dla bieżącego zadania.

Właściwości

• value = procent ukończenia

Przykład

Bash

echo "Begin a lengthy process..."
for i in {0..100..10}
do
   sleep 1
   echo "##vso[task.setprogress value=$i;]Sample Progress Indicator"
done
echo "Lengthy process is complete."

Program PowerShell

Write-Host "Begin a lengthy process..."
$i=0
While ($i -le 100)
{
   Start-Sleep 1
   Write-Host "##vso[task.setprogress value=$i;]Sample Progress Indicator"
   $i += 10
}
Write-Host "Lengthy process is complete."

Aby zobaczyć, jak wygląda, zapisz i utwórz kolejkę kompilacji, a następnie obejrzyj przebieg kompilacji. Zwróć uwagę, że wskaźnik postępu zmienia się, gdy zadanie uruchamia ten skrypt.

Ukończono: Zakończenie osi czasu

##vso[task.complete]current operation

Użycie

Zakończ rekord osi czasu dla bieżącego zadania, ustaw wynik zadania i bieżącą operację. Jeśli wynik nie zostanie podany, ustaw wynik na powodzenie.

Właściwości

• result =
  • Succeeded Zadanie zakończyło się pomyślnie.
  • SucceededWithIssues Zadanie napotkało problemy. Kompilacja zostanie ukończona jako częściowo zakończona pomyślnie.
  • Failed Kompilacja zostanie ukończona jako zakończona niepowodzeniem. (Jeśli Opcje sterowania: opcja Kontynuuj przy błędzie jest zaznaczona. Kompilacja zostanie ukończona jako częściowo zakończona pomyślnie.

Przykład

Zarejestruj zadanie jako zakończone pomyślnie.

##vso[task.complete result=Succeeded;]DONE

Ustaw zadanie jako nieudane. Alternatywnie możesz również użyć polecenia exit 1.

- bash: |
    if [ -z "$SOLUTION" ]; then
      echo "##vso[task.logissue type=error;]Missing template parameter \"solution\""
      echo "##vso[task.complete result=Failed;]"
    fi

LogDetail: tworzenie lub aktualizowanie rekordu osi czasu dla zadania

##vso[task.logdetail]current operation

Użycie

Tworzy i aktualizuje rekordy osi czasu. Jest ona używana głównie wewnętrznie przez usługę Azure Pipelines do raportowania kroków, zadań i etapów. Klienci mogą dodawać wpisy do osi czasu, ale zazwyczaj nie będą one wyświetlane w interfejsie użytkownika.

Podczas pierwszego kroku tworzymy ##vso[task.detail] rekord "szczegółowa oś czasu" dla kroku. Możemy tworzyć i aktualizować zagnieżdżone rekordy osi czasu oparte na elementach id i parentid.

Autorzy zadań muszą pamiętać, który identyfikator GUID był używany dla każdego rekordu osi czasu. System rejestrowania będzie śledzić identyfikator GUID dla każdego rekordu osi czasu, więc każdy nowy identyfikator GUID spowoduje nowy rekord osi czasu.

Właściwości

• id = Identyfikator GUID rekordu osi czasu (wymagany)
• parentid = identyfikator GUID rekordu osi czasu nadrzędnego
• type = Typ rekordu (wymagany po raz pierwszy, nie można zastąpić)
• name = Nazwa rekordu (wymagana po raz pierwszy, nie można zastąpić)
• order = kolejność rekordu osi czasu (wymagane po raz pierwszy, nie można zastąpić)
• starttime = Datetime
• finishtime = Datetime
• progress = procent ukończenia
• state = Unknown | Initialized | InProgress | Completed
• result = Succeeded | SucceededWithIssues | Failed

Przykłady

Utwórz nowy rekord osi czasu głównego:

##vso[task.logdetail id=new guid;name=project1;type=build;order=1]create new timeline record

Utwórz nowy zagnieżdżony rekord osi czasu:

##vso[task.logdetail id=new guid;parentid=exist timeline record guid;name=project1;type=build;order=1]create new nested timeline record

Aktualizacja istnieje rekord osi czasu:

##vso[task.logdetail id=existing timeline record guid;progress=15;state=InProgress;]update timeline record

SetVariable: inicjowanie lub modyfikowanie wartości zmiennej

##vso[task.setvariable]value

Użycie

Ustawia zmienną w usłudze zmiennej taskcontext. Pierwsze zadanie może ustawić zmienną, a następujące zadania mogą używać zmiennej. Zmienna jest widoczna dla następujących zadań jako zmiennej środowiskowej.

Gdy issecret zostanie ustawiona truewartość , wartość zmiennej zostanie zapisana jako wpis tajny i zamaskowana z dziennika. Zmienne tajne nie są przekazywane do zadań jako zmiennych środowiskowych i zamiast tego muszą być przekazywane jako dane wejściowe.

Gdy isoutput jest ustawiona składnia, aby odwoływać się do true zmiennej ustawionej, różni się w zależności od tego, czy uzyskujesz dostęp do tej zmiennej w tym samym zadaniu, w przyszłym zadaniu, czy w przyszłym etapie. Ponadto jeśli isoutput jest ustawiona false na składnię używania tej zmiennej w ramach tego samego zadania, jest odrębna. Zobacz poziomy zmiennych wyjściowych , aby określić odpowiednią składnię dla każdego przypadku użycia.

Aby uzyskać więcej informacji, zobacz ustawianie zmiennych w skryptach i definiowanie zmiennych .

Właściwości

• variable = nazwa zmiennej (wymagane)
• issecret = wartość logiczna (opcjonalna, domyślna wartość false)
• isoutput = wartość logiczna (opcjonalna, domyślna wartość false)
• isreadonly = wartość logiczna (opcjonalna, domyślna wartość false)

Przykłady

Bash

Ustaw wartości zmiennych:

- bash: |
    echo "##vso[task.setvariable variable=sauce;]crushed tomatoes"
    echo "##vso[task.setvariable variable=secretSauce;issecret=true]crushed tomatoes with garlic"
    echo "##vso[task.setvariable variable=outputSauce;isoutput=true]canned goods"
  name: SetVars

Odczytywanie zmiennych:

- bash: |
    echo "Non-secrets automatically mapped in, sauce is $SAUCE"
    echo "Secrets are not automatically mapped in, secretSauce is $SECRETSAUCE"
    echo "You can use macro replacement to get secrets, and they'll be masked in the log: $(secretSauce)"

Program PowerShell

Ustaw wartości zmiennych:

- pwsh: |
    Write-Host "##vso[task.setvariable variable=sauce;]crushed tomatoes"
    Write-Host "##vso[task.setvariable variable=secretSauce;issecret=true]crushed tomatoes with garlic"
    Write-Host "##vso[task.setvariable variable=outputSauce;isoutput=true]canned goods"
  name: SetVars

Odczytywanie zmiennych:

- pwsh: |
    Write-Host "Non-secrets automatically mapped in, sauce is $env:SAUCE"
    Write-Host "Secrets are not automatically mapped in, secretSauce is $env:SECRETSAUCE"
    Write-Host "You can use macro replacement to get secrets, and they'll be masked in the log: $(secretSauce)"
    Write-Host "Future jobs can also see $env:SETVARS_OUTPUTSAUCE"
    write-Host "Future jobs can also see $(SetVars.outputSauce)"

Dane wyjściowe konsoli:

Non-secrets automatically mapped in, sauce is crushed tomatoes
Secrets are not automatically mapped in, secretSauce is 
You can use macro replacement to get secrets, and they'll be masked in the log: ***
Future jobs can also see canned goods
Future jobs can also see canned goods

SetSecret: Rejestrowanie wartości jako wpisu tajnego

##vso[task.setsecret]value

Użycie

Wartość jest rejestrowana jako wpis tajny przez czas trwania zadania. Wartość zostanie zamaskowana z dzienników z tego punktu do przodu. To polecenie jest przydatne, gdy wpis tajny jest przekształcany (np. zakodowany w formacie base64) lub pochodny.

Uwaga: Poprzednie wystąpienia wartości wpisu tajnego nie będą maskowane.

Przykłady

Bash

Ustaw wartości zmiennych:

- bash: |
    NEWSECRET=$(echo $OLDSECRET|base64)
    echo "##vso[task.setsecret]$NEWSECRET"
  name: SetSecret
  env:
    OLDSECRET: "SeCrEtVaLuE"

Odczytywanie zmiennych:

- bash: |
    echo "Transformed and derived secrets will be masked: $(echo $OLDSECRET|base64)"
  env:
    OLDSECRET: "SeCrEtVaLuE"

Program PowerShell

Ustaw wartości zmiennych:

- pwsh: |
    $NewSecret = [convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes($env:OLDSECRET))
    Write-Host "##vso[task.setsecret]$NewSecret"
  name: SetSecret
  env:
    OLDSECRET: "SeCrEtVaLuE"

Odczytywanie zmiennych:

- pwsh: |
    Write-Host "Transformed and derived secrets will be masked: $([convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes($env:OLDSECRET)))"
  env:
    OLDSECRET: "SeCrEtVaLuE"

Dane wyjściowe konsoli:

Transformed and derived secrets will be masked: ***

SetEndpoint: Modyfikowanie pola połączenia usługi

##vso[task.setendpoint]value

Użycie

Ustaw pole połączenia usługi z daną wartością. Zaktualizowana wartość zostanie zachowana w punkcie końcowym dla kolejnych zadań wykonywanych w ramach tego samego zadania.

Właściwości

• id = identyfikator połączenia usługi (wymagany)
• field = typ pola, jeden z authParameter, dataParameterlub url (wymagane)
• key = klucz (wymagany, chyba że field = url)

Przykłady

##vso[task.setendpoint id=000-0000-0000;field=authParameter;key=AccessToken]testvalue
##vso[task.setendpoint id=000-0000-0000;field=dataParameter;key=userVariable]testvalue
##vso[task.setendpoint id=000-0000-0000;field=url]https://example.com/service

AddAttachment: dołączanie pliku do kompilacji

##vso[task.addattachment]value

Użycie

Przekaż i dołącz załącznik do bieżącego rekordu osi czasu. Te pliki nie są dostępne do pobrania za pomocą dzienników. Można do nich odwoływać się tylko za pomocą rozszerzeń przy użyciu wartości typu lub nazwy.

Właściwości

• type = typ załącznika (wymagany)
• name = nazwa załącznika (wymagane)

Przykład

##vso[task.addattachment type=myattachmenttype;name=myattachmentname;]c:\myattachment.txt

UploadSummary: dodawanie zawartości języka Markdown do podsumowania kompilacji

##vso[task.uploadsummary]local file path

Użycie

Przekaż i dołącz podsumowanie języka Markdown z pliku md w repozytorium do bieżącego rekordu osi czasu. To podsumowanie należy dodać do podsumowania kompilacji/wydania i nie jest dostępne do pobrania z dziennikami. Podsumowanie powinno być w formacie UTF-8 lub ASCII. Podsumowanie zostanie wyświetlone na karcie Rozszerzenia przebiegu potoku. Renderowanie języka Markdown na karcie Rozszerzenia różni się od renderowania w witrynie typu wiki usługi Azure DevOps.

Przykłady

##vso[task.uploadsummary]$(System.DefaultWorkingDirectory)/testsummary.md

Jest to krótka forma polecenia

##vso[task.addattachment type=Distributedtask.Core.Summary;name=testsummaryname;]c:\testsummary.md

UploadFile: przekaż plik, który można pobrać z dziennikami zadań

##vso[task.uploadfile]local file path

Użycie

Przekaż zainteresowany plik jako dodatkowe informacje dziennika do bieżącego rekordu osi czasu. Plik jest dostępny do pobrania wraz z dziennikami zadań.

Przykład

##vso[task.uploadfile]c:\additionalfile.log

PrependPath: wstępna ścieżka do zmiennej środowiskowej PATH

##vso[task.prependpath]local file path

Użycie

Zaktualizuj zmienną środowiskową PATH, poprzedzając element PATH. Zaktualizowana zmienna środowiskowa zostanie odzwierciedlona w kolejnych zadaniach.

Przykład

##vso[task.prependpath]c:\my\directory\path

Polecenia artefaktu

Kojarzenie: inicjowanie artefaktu

##vso[artifact.associate]artifact location

Użycie

Utwórz link do istniejącego artefaktu. Lokalizacja artefaktu musi być ścieżką kontenera plików, ścieżką VC lub ścieżką udziału UNC.

Właściwości

• artifactname = nazwa artefaktu (wymagane)
• type = typ artefaktu (wymagany) container | filepath | versioncontrol | gitref | tfvclabel

Przykłady

• Kontenera

  ##vso[artifact.associate type=container;artifactname=MyServerDrop]#/1/build
  

• Filepath

  ##vso[artifact.associate type=filepath;artifactname=MyFileShareDrop]\\MyShare\MyDropLocation
  

• Versioncontrol

  ##vso[artifact.associate type=versioncontrol;artifactname=MyTfvcPath]$/MyTeamProj/MyFolder
  

• gitref

  ##vso[artifact.associate type=gitref;artifactname=MyTag]refs/tags/MyGitTag
  

• tfvclabel

  ##vso[artifact.associate type=tfvclabel;artifactname=MyTag]MyTfvcLabel
  

• Artefakt niestandardowy

  ##vso[artifact.associate artifactname=myDrop;artifacttype=myartifacttype]https://downloads.visualstudio.com/foo/bar/package.zip
  

Przekazywanie: przekazywanie artefaktu

##vso[artifact.upload]local file path

Użycie

Przekaż plik lokalny do folderu kontenera plików i opcjonalnie opublikuj artefakt jako artifactname.

Właściwości

• containerfolder = folder, do którego zostanie przekazany plik, folder zostanie utworzony w razie potrzeby.
• artifactname = nazwa artefaktu. (Wymagane)

Przykład

##vso[artifact.upload containerfolder=testresult;artifactname=uploadedresult]c:\testresult.trx

Uwaga

Różnica między Artifact.associate i Artifact.upload polega na tym, że pierwszy może służyć do utworzenia linku do istniejącego artefaktu, podczas gdy ten ostatni może służyć do przekazywania/publikowania nowego artefaktu.

Polecenia kompilacji

UploadLog: przekazywanie dziennika

##vso[build.uploadlog]local file path

Użycie

Przekaż interesujący użytkownika dziennik do folderu "logs\tool" kontenera kompilacji.

Przykład

##vso[build.uploadlog]c:\msbuild.log

UpdateBuildNumber: zastąpij automatycznie wygenerowany numer kompilacji

##vso[build.updatebuildnumber]build number

Użycie

Możesz automatycznie wygenerować numer kompilacji na podstawie tokenów, które określisz w opcjach potoku. Jeśli jednak chcesz użyć własnej logiki do ustawienia numeru kompilacji, możesz użyć tego polecenia rejestrowania.

Przykład

##vso[build.updatebuildnumber]my-new-build-number

AddBuildTag: dodawanie tagu do kompilacji

##vso[build.addbuildtag]build tag

Użycie

Dodaj tag dla bieżącej kompilacji. Możesz rozwinąć tag ze wstępnie zdefiniowaną lub zdefiniowaną przez użytkownika zmienną. Na przykład w tym miejscu nowy tag zostanie dodany w zadaniu powłoki Bash z wartością last_scanned-$(currentDate). Nie można użyć dwukropka z elementem AddBuildTag.

Przykład

- task: Bash@3
    inputs:
    targetType: 'inline'
    script: |
        last_scanned="last_scanned-$(currentDate)"
        echo "##vso[build.addbuildtag]$last_scanned"
    displayName: 'Apply last scanned tag'

Polecenia wydania

UpdateReleaseName: Zmiana nazwy bieżącej wersji

##vso[release.updatereleasename]release name

Użycie

Zaktualizuj nazwę wydania dla uruchomionej wersji.

Uwaga

Obsługiwane w usługach Azure DevOps i Azure DevOps Server począwszy od wersji 2020.

Przykład

##vso[release.updatereleasename]my-new-release-name