發行版本和工作項目深入解析

發行項
10/15/2024

發行版本和工作項目深入解析對於最佳化軟體開發生命週期極為重要。隨著應用程式的發展，務必密切監視每個發行版本及其工作項目。這些深入解析會強調效能瓶頸，並讓小組主動解決問題，確保部署和使用者體驗順暢。開發人員和專案關係人即可藉此做出決策、調整程式，並提供高品質的軟體。

Azure Pipelines 與 Application Insights 整合，可以在整個軟體開發生命週期持續監視 Azure DevOps 發行管線。

透過持續監視，發行管線可以從 Application Insights 和其他 Azure 資源納入監視資料。當發行管線偵測到 Application Insights 警示時，該管線可以設定閘道或復原部署，直到警示解決為止。如果通過所有檢查，部署就能從測試一路自動進行到實際執行，而不需手動介入。

設定連續監視

在 Azure DevOps 中，選取組織和專案。
在專案頁面的左側功能表上，選取 [管線]>[發行]。
選取 [新增] 旁的下拉式箭號，然後選取 [新增發行管線]。或者，如果您還沒有管線，請在出現的頁面上選取 [新增管線]。
在 [選取範本] 窗格上，搜尋並選取 [具備持續監視的 Azure App Service 部署]，然後選取 [套用]。
在 [階段 1] 方塊中，選取 [檢視階段工作] 的超連結。

在 [階段 1] 設定窗格中，填入下列欄位：

參數	值
階段名稱	提供階段名稱，或將其保留為 [階段 1]。
Azure 訂用帳戶	選取下拉式箭號，並且選取要使用的連結 Azure 訂用帳戶。
應用程式類型	選取下拉式箭號，並且選取您的應用程式類型。
App Service 名稱	輸入您 Azure App Service 的名稱。
Application Insights 的資源群組名稱	選取下拉式箭號，並且選取您想要使用的資源群組。
Application Insights 資源名稱	選取下拉式箭號，並且選取您已選資源群組適用的 Application Insights 資源。

若要使用預設警示規則設定儲存管線，請選取 Azure DevOps 視窗右上方的 [儲存]。輸入描述性註解，並且選取 [確定]。

修改警示規則

現成可用的 [具備持續監視的 Azure App Service 部署] 範本具有四個警示規則：[可用性]、[失敗的要求]、[伺服器回應時間] 及 [伺服器例外狀況]。您可以新增更多規則，也可以變更規則設定以符合您的服務等級需求。

修改警示規則設定：

在發行管線頁面的左窗格中，選取 [設定 Application Insights 警示]。

這四個預設警示規則是透過內嵌指令碼所建立：

