练习 - 在 .NET Aspire 项目中使用遥测

  • 10 分钟

在本练习中，你需要使用 OpenTelemetry API 将自定义数据添加到日志。 你还需要检查日志以查找自定义事件。

安装先决条件

本练习的先决条件如下：

  • .NET 8
  • Visual Studio 2022 预览版
  • Docker Desktop
  • Visual Studio 中的 .NET Aspire 工作负载

如果已安装这些包，则可以直接跳到开始使用 OpenTelemetry 日志记录的步骤。

安装 .NET 8

单击此 .NET 8 链接，然后根据操作系统选择正确的安装程序。 例如，如果使用的是 Windows 11 和新式处理器，请选择适用于 Windows 的 x64 .NET 8 SDK。

下载完成后，运行安装程序并按照说明操作。 在终端窗口中，运行以下命令以验证安装是否成功：

dotnet --version

应会看到所安装的 .NET SDK 版本号。 例如：

8.0.300-preview.24203.14

安装 Visual Studio 2022 预览版

单击此 Visual Studio 2022 预览版链接，然后选择“下载预览版”。 下载完成后，运行安装程序并按照说明操作。

安装 Docker Desktop

单击此 Docker Desktop 链接，然后根据操作系统选择正确的安装程序。 下载完成后，运行安装程序并按照说明操作。 为了获得最佳性能和兼容性，请使用 WSL 2 后端。

打开 Docker Desktop 应用程序并接受服务协议。

在 Visual Studio 中安装 .NET Aspire 工作负载

使用 .NET CLI 安装 .NET Aspire 工作负载：

  1. 打开终端。

  2. 使用以下命令更新 .NET 工作负载：

    dotnet workload update

    应会看到一条消息，指出工作负载已成功更新。

    No workloads installed for this feature band. To update workloads installed with earlier SDK versions, include the --from-previous-sdk option.
Updated advertising manifest microsoft.net.sdk.ios.
Updated advertising manifest microsoft.net.workload.mono.toolchain.net6.
Updated advertising manifest microsoft.net.sdk.android.
Updated advertising manifest microsoft.net.workload.emscripten.net7.
Updated advertising manifest microsoft.net.workload.emscripten.net6.
Updated advertising manifest microsoft.net.sdk.macos.
Updated advertising manifest microsoft.net.workload.emscripten.current.
Updated advertising manifest microsoft.net.workload.mono.toolchain.current.
Updated advertising manifest microsoft.net.sdk.maui.
Updated advertising manifest microsoft.net.workload.mono.toolchain.net7.
Updated advertising manifest microsoft.net.sdk.maccatalyst.
Updated advertising manifest microsoft.net.sdk.tvos.
Updated advertising manifest microsoft.net.sdk.aspire.
No workloads installed for this feature band. To update workloads installed with earlier SDK versions, include the --from-previous-sdk option.

Successfully updated workload(s): .

  3. 使用以下命令安装 .NET Aspire 工作负载：

    dotnet workload install aspire

    你应会看到一条消息，指出已成功安装 Aspire 工作负载。

    Installing Aspire.Hosting.Sdk.Msi.x64 ...... Done
Installing Aspire.ProjectTemplates.Msi.x64 ..... Done
Installing Aspire.Hosting.Orchestration.win-x64.Msi.x64 ............. Done
Installing Aspire.Hosting.Msi.x64 ..... Done
Installing Aspire.Dashboard.Sdk.win-x64.Msi.x64 ....... Done

Successfully installed workload(s) aspire.

  4. 使用以下命令验证是否安装了 .NET Aspire 工作负载：

    dotnet workload list

    应会看到 .NET Aspire 工作负载的详细信息。

     Installed Workload Id      Manifest Version      Installation Source
---------------------------------------------------------------------------------------------
aspire                     8.0.0/8.0.100         SDK 8.0.300-preview.24203, VS 17.10.34902.84

Use `dotnet workload search` to find additional workloads to install.

克隆示例应用

让我们使用 git 获取示例应用。 由于该应用包含 .NET Aspire，因此默认日志记录、指标和分布式跟踪中包含 OpenTelemetry：

  1. 在命令行中，浏览到你选择的、可在其中处理代码的文件夹。

  2. 执行以下命令克隆 Northern Mountains eShop 示例应用程序：

    git clone -b aspire-telemetry https://github.com/MicrosoftDocs/mslearn-aspire-starter

使用编译时源生成记录消息

我们可以使用编译时源生成来自动创建高性能的日志记录代码。 让我们实现该技术来获取产品品牌：

  1. 打开 Visual Studio 并选择“打开项目或解决方案”。

  2. 浏览到初学者项目克隆到的文件夹。 打开“开始”文件夹，选择 eShop.aspiretelemetry.sln，然后选择“打开”。

  3. 在“解决方案资源管理器”中，展开“WebApp”>“服务”，然后双击“CatalogService.cs”。

  4. 找到以下代码行，其中声明了 CatalogService 类：

    public class CatalogService(HttpClient httpClient)

  5. 若要使用编译时源生成，我们必须将此类设为 partial，并使用依赖项注入来获取记录器。 修改该行以匹配以下代码：

    public partial class CatalogService(HttpClient httpClient, ILogger<CatalogService> logger)

  6. 接下来，在 CatalogService 类中其他方法之外的任意位置创建一个名为 LogGetBrands 的新 static partial 方法：

    public static partial void LogGetBrands(string uri, ILogger logger);

  7. 紧接该行之前，添加 LoggerMessageAttribute 并定义日志记录级别和消息：

    [LoggerMessage(
EventId = 0,
Level = LogLevel.Information,
Message = "Getting brands from URI: {uri}")]

  8. 找到 GetBrands() 方法及其中的以下代码行：

    var uri = $"{remoteServiceBaseUrl}catalogBrands";

  9. 若要调用新的日志记录方法，请在该行后面插入以下代码：

    LogGetBrands(uri, logger);

  10. 若要保存更改，请按 CTRL + S 或选择“文件”>“全部保存”。

测试检测

现在，我们将测试编译时源生成日志记录：

  1. 在 Visual Studio 中，若要在调试模式下启动应用，请按 F5 或选择“调试”>“开始调试”。

  2. 如果出现“启动 Docker Desktop”消息，请选择“是”。 应用将会启动并在浏览器选项卡中显示 .NET Aspire 仪表板。

  3. 若要发出一些请求，请在“资源”列表中找到“webapp”项目，然后在“终结点”列中选择此项目的条目之一：

    显示 .NET Aspire 仪表板和 Web 应用终结点链接位置的屏幕截图。

  4. 此时会出现一个新的浏览器选项卡，其中显示了 Northern Mountains 主页。 品牌列表显示在左侧。 切换回 .NET Aspire 仪表板，在左侧菜单上选择“结构化”。

  5. 在“筛选器”文本框中，键入“获取品牌”。 页面会显示记录的事件：

    显示 .NET Aspire 仪表板中已筛选事件的屏幕截图。

  6. 在事件的“详细信息”列中，选择“查看”。 仪表板中会打开一个下部窗格来显示条目的详细信息。

  7. 关闭浏览器选项卡，然后在 Visual Studio 中按 SHIFT + F5 或选择“调试”>“停止调试”。

  8. 关闭 Visual Studio。