Perintah untuk pengelogan

Layanan Azure DevOps | Azure DevOps Server 2022 - Azure DevOps Server 2019

Perintah pengelogan adalah cara tugas dan skrip berkomunikasi dengan agen. Mereka mencakup tindakan seperti membuat variabel baru, menandai langkah sebagai gagal, dan mengunggah artefak. Perintah pengelogan berguna saat Anda memecahkan masalah alur.

Penting

Kami berupaya menutupi rahasia agar tidak muncul di output Azure Pipelines, tetapi Anda masih perlu mengambil tindakan pencegahan. Jangan pernah menggaungkan rahasia sebagai output. Beberapa argumen baris perintah log sistem operasi. Jangan pernah meneruskan rahasia pada baris perintah. Sebagai gantinya, kami sarankan Anda memetakan rahasia Anda ke dalam variabel lingkungan.

Kami tidak pernah menutupi substring rahasia. Jika, misalnya, "abc123" diatur sebagai rahasia, "abc" tidak ditutupi dari log. Ini untuk menghindari menutupi rahasia terlalu terperinci dari tingkat, membuat log tidak dapat dibaca. Untuk alasan ini, rahasia tidak boleh berisi data terstruktur. Jika, misalnya, "{ "foo": "bar" }" diatur sebagai rahasia, "bar" tidak ditutupi dari log.

Jenis	Perintah
Perintah tugas	AddAttachment, Complete, LogDetail, LogIssue, PrependPath, SetEndpoint, SetProgress, SetVariable, SetSecret, UploadFile, UploadSummary
Perintah artefak	Kaitkan, Unggah
Perintah build	AddBuildTag, UpdateBuildNumber, UploadLog
Perintah rilis	UpdateReleaseName

Format perintah pengelogan

Format umum untuk perintah pengelogan adalah:

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

Ada juga beberapa perintah pemformatan dengan sintaks yang sedikit berbeda:

##[command]message

Untuk memanggil perintah pengelogan, gemakan perintah melalui output standar.

Bash

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

PowerShell

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

Jalur file harus diberikan sebagai jalur absolut: di-root ke drive di Windows, atau dimulai dengan / di Linux dan macOS.

Catatan

Harap dicatat bahwa Anda tidak dapat menggunakan set -x perintah sebelum perintah pengelogan saat Anda menggunakan Linux atau macOS. Lihat pemecahan masalah, untuk mempelajari cara menonaktifkan set -x sementara untuk Bash.

Perintah pemformatan

Catatan

Gunakan pengodean UTF-8 untuk perintah pengelogan.

Perintah ini adalah pesan ke pemformat log di Azure Pipelines. Mereka menandai baris log tertentu sebagai kesalahan, peringatan, bagian yang dapat diciutkan, dan sebagainya.

Perintah pemformatan adalah:

##[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]

Anda bisa menggunakan perintah pemformatan dalam tugas bash atau 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]"

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]"

Perintah tersebut akan dirender dalam log seperti ini:

Blok perintah tersebut juga dapat diciutkan, dan terlihat seperti ini:

Perintah tugas

LogIssue: Mencatat kesalahan atau peringatan

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

Penggunaan

Catat kesalahan atau pesan peringatan dalam catatan garis waktu tugas saat ini.

Properti

• type = error atau warning (Diperlukan)
• sourcepath = lokasi file sumber
• linenumber = nomor baris
• columnnumber = nomor kolom
• code = kode kesalahan atau peringatan

Contoh: Mencatat kesalahan

Bash

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

PowerShell

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

Tip

exit 1 bersifat opsional, tetapi sering kali merupakan perintah yang akan Anda terbitkan segera setelah kesalahan dicatat. Jika Anda memilih Opsi Kontrol: Lanjutkan pada kesalahan, maka exit 1 akan menghasilkan build yang berhasil sebagian alih-alih build yang gagal. Sebagai alternatif, Anda juga dapat menggunakan task.logissue type=error.

Contoh: Mencatat peringatan tentang tempat tertentu dalam file

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."

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: Tampilkan persentase selesai

##vso[task.setprogress]current operation

Penggunaan

Atur kemajuan dan operasi saat ini untuk tugas saat ini.

Properti

• value = persentase penyelesaian

Contoh

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."

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."

Untuk melihat tampilannya, simpan dan antre build, lalu tonton build run. Amati bahwa indikator kemajuan berubah ketika tugas menjalankan skrip ini.

Selesai: Selesaikan garis waktu

##vso[task.complete]current operation

Penggunaan

Selesaikan catatan garis waktu untuk tugas saat ini, atur hasil tugas dan operasi saat ini. Jika hasil tidak disediakan, atur hasil ke berhasil.

Properti