$subscription = az account show --query "id";$subscription.Trim("`"");$resource="/subscriptions/$subscription/resourcegroups/"+"$(Parameters.AppInsightsResourceGroupName)"+"/providers/microsoft.insights/components/" + "$(Parameters.ApplicationInsightsResourceName)";
az monitor metrics alert create -n 'Availability_$(Release.DefinitionName)' -g $(Parameters.AppInsightsResourceGroupName) --scopes $resource --condition 'avg availabilityResults/availabilityPercentage < 99' --description "created from Azure DevOps";
az monitor metrics alert create -n 'FailedRequests_$(Release.DefinitionName)' -g $(Parameters.AppInsightsResourceGroupName) --scopes $resource --condition 'count requests/failed > 5' --description "created from Azure DevOps";
az monitor metrics alert create -n 'ServerResponseTime_$(Release.DefinitionName)' -g $(Parameters.AppInsightsResourceGroupName) --scopes $resource --condition 'avg requests/duration > 5' --description "created from Azure DevOps";
az monitor metrics alert create -n 'ServerExceptions_$(Release.DefinitionName)' -g $(Parameters.AppInsightsResourceGroupName) --scopes $resource --condition 'count exceptions/server > 5' --description "created from Azure DevOps";

您可以修改指令碼，並新增更多警示規則。您也可以修改警示條件。而且，您可以移除對您的部署目的而言沒有意義的警示規則。

新增部署條件

當您將部署閘道新增至發行管線時，超過您設定閾值的警示，可防止不必要的發行升級。解決該警示之後，部署就會自動繼續進行。

新增部署閘道：

在主要管線頁面的 [階段] 下方，根據哪個階段需要持續監視閘道而定，選取 [部署前的條件] 或 [部署後的條件] 符號。
在 [部署前的條件] 設定窗格中，將 [閘道] 設定為 [已啟用]。
在 [部署閘道] 旁邊，選取 [新增]。
從下拉式功能表中，選取 [查詢 Azure 監視器警示]。此選項可讓您存取 Azure 監視器和 Application Insights 警示。
在 [評估選項] 下方，輸入您想要設定的值，例如 [閘道重新評估之間的時間] 和 [閘道失敗後的逾時]。

檢視發行記錄

您可以在發行記錄中查看部署閘道行為及其他發行步驟。開啟記錄：

從管線頁面的左側功能表中，選取 [發行]。
選取任何發行。
在 [階段] 底下，選取任一階段以檢視發行摘要。
若要檢視記錄，請選取發行摘要中的 [檢視記錄]、選取任一階段中的 [成功] 或 [失敗] 超連結，或者將滑鼠暫留在任一階段上方，然後選取 [記錄]。

註釋會顯示您在哪裡部署新的組建，或是其他重要事件。註釋可讓您輕鬆查看變更是否對應用程式的效能有任何影響。 Azure Pipelines 組建系統可以自動建立這些註釋。您也可以從 PowerShell 建立註釋來標記您想要的任何事件。

使用 Azure Pipelines 組建的版本註釋

版本註釋是 Azure DevOps 雲端式 Azure Pipelines 服務的功能。

如果符合下列所有準則，部署工作會自動建立版本註釋：

您要部署的資源已連結至 Application Insights (透過 APPINSIGHTS_INSTRUMENTATIONKEY 應用程式設定)。
Application Insights 資源與您部署所在的資源位於相同的訂閱中。

您使用的是下列其中一個 Azure DevOps 管線工作：

工作程式碼	工作名稱	版本
AzureAppServiceSettings	Azure App Service 設定	任意
AzureRmWebAppDeployment	Azure App Service 部署	V3 及更高版本
AzureFunctionApp	Azure Functions	任意
AzureFunctionAppContainer	適用於容器的 Azure Functions	任意
AzureWebAppContainer	Azure 用於容器的 Web App	任意
AzureWebApp	Azure Web 應用程式	任意

注意

如果您仍在使用 Application Insights 註釋部署工作，您應該予以刪除。

設定發行註解

如果您無法使用上一節中的其中一個部署工作，需要在部署管線中新增內嵌指令碼工作。

瀏覽至新的或現有管線，並且選取工作。
新增工作，並選取 [Azure CLI]。
指定相關的 Azure 訂閱。將指令碼類型變更為 PowerShell，並將指令碼位置變更為「內嵌」。
將下一節中步驟 2 的 PowerShell 指令碼新增至內嵌指令碼。

新增下列引數。將角括弧預留位置取代為指令碼引數的值。 -releaseProperties 為選用。

    -aiResourceId "<aiResourceId>" `
    -releaseName "<releaseName>" `
    -releaseProperties @{"ReleaseDescription"="<a description>";
         "TriggerBy"="<Your name>" }

下列範例是您可以使用 build 和 release 變數，在選用的 releaseProperties 引數中設定的中繼資料。

-releaseProperties @{
 "BuildNumber"="$(Build.BuildNumber)";
 "BuildRepositoryName"="$(Build.Repository.Name)";
 "BuildRepositoryProvider"="$(Build.Repository.Provider)";
 "ReleaseDefinitionName"="$(Build.DefinitionName)";
 "ReleaseDescription"="Triggered by $(Build.DefinitionName) $(Build.BuildNumber)";
 "ReleaseEnvironmentName"="$(Release.EnvironmentName)";
 "ReleaseId"="$(Release.ReleaseId)";
 "ReleaseName"="$(Release.ReleaseName)";
 "ReleaseRequestedFor"="$(Release.RequestedFor)";
 "ReleaseWebUrl"="$(Release.ReleaseWebUrl)";
 "SourceBranch"="$(Build.SourceBranch)";
 "TeamFoundationCollectionUri"="$(System.TeamFoundationCollectionUri)" }

選取 [儲存]。

使用 Azure CLI 建立版本註釋

您可以使用 CreateReleaseAnnotation PowerShell 指令碼，從任何您想要的流程中建立註釋，而不需要使用 Azure DevOps。

登入 Azure CLI。

建立下列指令碼的本機複本，並予以呼叫 CreateReleaseAnnotation.ps1。

param(
    [parameter(Mandatory = $true)][string]$aiResourceId,
    [parameter(Mandatory = $true)][string]$releaseName,
    [parameter(Mandatory = $false)]$releaseProperties = @()
)

# Function to ensure all Unicode characters in a JSON string are properly escaped
function Convert-UnicodeToEscapeHex {
  param (
    [parameter(Mandatory = $true)][string]$JsonString
  )
  $JsonObject = ConvertFrom-Json -InputObject $JsonString
  foreach ($property in $JsonObject.PSObject.Properties) {
    $name = $property.Name
    $value = $property.Value
    if ($value -is [string]) {
      $value = [regex]::Unescape($value)
      $OutputString = ""
      foreach ($char in $value.ToCharArray()) {
        $dec = [int]$char
        if ($dec -gt 127) {
          $hex = [convert]::ToString($dec, 16)
          $hex = $hex.PadLeft(4, '0')
          $OutputString += "\u$hex"
        }
        else {
          $OutputString += $char
        }
      }
      $JsonObject.$name = $OutputString
    }
  }
  return ConvertTo-Json -InputObject $JsonObject -Compress
}

$annotation = @{
    Id = [GUID]::NewGuid();
    AnnotationName = $releaseName;
    EventTime = (Get-Date).ToUniversalTime().GetDateTimeFormats("s")[0];
    Category = "Deployment"; #Application Insights only displays annotations from the "Deployment" Category
    Properties = ConvertTo-Json $releaseProperties -Compress
}

$annotation = ConvertTo-Json $annotation -Compress
$annotation = Convert-UnicodeToEscapeHex -JsonString $annotation  

$accessToken = (az account get-access-token | ConvertFrom-Json).accessToken
$headers = @{
    "Authorization" = "Bearer $accessToken"
    "Accept"        = "application/json"
    "Content-Type"  = "application/json"
}
$params = @{
    Headers = $headers
    Method  = "Put"
    Uri     = "https://management.azure.com$($aiResourceId)/Annotations?api-version=2015-05-01"
    Body    = $annotation
}
Invoke-RestMethod @params

注意

您的註釋必須將類別設為部署，才能顯示在 Azure 入口網站中。
如果您收到錯誤「要求包含實體主體，但沒有 Content-Type 標頭」，請嘗試移除下列這一行中的 replace 參數。

$body = (ConvertTo-Json $annotation -Compress)

使用下列程式碼呼叫 PowerShell 指令碼。以您的值取代角括弧預留位置。 -releaseProperties 為選用。

     .\CreateReleaseAnnotation.ps1 `
      -aiResourceId "<aiResourceId>" `
      -releaseName "<releaseName>" `
      -releaseProperties @{"ReleaseDescription"="<a description>";
          "TriggerBy"="<Your name>" }

引數	定義	注意
`aiResourceId`	目標 Application Insights 資源的資源識別碼。	範例： /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/MyRGName/providers/microsoft.insights/components/MyResourceName
`releaseName`	要提供已建立版本註釋的名稱。
`releaseProperties`	用來將自訂中繼資料附加至註釋。	選擇性

檢視註解

注意

Application Insights 的 [計量] 窗格中目前未提供版本註釋。

每當您使用發行範本來部署新的發行，會將註釋傳送至 Application Insights。您可以在下列位置檢視註釋：

效能：
失敗：
使用方式：
活頁簿：

在任何記錄型活頁簿查詢中，視覺效果會沿著 X 軸顯示時間：

若要在您的活頁簿啟用註釋，請前往 [進階設定]，並選取 [顯示註釋]。

顯示 [進階設定] 功能表的螢幕擷取畫面，其中醒目提示顯示註釋核取方塊。

選取任一註釋標記可開啟關於發行版本的詳細資料，包括要求者、原始檔控制分支、發行管線和環境。

使用 API 金鑰的版本註釋

版本註釋是 Azure DevOps 雲端式 Azure Pipelines 服務的功能。

重要

使用 API 金鑰的註釋已被取代。建議改用 Azure CLI。

安裝註釋延伸模組 (一次)

若要建立版本註釋，請裝 Visual Studio Marketplace 中的許多可用 Azure DevOps 延伸模組之一。

登入您的 Azure DevOps 專案。
在 [Visual Studio Marketplace][版本註釋延伸模組] 頁面上，選取您的 Azure DevOps 組織。選取 [安裝] 將延伸模組新增至您的 Azure DevOps 組織。

您只需要為 Azure DevOps 組織安裝一次此延伸模組。現在，您可以為組織中的任何專案設定版本註釋。

使用 API 金鑰設定版本註釋

為每個 Azure Pipelines 發行範本建立個別的 API 金鑰。

登入 Azure 入口網站，開啟監視應用程式的 Application Insights 資源。或者，如果您沒有資源，請建立新的 Application Insights 資源。
開啟 [API 存取] 索引標籤，並複製 Application Insights 識別碼。
在另一個瀏覽器視窗中，開啟或建立管理 Azure Pipelines 部署的發行範本。
選取 [新增工作]，然後從功能表選取 [Application Insights 版本註釋] 工作。

注意

版本註釋工作目前僅支援以 Windows 為基礎的代理程式。這不會在 Linux、macOS 或其他型別的代理程式中執行。
在 [應用程式識別碼] 下，貼上您從 [API 存取] 索引標籤複製的 Application Insights 識別碼。
返回 Application Insights [API 存取] 視窗，選取 [建立 API 金鑰]。
在 [建立 API 金鑰] 視窗中，輸入描述，選取 [寫入註釋]，然後選取 [產生金鑰]。複製新的金鑰。
在發行範本視窗的 [變數] 索引標籤中，選取 [新增] 以建立新 API 金鑰的變數定義。
在 [名稱] 下，輸入 ApiKey。在 [值] 下，貼上您從 [API 存取] 索引標籤複製的 API 金鑰。
在主要發行範本視窗中選取 [儲存] 以儲存範本。

注意

API 金鑰的限制在 REST API 速率限制文件中加以說明。

轉換至新的版本註釋

若要使用新的版本註釋：

移除版本註釋延伸模組。
移除 Azure Pipelines 部署中的 Application Insights 版本註釋工作。
使用 Azure Pipelines 或 Azure CLI 建立新版本註釋。

工作項目整合功能可讓您輕鬆地在 GitHub 或 Azure DevOps 中建立工作項目，並在其中內嵌相關的 Application Insights 資料。

與傳統版本相比，新的工作項目整合提供下列功能：

進階欄位，例如受託人、專案或里程碑。
存放庫圖示，讓您可以區分 GitHub 和 Azure DevOps 活頁簿。
任意數目存放庫或工作項目的多個設定。
透過 Azure Resource Manager 範本進行部署。
預先建置且可自訂的關鍵字查詢語言 (KQL) 查詢，可用來將 Application Insights 資料新增至您的工作項目。
可自訂的活頁簿範本。

建立和設定工作項目範本

若要建立工作項目範本，請移至您的 Application Insights 資源，然後在左側的 [設定] 底下選取 [工作項目]，然後在頂端選取 [建立新範本]

如果目前沒有任何範本存在，您也可以從端對端交易詳細資料索引標籤建立工作項目範本。選取事件，然後在右側選取 [建立工作項目]，然後選取 [開始使用活頁簿範本]。
選取 [建立新範本] 之後，您可以選擇您的追蹤系統、命名活頁簿、連結到選取的追蹤系統，然後選擇要儲存範本的區域 (預設值是 Application Insights 資源所在的區域)。 URL 參數是您存放庫的預設 URL，例如 https://github.com/myusername/reponame 或 https://dev.azure.com/{org}/{project}。

您可以直接從範本本身設定特定的工作項目屬性。這包括受託人、反覆項目路徑、專案等 (視您的版本控制提供者而定)。

注意

針對內部部署 Azure DevOps 環境，https://dev.azure.com/test/test 這類範例 URL 可用來作為 Azure DevOps 專案 URL 的預留位置。建立工作項目範本之後，您即可在產生的 Azure 活頁簿內修改 URL 及其驗證規則。

建立工作項目

您可以從 [效能]、[失敗]、[可用性] 或其他索引標籤存取任何端對端交易詳細資料，然後從中存取新的範本。

若要建立工作項目，請移至端對端交易詳細資料，選取事件，然後選取 [建立工作項目]，並選擇您的工作項目範本。
瀏覽器中的新索引標籤會開啟您選取的追蹤系統。在 Azure DevOps 中，您可以建立錯誤或工作，而在 GitHub 中，您可以在存放庫中建立新的問題。新的工作項目會自動使用 Application Insights 所提供的內容資訊來建立。