Exercise - Use telemetry in a .NET Aspire project

  • 10 minutes

In this exercise, you use the OpenTelemetry APIs to add custom data to the logs. You also examine the logs to find your custom events.

Install prerequisites

The prerequisites for this exercise are:

  • .NET 8
  • Visual Studio 2022 Preview
  • Docker Desktop
  • .NET Aspire workload in Visual Studio

If these packages are already installed, you can skip ahead to begin working with OpenTelemetry logging.

Install .NET 8

Follow this .NET 8 link, and select the correct installer for your operating system. For example, if you're using Windows 11, and a modern processor, select the x64 .NET 8 SDK for Windows.

After the download is complete, run the installer and follow the instructions. In a terminal window, run the following command to verify that the installation was successful:

dotnet --version

You should see the version number of the .NET SDK you installed. For example:

8.0.300-preview.24203.14

Install Visual Studio 2022 Preview

Follow this Visual Studio 2022 Preview link, and select Download Preview. After the download is complete, run the installer and follow the instructions.

Install Docker Desktop

Follow this Docker Desktop link, and select the correct installer for your operating system. After the download is complete, run the installer and follow the instructions. For the best performance and compatibility, use the WSL 2 backend.

Open the Docker Desktop application and accept the service agreement.

Install the .NET Aspire workload in Visual Studio

Install the .NET Aspire workload using the .NET CLI:

  1. Open a terminal.

  2. Update .NET workloads with this command:

    dotnet workload update

    You should see a message that the workloads are updated successfully.

    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. Install the .NET Aspire workload with this command:

    dotnet workload install aspire

    You should see a message that the Aspire workload is successfully installed.

    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. Verify that the .NET Aspire workload is installed with this command:

    dotnet workload list

    You should see the details of the .NET Aspire workload.

     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.

Clone the sample app

Let's use git to obtain a sample app. Because the app includes .NET Aspire, OpenTelemetry is included with default logging, metrics, and distributed tracing:

  1. In the command line, browse to a folder of your choice where you can work with code.

  2. Execute the following command to clone the Northern Mountains eShop sample application:

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

Log a message using compile time source generation

We can use compile time source generation to create performant logging code automatically. Let's implement that technique for getting products brands:

  1. Open Visual Studio and select Open a project or solution.

  2. Browse to the folder where you cloned the starter project. Open the start folder, select eShop.aspiretelemetry.sln, and then select Open.

  3. In Solution Explorer, expand WebApp > Services and then double-click CatalogService.cs.

  4. Locate the following line of code, which declares the CatalogService class:

    public class CatalogService(HttpClient httpClient)

  5. To use compile time source generation, we have to make this class partial and use dependency injection to obtain the logger. Modify the line to match this code:

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

  6. Next, anywhere in the CatalogService class outside other methods, create a new static partial method named LogGetBrands:

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

  7. Immediately before that line, add the LoggerMessageAttribute and define the logging level and message:

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

  8. Locate the GetBrands() method and the following line of code in it:

    var uri = $"{remoteServiceBaseUrl}catalogBrands";

  9. To call your new logging method, insert the following code after that line:

    LogGetBrands(uri, logger);

  10. To save your changes press CTRL + S or select File > Save All.

Test the instrumentation

Now, we test the compile time source generation logging:

  1. In Visual Studio, to start the app in debugging mode, press F5, or select Debug > Start Debugging.

  2. If the Start Docker Desktop message appears, select Yes. The app starts and displays the .NET Aspire dashboard in a browser tab.

  3. To make some requests, locate the webapp project in the Resources list and then select one of its entries in the Endpoints column:

    Screenshot showing the .NET Aspire dashboard and the location of the webapp's endpoint links.

  4. A new browser tab appears and displays the Northern Mountains homepage. The brands list is included on the left-hand side. Switch back to the .NET Aspire dashboard and on the left-hand menu, select Structured.

  5. In the Filter textbox, type Getting brands. The page displays your logged event:

    Screenshot showing filtered events in the .NET Aspire dashboard.

  6. In the Details column for your event, select View. The dashboard opens a lower pane to display the details of the entry.

  7. Close the browser tabs and in Visual Studio, press SHIFT + F5 or select Debug > Stop Debugging.

  8. Close Visual Studio.