.NET Skills for Claude Code

In .NET, metric instruments are accessed via System.Diagnostics.Metrics.Meter. They are categorized into two main types based on how they are triggered:

Synchronous Instruments

These are called directly in your code when a specific event occurs. They are ideal for high-frequency events like request processing.

• Counter: Monotonically increasing (only up). Use for request counts, errors, or bytes sent.
• UpDownCounter: Can increase or decrease. Use for queue sizes or active connections.
• Histogram: Captures distributions (e.g., latency percentiles). Use for request durations or response sizes.
• Gauge (.NET 9+): Records an instantaneous snapshot. Use for non-cumulative measurements like temperature.

Asynchronous/Observable Instruments

These are called by the OpenTelemetry SDK at a defined collection interval via a callback. They are ideal for polling system state.

• ObservableCounter: Reports a monotonically increasing value (e.g., total CPU time).
• ObservableGauge: Reports an instantaneous value (e.g., current memory usage).
• ObservableUpDownCounter: Reports a value that can go up or down (e.g., active tasks by priority).

Is the value a cumulative total that only goes up?
  → YES: Can you increment it on every event?
           → YES: Counter (synchronous)
           → NO (polled periodically):  ObservableCounter (async)
  → NO:  Is it a distribution/percentile you need?
           → YES: Histogram
  → NO:  Can the value go both up AND down?
           → YES: Can you update it on every event?
                    → YES: UpDownCounter (synchronous)
                    → NO (polled periodically): ObservableUpDownCounter (async)
           → NO (instantaneous snapshot): Can you record it on every event?
                    → YES: Gauge (synchronous, .NET 9+)
                    → NO (polled periodically): ObservableGauge (async)

Place a Directory.Build.props file at your solution root to apply centralized build configurations to all projects in the directory tree. This is useful for managing metadata, C# language settings, versioning, and SourceLink configuration in one place.

Key Patterns:

• Dynamic Copyright: Use $([System.DateTime]::Now.Year) to automate copyright year updates.
• Reusable Framework Properties: Define target framework versions once and reference them in individual .csproj files using $(PropertyName) syntax.
• SourceLink: Configure PublishRepositoryUrl, EmbedUntrackedSources, IncludeSymbols, and SymbolPackageFormat to enable step-through debugging for NuGet packages.

<Project>
  <PropertyGroup>
    <Copyright>Copyright © 2020-$([System.DateTime]::Now.Year) Your Company</Copyright>
    <LangVersion>latest</LangVersion>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
  </PropertyGroup>

  <PropertyGroup>
    <NetLibVersion>net8.0</NetLibVersion>
  </PropertyGroup>

  <PropertyGroup>
    <PublishRepositoryUrl>true</PublishRepositoryUrl>
    <EmbedUntrackedSources>true</EmbedUntrackedSources>
    <IncludeSymbols>true</IncludeSymbols>
    <SymbolPackageFormat>snupkg</SymbolPackageFormat>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.SourceLink.GitHub" PrivateAssets="All" />
  </ItemGroup>
</Project>

For performance-critical code, use Span<T> and Memory<T> instead of byte[] or string to perform operations without unnecessary allocations.

• Span<T>: Use for synchronous operations, stack-allocated buffers, and slicing data without allocation.
• ReadOnlySpan<T>: Use for read-only views or method parameters where the data should not be modified.
• Memory<T>: Use for asynchronous operations, as Span cannot cross await boundaries.
• ReadOnlyMemory<T>: Use for read-only asynchronous operations.
• ArrayPool<T>: Use for large temporary buffers (typically >1KB) to reduce Garbage Collector (GC) pressure by renting and returning arrays.
• byte[]: Use only when you need to store data long-term or interface with APIs that specifically require arrays.

// Span<T> for synchronous, zero-allocation operations
public int ParseOrderId(ReadOnlySpan<char> input)
{
    if (!input.StartsWith("ORD-"))
        throw new FormatException("Invalid order ID format");

    var numberPart = input.Slice(4);
    return int.Parse(numberPart);
}

