Skip to content

Installation

Jump to bottom
Kieron Lanning edited this page Apr 16, 2026 · 9 revisions

Installation Guide

This guide covers installing and configuring the Purview Telemetry Source Generator in your project.

Requirements

Supported Frameworks

  • .NET 8.0 or higher (Recommended)
  • .NET Framework 4.8 or higher

Supported IDEs

  • Visual Studio 2022 (17.0 or higher)
  • Visual Studio Code with C# extension
  • JetBrains Rider 2022.3 or higher
  • Any IDE with Roslyn analyzer support

Installation Methods

Method 1: .NET CLI (Recommended)

dotnet add package Purview.Telemetry.SourceGenerator --version 4.1.0

Method 2: Package Manager Console (Visual Studio)

Install-Package Purview.Telemetry.SourceGenerator -Version 4.1.0

Method 3: Edit Project File (.csproj)

Add directly to your .csproj file:

<ItemGroup>
  <PackageReference Include="Purview.Telemetry.SourceGenerator" Version="4.1.0">
    <PrivateAssets>all</PrivateAssets>
    <IncludeAssets>analyzers</IncludeAssets>
  </PackageReference>
</ItemGroup>

Important

The <PrivateAssets>all</PrivateAssets> and <IncludeAssets>analyzers</IncludeAssets> tags ensure the source generator is used during compilation but not included in your published output.

Method 4: Directory.Build.props (Multi-Project Solutions)

For solutions with multiple projects that all need telemetry, create or edit Directory.Build.props at the solution root:

<Project>
  <ItemGroup>
    <PackageReference Include="Purview.Telemetry.SourceGenerator" Version="4.1.0">
      <PrivateAssets>all</PrivateAssets>
      <IncludeAssets>analyzers</IncludeAssets>
    </PackageReference>
  </ItemGroup>
</Project>

This automatically adds the package to all projects in the solution.

Verifying Installation

Step 1: Create a Test Interface

Create a file ITelemetryTest.cs:

using Purview.Telemetry;

[Logger]
public interface ITelemetryTest
{
    [Info]
    void TestMessage(string message);
}

Step 2: Rebuild the Project

dotnet build

Step 3: Check for Generated Files

If EmitCompilerGeneratedFiles is enabled (see below), check:

obj/Debug/net8.0/generated/Purview.Telemetry.SourceGenerator/

You should see generated files with names like:

  • {Namespace}.TelemetryTestCore.Logging.g.cs
  • {Namespace}.TelemetryTestCoreDIExtension.DependencyInjection.g.cs

Step 4: Use the Generated Extension Method

In your Program.cs:

services.AddTelemetryTest();  // This should have IntelliSense support

If IntelliSense recognizes AddTelemetryTest(), installation was successful! ✅

Configuration Options

Enable Generated File Output (Recommended for Development)

To inspect generated code during development, add to your .csproj:

<PropertyGroup>
  <EmitCompilerGeneratedFiles>true</EmitCompilerGeneratedFiles>
  <CompilerGeneratedFilesOutputPath>$(BaseIntermediateOutputPath)/generated</CompilerGeneratedFilesOutputPath>
</PropertyGroup>

Generated files appear in obj/Debug/net8.0/generated/.

Conditional Compilation

To include source generator attributes in your assembly (usually not needed):

<PropertyGroup>
  <DefineConstants>PURVIEW_TELEMETRY_ATTRIBUTES</DefineConstants>
</PropertyGroup>

By default, attributes are marked [Conditional("PURVIEW_TELEMETRY_ATTRIBUTES")] and are removed at runtime.

Disable Logging Generation

If Microsoft.Extensions.Logging is not available in your project:

<PropertyGroup>
  <DefineConstants>EXCLUDE_PURVIEW_TELEMETRY_LOGGING</DefineConstants>
</PropertyGroup>

This excludes logging-related attributes and code generation.

Additional Dependencies

The source generator itself has no runtime dependencies. However, to use the generated code, you need:

For Activities

# .NET 5.0+ (included in SDK)
# No additional packages needed

For Logging (Generation v2 - Recommended)

dotnet add package Microsoft.Extensions.Logging
dotnet add package Microsoft.Extensions.Telemetry.Abstractions

For Logging (Generation v1 - Legacy)

dotnet add package Microsoft.Extensions.Logging

For Metrics

# .NET 8.0+ (included in SDK)
# No additional packages needed for IMeterFactory

For OpenTelemetry (Recommended)

To export telemetry to observability platforms:

# Core packages
dotnet add package OpenTelemetry.Extensions.Hosting
dotnet add package OpenTelemetry.Exporter.Console

# Optional: Specific exporters
dotnet add package OpenTelemetry.Exporter.Jaeger
dotnet add package OpenTelemetry.Exporter.Prometheus.AspNetCore
dotnet add package Azure.Monitor.OpenTelemetry.Exporter

Project Types

ASP.NET Core Applications

<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Purview.Telemetry.SourceGenerator" Version="4.1.0">
      <PrivateAssets>all</PrivateAssets>
      <IncludeAssets>analyzers</IncludeAssets>
    </PackageReference>
  </ItemGroup>
</Project>

Console Applications

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net8.0</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Purview.Telemetry.SourceGenerator" Version="4.1.0">
      <PrivateAssets>all</PrivateAssets>
      <IncludeAssets>analyzers</IncludeAssets>
    </PackageReference>
  </ItemGroup>