• result =
  • Succeeded Tugas berhasil.
  • SucceededWithIssues Tugas mengalami masalah. Build akan diselesaikan karena sebagian berhasil di terbaik.
  • Failed Build akan selesai sebagai gagal. (Jika Opsi Kontrol: Lanjutkan pada opsi kesalahan dipilih, build akan diselesaikan sebagai berhasil sebagian di terbaik.)

Contoh

Catat tugas sebagai berhasil.

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

Atur tugas sebagai gagal. Sebagai alternatif, Anda juga dapat menggunakan 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: Membuat atau memperbarui catatan garis waktu untuk tugas

##vso[task.logdetail]current operation

Penggunaan

Membuat dan memperbarui rekaman garis waktu. Ini terutama digunakan secara internal oleh Azure Pipelines untuk melaporkan langkah- langkah, pekerjaan, dan tahapan. Meskipun pelanggan dapat menambahkan entri ke garis waktu, mereka biasanya tidak akan ditampilkan di UI.

Pertama kali kita melihat ##vso[task.detail] selama langkah, kita membuat catatan "garis waktu detail" untuk langkah tersebut. Kita dapat membuat dan memperbarui catatan garis waktu berlapis berdasarkan id dan parentid.

Penulis tugas harus mengingat GUID mana yang mereka gunakan untuk setiap rekaman garis waktu. Sistem pengelogan akan melacak GUID untuk setiap rekaman garis waktu, sehingga GUID baru akan menghasilkan catatan garis waktu baru.

Properti

• id = GUID rekaman garis waktu (Diperlukan)
• parentid = GUID rekaman garis waktu induk
• type = Jenis rekaman (Diperlukan untuk pertama kalinya, tidak dapat menimpa)
• name = Nama rekaman (Diperlukan untuk pertama kalinya, tidak dapat menimpa)
• order = urutan rekaman garis waktu (Diperlukan untuk pertama kalinya, tidak dapat menimpa)
• starttime = Datetime
• finishtime = Datetime
• progress = persentase penyelesaian
• state = Unknown | Initialized | InProgress | Completed
• result = Succeeded | SucceededWithIssues | Failed

Contoh

Buat catatan garis waktu akar baru:

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

Buat catatan garis waktu berlapis baru:

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

Perbarui catatan garis waktu yang ada:

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

SetVariable: Menginisialisasi atau memodifikasi nilai variabel

##vso[task.setvariable]value

Penggunaan

Mengatur variabel dalam layanan variabel taskcontext. Tugas pertama dapat mengatur variabel, dan tugas berikut dapat menggunakan variabel . Variabel diekspos ke tugas berikut sebagai variabel lingkungan.

Ketika issecret diatur ke true, nilai variabel akan disimpan sebagai rahasia dan ditutupi dari log. Variabel rahasia tidak diteruskan ke tugas sebagai variabel lingkungan dan sebaliknya harus diteruskan sebagai input.

Ketika isoutput diatur ke true sintaks untuk mereferensikan variabel yang ditetapkan bervariasi berdasarkan apakah Anda mengakses variabel tersebut dalam pekerjaan yang sama, pekerjaan di masa mendatang, atau tahap mendatang. Selain itu, jika isoutput diatur ke false sintaks untuk menggunakan variabel tersebut dalam pekerjaan yang sama berbeda. Lihat tingkat variabel output untuk menentukan sintaks yang sesuai untuk setiap kasus penggunaan.

Lihat mengatur variabel dalam skrip dan menentukan variabel untuk detail selengkapnya.

Properti

• variable = nama variabel (Diperlukan)
• issecret = boolean (Opsional, default ke false)
• isoutput = boolean (Opsional, default ke false)
• isreadonly = boolean (Opsional, default ke false)

Contoh

Bash

Atur variabel:

- 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

Baca variabel:

- 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)"

PowerShell

Atur variabel:

- 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

Baca variabel:

- 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)"

Output konsol:

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: Mendaftarkan nilai sebagai rahasia

##vso[task.setsecret]value

Penggunaan

Nilai terdaftar sebagai rahasia selama durasi pekerjaan. Nilai akan ditutupi dari log dari titik ini ke depan. Perintah ini berguna ketika rahasia diubah (misalnya base64 dikodekan) atau diturunkan.

Catatan: Kemunculan sebelumnya dari nilai rahasia tidak akan ditutupi.

Contoh

Bash

Atur variabel:

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

Baca variabel:

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

PowerShell

Atur variabel:

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

Baca variabel:

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

Output konsol:

Transformed and derived secrets will be masked: ***

SetEndpoint: Mengubah bidang koneksi layanan

##vso[task.setendpoint]value

Penggunaan

