探索 .NET.NET Aspire 儀錶板

發行項
12/16/2024

在後續各節中，您會探索如何建立 .NET.NET Aspire 專案，並著手執行下列工作：

使用從專案範本產生的應用程式來調查儀錶板的功能，如快速入門：建置您的第一個 .NET.NET Aspire 專案中所述。
深入探索 .NET.NET Aspire 儀錶板應用程式的功能。

本文中精選的螢幕快照會展示深色主題。如您要主題選取的詳細資訊，請參閱主題選取。

儀錶板驗證

當您執行 .NET.NET Aspire 應用程式主機時，協調器會啟動所有應用程式的相依資源，然後開啟儀錶板的瀏覽器視窗。 .NET .NET Aspire 儀錶板需要使用者令牌型驗證，因為它會顯示環境變數和其他敏感性資訊。

從 Visual Studio 或 Visual Studio Code 啟動儀錶板時（具有 C# Dev Kit 延伸模組），瀏覽器會自動登入，且儀錶板會直接開啟。這是典型的開發人員 F5 體驗，而驗證登入流程是由 .NET.NET Aspire 工具自動化。

不過，如果您從命令行啟動應用程式主機，就會看到登入頁面。主控台視窗會顯示您可以選取的URL，以在瀏覽器中開啟儀錶板。

URL 包含令牌查詢字串（具有對應至 t 名稱部分的令牌值），用來 登入儀錶板。如果您的主控台支援，您可以按住 ctrl 鍵，然後選取連結以在瀏覽器中開啟儀錶板。這個方法比從主控台複製令牌容易，並將它貼到登入頁面。如果您最終在儀錶板登入頁面上沒有上述任一方法，您隨時可以返回控制台以複製令牌。

登入頁面接受令牌，並提供如何取得令牌的實用指示，如下列螢幕快照所示：

從主控台複製令牌並將其貼入登入頁面之後，請選取 [登入] 按鈕。

儀錶板會將令牌保存為瀏覽器持續性 cookie，該令牌仍有效三天。持續性 Cookie 有到期日，即使在關閉瀏覽器之後仍然有效。這表示如果使用者關閉並重新開啟瀏覽器，就不需要再次登入。如需詳細資訊，請參閱執行儀錶板檔安全性考慮。

資源頁面

資源頁面是 .NET.NET Aspire 儀錶板的預設首頁。此頁面會列出 .NET 解決方案中包含的所有 .NET Aspire 專案、容器和可執行檔。例如，入門應用程式包含兩個專案：

apiservice：使用最小 API 建置的後端 API 專案。
webfrontend：使用 Blazor建置的前端 UI 專案。

儀錶板也會提供每個資源的基本詳細數據：

類型：顯示資源是專案、容器或可執行檔。
名稱：資源的名稱。
狀態：顯示資源目前是否正在執行。
- 錯誤：在 [狀態] 數據行內，錯誤會顯示為具有錯誤計數的徽章。快速瞭解哪些資源報告錯誤很有用。選取徽章會帶您前往該資源的語意記錄，並在錯誤層級篩選。
開始時間：資源開始執行時。
來源：裝置上資源的位置。
端點：直接連線到執行中資源的一或多個 URL。
記錄：資源記錄頁面的連結。
Actions：可在資源上執行的一組動作：
- 停止/啟動：根據目前的狀態，停止（或啟動）資源。
- 主控台記錄：流覽至資源的主控台記錄。
- 省略號：具有額外資源特定動作的子功能表：
  - 檢視詳細數據：檢視資源詳細數據。
  - 主控台記錄：流覽至資源的主控台記錄。
  - 結構化記錄：流覽至資源的結構化記錄。
  - 追蹤：流覽至資源的追蹤。
  - 計量：流覽至資源的計量。
  - 重新啟動：停止再啟動資源。

請考慮下列資源頁面的螢幕快照：

資源動作

每個資源都有一組可用的動作，這些動作會根據資源的目前狀態有條件地啟用。例如，如果資源正在執行，則會啟用停止動作。如果資源停止，則會啟用啟動動作。同樣地，某些動作在無法使用時會停用，例如，某些資源沒有結構化記錄。在這些情況下，會停用動作結構化記錄。

停止或啟動資源

.NET .NET Aspire 儀錶板可讓您選取 [動作] 數據行中的 [停止] 或 [開始] 按鈕，來停止或啟動資源。請考慮下列資源頁面的螢幕快照，其中已選取 [停止] 按鈕：