</Project>

Class Libraries

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Purview.Telemetry.SourceGenerator" Version="4.1.0">
      <PrivateAssets>all</PrivateAssets>
      <IncludeAssets>analyzers</IncludeAssets>
    </PackageReference>
  </ItemGroup>
</Project>

.NET Aspire Projects

<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Aspire.Hosting" Version="8.0.0" />
    <PackageReference Include="Purview.Telemetry.SourceGenerator" Version="4.1.0">
      <PrivateAssets>all</PrivateAssets>
      <IncludeAssets>analyzers</IncludeAssets>
    </PackageReference>
  </ItemGroup>
</Project>

See the Sample Application for a complete .NET Aspire example.

Multi-Targeting

If your project targets multiple frameworks:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFrameworks>net8.0;net48</TargetFrameworks>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Purview.Telemetry.SourceGenerator" Version="4.1.0">
      <PrivateAssets>all</PrivateAssets>
      <IncludeAssets>analyzers</IncludeAssets>
    </PackageReference>
  </ItemGroup>

  <!-- Conditional dependencies for older frameworks -->
  <ItemGroup Condition="'$(TargetFramework)' == 'net48'">
    <PackageReference Include="System.Diagnostics.DiagnosticSource" Version="8.0.0" />
  </ItemGroup>
</Project>

IDE Setup

Visual Studio 2022

  1. Install latest Visual Studio 2022 (17.8 or higher recommended)
  2. Ensure "Source Generators" support is enabled (on by default)
  3. After adding the package, rebuild to trigger generation
  4. Generated files appear in Solution Explorer under Dependencies > Analyzers > Purview.Telemetry.SourceGenerator

Visual Studio Code

  1. Install the C# extension (ms-dotnettools.csharp)
  2. Ensure the latest .NET SDK is installed
  3. Open the project folder
  4. Run dotnet build from the terminal
  5. IntelliSense should recognize generated types after build

JetBrains Rider

  1. Install Rider 2022.3 or higher
  2. Rider automatically detects source generators
  3. After adding the package, rebuild the solution
  4. Generated types appear in IntelliSense immediately

Troubleshooting Installation

Issue: "Type or namespace 'Purview' could not be found"

Cause: Package not installed or build not run.

Solution:

dotnet restore
dotnet build

Issue: "No extension method 'Add{InterfaceName}' found"

Cause: Source generator didn't run or interface not properly annotated.

Solution:

  1. Ensure the interface has [ActivitySource], [Logger], or [Meter] attribute
  2. Rebuild: dotnet build --no-incremental
  3. Check for build errors in the output

Issue: "Generated files not visible in IDE"

Cause: EmitCompilerGeneratedFiles not enabled.

Solution: Add to .csproj:

<PropertyGroup>
  <EmitCompilerGeneratedFiles>true</EmitCompilerGeneratedFiles>
</PropertyGroup>

Issue: "Source generator errors during build"

Cause: Incompatible package version or corrupted NuGet cache.

Solution:

# Clear NuGet cache
dotnet nuget locals all --clear

# Restore packages
dotnet restore

# Clean and rebuild
dotnet clean
dotnet build

Issue: "Attributes not recognized (red squiggles)"

Cause: IDE hasn't detected the generator yet.

Solution:

  1. Rebuild the project: dotnet build
  2. Restart the IDE
  3. Check the package is correctly referenced in .csproj

Issue: "Multiple definitions of type 'ActivitySourceAttribute'"

Cause: Package referenced multiple times or in multiple Directory.Build.props files.

Solution: Remove duplicate references and ensure the package is only included once per project.

Upgrading from v3

If you're upgrading from v3.x to v4.x:

Update Package Version

<!-- Before -->
<PackageReference Include="Purview.Telemetry.SourceGenerator" Version="4.1.0" />

<!-- After -->
<PackageReference Include="Purview.Telemetry.SourceGenerator" Version="4.1.0" />

Update Using Statements

// Before (v3)
using Purview.Telemetry.Activities;
using Purview.Telemetry.Logging;
using Purview.Telemetry.Metrics;

// After (v4)
using Purview.Telemetry;  // Single namespace!

Handle Breaking Changes

See the Breaking Changes guide for:

  • Namespace consolidation details
  • OpenTelemetry naming conventions (default in v4)
  • Migration paths and compatibility options

Validating Installation

Run this checklist to confirm everything is working:

  • Package installed (dotnet list package shows it)
  • Project builds without errors (dotnet build)
  • IntelliSense recognizes using Purview.Telemetry;
  • Test interface compiles successfully
  • Generated DI extension method appears in IntelliSense
  • Application runs and telemetry is emitted

Next Steps

Version History

Version Release Date Notes
4.0.0-prerelease.2 2026-02-14 Added TelemetryNames generated classes
4.0.0-prerelease.1 2026-02-08 OTel-aligned naming across MELT
4.0.0-prerelease.0 2026-02-08 Namespace consolidation, OTel naming conventions
3.2.4 2025-07-27 Last stable v3 release

See the CHANGELOG for complete version history.

Important

Like this tool?

Consider helping children around the world affected by conflict. You can donate any amount to War Child here - any amount can help save a life.

War Child logo

Purview Telemetry Source Generator v4.0.0-prerelease.1 | Home | Getting Started | FAQ | Breaking Changes | GitHub

Clone this wiki locally