// Memory<T> for async operations
public async Task<int> ReadDataAsync(
    Memory<byte> buffer,
    CancellationToken cancellationToken)
{
    return await _stream.ReadAsync(buffer, cancellationToken);
}

// ArrayPool for temporary large buffers
public async Task ProcessLargeFileAsync(Stream stream, CancellationToken cancellationToken)
{
    var buffer = ArrayPool<byte>.Shared.Rent(8192);
    try
    {
        int bytesRead;
        while ((bytesRead = await stream.ReadAsync(buffer.AsMemory(), cancellationToken)) > 0)
        {
            ProcessChunk(buffer.AsSpan(0, bytesRead));
        }
    }
    finally
    {
        ArrayPool<byte>.Shared.Return(buffer);
    }
}

Sampling controls which traces are recorded and exported to reduce overhead.

Built-in Samplers

• AlwaysOnSampler: Records every span.
• AlwaysOffSampler: Drops every span.
• TraceIdRatioBasedSampler(ratio): Samples a fixed fraction (0.0–1.0).
• ParentBasedSampler(root): Follows the parent's sampling decision (recommended for production). It uses a root sampler for new traces and follows the parent's decision for child spans.

Configuration Methods

Via Code (AddOpenTelemetry):

builder.Services.AddOpenTelemetry()
    .WithTracing(tracing => tracing
        .AddSource("MyApp.MyComponent")
        .SetSampler(new ParentBasedSampler(
            new TraceIdRatioBasedSampler(0.1))) // 10% of root spans
        .AddOtlpExporter());

Via Environment Variables:

• OTEL_TRACES_SAMPLER: Set to always_on, always_off, traceidratio, or parentbased_traceidratio.
• OTEL_TRACES_SAMPLER_ARG: The argument for the sampler (e.g., 0.1 for 10%).

# Ratio-based sampling (10%)
export OTEL_TRACES_SAMPLER=traceidratio
export OTEL_TRACES_SAMPLER_ARG=0.1

# Parent-based with ratio for roots
export OTEL_TRACES_SAMPLER=parentbased_traceidratio
export OTEL_TRACES_SAMPLER_ARG=0.1

Unlike Rx.NET which uses interfaces, R3 uses abstract classes for its core types. This allows for centralized subscription tracking (e.g., via ObservableTracker).

The R3 Grammar: (OnNext | OnErrorResume)* OnCompleted(Result)?

Key differences from Rx:

• Errors are decoupled from termination: OnErrorResume allows you to handle an error without killing the subscription. Only OnCompleted ends the stream.
• Termination carries a Result: OnCompleted provides a Result object which indicates if the stream ended via Result.Success or Result.Failure(exception).

public abstract class Observable<T>
{
    public IDisposable Subscribe(Observer<T> observer);     // tracked centrally
    protected abstract IDisposable SubscribeCore(Observer<T> observer);
}

public abstract class Observer<T> : IDisposable               // the observer IS the subscription
{
    public void OnNext(T value);
    public void OnErrorResume(Exception error);               // error WITHOUT unsubscribing
    public void OnCompleted(Result result);                   // success OR failure terminates
}

Use record types for DTOs, messages, events, and domain entities to ensure immutability by default.

• Use record class (the default) for reference types like entities, aggregates, and DTOs with multiple properties.
• Use IReadOnlyList<T> for collections within records to prevent mutation of the underlying collection.
• Use init-only properties for controlled initialization.

// Simple immutable DTO
public record CustomerDto(string Id, string Name, string Email);

// Record with validation in constructor
public record EmailAddress
{
    public string Value { get; init; }

    public EmailAddress(string value)
    {
        if (string.IsNullOrWhiteSpace(value) || !value.Contains('@'))
            throw new ArgumentException("Invalid email address", nameof(value));

        Value = value;
    }
}

// Records with collections - use IReadOnlyList
public record ShoppingCart(
    string CartId,
    string CustomerId,
    IReadOnlyList<CartItem> Items
) 
{
    public decimal Total => Items.Sum(item => item.Price * item.Quantity);
}