當您選取 [停止時，資源會停止執行，而狀態數據行會更新以反映變更。

注意

針對項目資源，附加調試程式時，會在重新啟動時重新附加。

接著會啟用 [開始] 按鈕，讓您再次啟動資源。此外，儀錶板會顯示動作結果的快顯通知：

當資源處於非執行狀態時，會啟用 [開始] 按鈕。選取 [開始] 啟動資源，而 [狀態] 數據行會更新以反映變更。接著會啟用 [停止] 按鈕，讓您再次停止資源。儀錶板會顯示動作結果的快顯通知：

提示

相依於其他已停止或重新啟動的資源，可能會遇到暫時錯誤。這是預期的行為，而且通常會在相依資源再次處於執行狀態時解析。

資源子功能表動作

選取 [動作] 數據行中的水準省略號圖示，會開啟具有其他資源特定動作的子功能表。除了內建資源子功能表動作之外，您也可以藉由定義自定義命令來定義自訂資源動作。如需詳細資訊，請參閱 .NET.NET Aspire中的自定義資源命令。針對內建資源子功能表動作，請考慮下列螢幕快照：

下列子選單動作可供使用：

檢視詳細數據：檢視資源詳細數據。
主控台記錄：流覽至資源的主控台記錄。
結構化記錄：流覽至資源的結構化記錄。
追蹤：流覽至資源的追蹤。
計量：流覽至資源的計量。
重新啟動：停止再啟動資源。

重要

可能有資源具有停用的子功能表動作。當他們被停用時，它們會呈現灰色。例如，下列螢幕快照顯示停用的子功能表動作：

在文字可視化檢視中複製或開啟

若要檢視特定資料行的文字可視化檢視，請將滑鼠停留時，您會看到垂直省略號圖示。選取圖示以顯示可用的選項：

[複製到剪貼簿]
在文字可視化檢視中開啟

請考慮下列省略號選單選項的螢幕快照：

當您選取 [在文字可視化檢視 中開啟] 選項時，模式對話框隨即開啟，並顯示較大的格式文字。請考慮下列文字可視化檢視模式對話框的螢幕快照：

某些值會格式化為 JSON 或 XML。在這些情況下，文字可視化檢視可讓 選取格式 下拉式清單切換不同的格式。

資源詳細數據

您可以選取 [動作] 數據行中的省略號按鈕，然後選取 [檢視詳細數據]，以取得每個資源的完整詳細數據。 [詳細數據] 頁面提供資源的完整檢視：

儀錶板右上方的搜尋列也提供篩選列表的選項，這對於具有許多資源的 .NET.NET Aspire 專案很有用。若要選取顯示的資源類型，請下拉式清單篩選文字框左側的箭號：

[.NET.NET Aspire 儀錶板資源] 頁面中資源類型選取器清單的螢幕快照。

在此範例中，清單中只會顯示容器。例如，如果您在建立 Redis 項目時啟用，您應該會看到列出的 .NET Aspire 容器：

可執行檔是獨立進程。您可以將 .NET.NET Aspire 項目設定為在啟動期間執行獨立可執行檔，不過預設的入門範本預設不包含任何可執行檔。

下列螢幕快照顯示有錯誤的專案範例：

選取錯誤計數徽章會流覽至 [結構化記錄] 頁面，並套用篩選，只顯示與資源相關的記錄：

若要查看錯誤的詳細記錄專案，請選取 [檢視] 按鈕，以使用結構化記錄專案詳細數據開啟清單下方的視窗：

如需結構化記錄的詳細資訊和範例，請參閱結構化記錄頁面一節。

注意

如果在未設定的資源服務的情況下啟動儀錶板，則無法使用資源頁面。儀錶板會改為在 [結構化記錄] 頁面上開始。這是在獨立模式中執行儀錶板時的默認體驗，而不需要額外的設定。

如需設定資源服務的詳細資訊，請參閱儀表板設定。

監視頁面

.NET .NET Aspire 儀錶板提供各種方式來檢視應用程式的記錄、追蹤和計量。這項資訊可讓您追蹤應用程式的行為和效能，以及診斷所發生的任何問題。

主控台記錄頁面

主控台記錄 頁面會顯示應用程式中每個資源已傳送至標準輸出的文字。記錄是監視應用程式健康情況並診斷問題的有用方式。記錄會根據來源而有所不同，例如專案、容器或可執行檔。

當您開啟 [主控台記錄] 頁面時，您必須在 [選取資源] 下拉式清單中選取來源。

如果您選取專案，實時記錄會以一組與記錄嚴重性對應的文體色彩呈現;綠色作為範例資訊。請考慮下列項目記錄的範例螢幕快照，其中已選取 apiservice 專案：

發生錯誤時，會在記錄中設定樣式，使其易於識別。請考慮下列具有錯誤的項目記錄範例螢幕快照：

如果您選取容器或可執行檔，格式設定與專案不同，但仍可使用詳細資訊行為資訊。請考慮下列容器記錄的範例螢幕快照，其中已選取 cache 容器：

資源複本

使用 WithReplicas API 複寫項目資源時，它們會以最上層具名資源專案下的資源選取器來表示，並具有要指標的圖示。每個復寫的資源都會列在最上層資源專案底下，其對應的唯一名稱。請考慮下列復寫項目資源的範例螢幕快照：

上述螢幕快照顯示具有兩個複本 catalogservice (application) 專案，catalogservice-2bpj2qdq6k 和 catalogservice-6ljdin0hc0。每個複本都有自己的記錄集，可藉由選取複本名稱來檢視。

結構化記錄頁面

.NET Aspire 使用 OpenTelemetry自動設定項目記錄。流覽至 [結構化記錄] 頁面，以檢視 .NET.NET Aspire 項目的語意記錄。語意或結構化記錄可讓您更輕鬆地儲存和查詢記錄事件，因為會保留log-event message-template 和 message-parameters，而不只是將它們轉換成格式化的訊息。您會注意到頁面上使用資料行顯示之不同記錄的全新結構：

資源：記錄來源的資源。
層級：項目的記錄層級，例如資訊、警告或錯誤。
時間戳：記錄發生的時間。
訊息：記錄檔的詳細數據。
追蹤：如果適用，則為記錄的相關追蹤連結。
詳細數據：關於記錄專案的其他詳細數據或元數據。

請考慮下列語意記錄範例螢幕快照：

篩選結構化記錄

結構化記錄頁面也提供搜尋列，依服務、層級或訊息篩選記錄。您可以使用 [層級] 下拉式清單來依記錄層級進行篩選。您也可以選取篩選圖示按鈕來篩選任何記錄屬性，以開啟進階篩選對話方塊。

請考慮下列螢幕快照，其中顯示結構化記錄，並篩選為在消息正文中顯示具有「主控」的專案：

追蹤頁面

流覽至 [追蹤] 頁面，以檢視您應用程式的所有追蹤。 .NET .NET Aspire 會自動為應用程式中的不同專案設定追蹤。分散式追蹤是一種診斷技術，可協助工程師將應用程式內的失敗和效能問題當地語系化，特別是可能分散於多部計算機或進程的失敗和效能問題。如需詳細資訊，請參閱 .NET 分散式追蹤。這項技術會透過應用程式追蹤要求，並將不同應用程式整合所完成的工作相互關聯。追蹤也有助於識別要求的不同階段完成時間。追蹤頁面會顯示下列資訊：

時間戳：追蹤完成時。
Name：追蹤的名稱，前面加上項目名稱。
Spans：要求所涉及的資源。
持續時間：完成要求所需的時間。此數據行包含星形圖示，可說明要求的持續時間，與清單中的其他人比較。

篩選追蹤

追蹤頁面也提供搜尋列，以依名稱或範圍篩選追蹤。套用篩選條件，並注意追蹤結果會立即更新。請考慮下列已套用至 weather 篩選的追蹤螢幕快照，並注意搜尋字詞在結果中醒目提示的方式：

在 [[新增篩選] 對話框中篩選追蹤時，選取參數和對應的 Condition之後，值選取專案會預先填入所選參數的可用值。請考慮下列螢幕快照，其中已選取 ] 對話框：

結合多個資源的遙測

當資源有多個複本時，您可以篩選遙測以一次檢視所有實例的數據。選取標示為 (application)的父資源，如下列螢幕快照所示：

的所有實例進行篩選

選取父資源之後，追蹤頁面會顯示來自資源所有實例的遙測。

追蹤詳細數據

追蹤詳細數據頁面包含與要求相關的各種詳細數據，包括：

追蹤詳細數據：追蹤啟動時。
持續時間：完成要求所需的時間。
Resources：要求所涉及的資源數目。
深度：要求所涉及的圖層數目。
範圍總計：要求所涉及的範圍總數。

每個範圍都會以資料表中的數據列表示，並包含 Name。如果錯誤發生在追蹤的特定範圍內，範圍也會顯示錯誤圖示。具有用戶端/取用者類型的範圍，但伺服器上沒有範圍、顯示箭號圖示，然後顯示目的地位址。這代表對 .NET.NET Aspire 專案外部系統的用戶端呼叫。例如，HTTP 要求外部 Web API 或資料庫呼叫。

在追蹤詳細數據頁面中，有 [檢視記錄] 按鈕，會帶您前往結構化記錄頁面，並套用篩選，只顯示與要求相關的記錄。請考慮描述結構化記錄頁面的範例螢幕快照，其中包含套用篩選條件，只顯示與追蹤相關的記錄：