Atur bidang koneksi layanan dengan nilai tertentu. Nilai yang diperbarui akan dipertahankan di titik akhir untuk tugas berikutnya yang dijalankan dalam pekerjaan yang sama.

Properti

• id = ID koneksi layanan (Diperlukan)
• field = jenis bidang, salah satu dari authParameter, dataParameter, atau url (Diperlukan)
• key = kunci (Diperlukan, kecuali field = url)

Contoh

##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: Melampirkan file ke build

##vso[task.addattachment]value

Penggunaan

Unggah dan lampirkan lampiran ke rekaman garis waktu saat ini. File-file ini tidak tersedia untuk diunduh dengan log. Ini hanya dapat dirujuk oleh ekstensi menggunakan nilai jenis atau nama.

Properti

• type = jenis lampiran (Diperlukan)
• name = nama lampiran (Diperlukan)

Contoh

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

UploadSummary: Menambahkan beberapa konten Markdown ke ringkasan build

##vso[task.uploadsummary]local file path

Penggunaan

Unggah dan lampirkan ringkasan Markdown dari file .md di repositori ke rekaman garis waktu saat ini. Ringkasan ini akan ditambahkan ke ringkasan build/rilis dan tidak tersedia untuk diunduh dengan log. Ringkasan harus dalam format UTF-8 atau ASCII. Ringkasan akan muncul pada tab Ekstensi dari eksekusi alur Anda. Penyajian markdown pada tab Ekstensi berbeda dari penyajian wiki Azure DevOps.

Contoh

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

Ini adalah bentuk tangan pendek untuk perintah

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

UploadFile: Mengunggah file yang dapat diunduh dengan log tugas

##vso[task.uploadfile]local file path

Penggunaan

Unggah file yang menarik pengguna sebagai informasi log tambahan ke catatan garis waktu saat ini. File akan tersedia untuk diunduh bersama dengan log tugas.

Contoh

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

PrependPath: Menambahkan jalur ke variabel lingkungan PATH

##vso[task.prependpath]local file path

Penggunaan

Perbarui variabel lingkungan PATH dengan menambahkan sebelumnya ke PATH. Variabel lingkungan yang diperbarui akan tercermin dalam tugas berikutnya.

Contoh

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

Perintah artefak

Kaitkan: Menginisialisasi artefak

##vso[artifact.associate]artifact location

Penggunaan

Buat tautan ke Artefak yang ada. Lokasi artefak harus berupa jalur kontainer file, jalur VC, atau jalur berbagi UNC.

Properti

• artifactname = nama artefak (Diperlukan)
• type = jenis artefak (Diperlukan) container | filepath | versioncontrol | gitref | tfvclabel

Contoh

• container

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

• jalur file

  ##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
  

• Artefak Kustom

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

Unggah: Mengunggah artefak

##vso[artifact.upload]local file path

Penggunaan

Unggah file lokal ke folder kontainer file, dan secara opsional menerbitkan artefak sebagai artifactname.

Properti

• containerfolder = folder tempat file akan diunggah, folder akan dibuat jika diperlukan.
• artifactname = nama artefak. (Diperlukan)

Contoh

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

Catatan

Perbedaan antara Artifact.associate dan Artifact.upload adalah bahwa yang pertama dapat digunakan untuk membuat tautan ke artefak yang ada, sementara yang terakhir dapat digunakan untuk mengunggah/menerbitkan Artefak baru.

Perintah build

UploadLog: Mengunggah log

##vso[build.uploadlog]local file path

Penggunaan

Unggah log yang tertarik pengguna untuk membangun folder "logs\tool" kontainer.

Contoh

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

UpdateBuildNumber: Mengambil alih nomor build yang dihasilkan secara otomatis

##vso[build.updatebuildnumber]build number

Penggunaan

Anda dapat secara otomatis membuat nomor build dari token yang Anda tentukan dalam opsi alur. Namun, jika Anda ingin menggunakan logika Anda sendiri untuk mengatur nomor build, maka Anda dapat menggunakan perintah pengelogan ini.

Contoh

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

AddBuildTag: Menambahkan tag ke build

##vso[build.addbuildtag]build tag

Penggunaan

Tambahkan tag untuk build saat ini. Anda dapat memperluas tag dengan variabel yang telah ditentukan atau ditentukan pengguna. Misalnya, di sini tag baru ditambahkan dalam tugas Bash dengan nilai last_scanned-$(currentDate). Anda tidak dapat menggunakan titik dua dengan AddBuildTag.

Contoh

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

Perintah rilis

UpdateReleaseName: Ganti nama rilis saat ini

##vso[release.updatereleasename]release name

Penggunaan

Perbarui nama rilis untuk rilis yang sedang berjalan.

Catatan

Didukung di Azure DevOps dan Azure DevOps Server mulai versi 2020.

Contoh

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