Oakrey.Applications.Trace 8.0.0

dotnet add package Oakrey.Applications.Trace --version 8.0.0
                    
NuGet\Install-Package Oakrey.Applications.Trace -Version 8.0.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Oakrey.Applications.Trace" Version="8.0.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Oakrey.Applications.Trace" Version="8.0.0" />
                    
Directory.Packages.props
<PackageReference Include="Oakrey.Applications.Trace" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Oakrey.Applications.Trace --version 8.0.0
                    
#r "nuget: Oakrey.Applications.Trace, 8.0.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Oakrey.Applications.Trace@8.0.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Oakrey.Applications.Trace&version=8.0.0
                    
Install as a Cake Addin
#tool nuget:?package=Oakrey.Applications.Trace&version=8.0.0
                    
Install as a Cake Tool

Oakrey.Applications.Trace

A .NET 11 library for building file-based application tracers with observable status and elapsed-time updates.

NuGet package ID: Oakrey.Applications.Trace

Main features

  • TracerBase owns trace file creation, UTF-8 writing, elapsed-time measurement, status publication, and cleanup.
  • Derived tracers provide file naming, software naming, and custom header content.
  • StatusChanged publishes the initial Stopped state and subsequent running/stopped transitions.
  • TraceTimeChanged publishes monotonic elapsed time every 250 ms while tracing.
  • Repeated start and stop calls are idempotent.
  • Trace files are created only inside an existing configured trace directory.
  • Generated file paths are checked to prevent escaping the configured directory.
  • Operational logging uses placeholders and never records the full trace directory path.
  • Active traces are completed automatically during disposal.

Public contracts

ITracer defines the public application-facing contract. TracerBase.StartTrace remains protected, so a derived tracer exposes it publicly when implementing ITracer.

ITracerSettings provides:

  • LastTraceFolderPath
  • TraceFileNamingPolicy
  • LastTraceFileIncrement
  • Format

No public interface signatures are changed by the current implementation.

Requirements and direct dependencies

  • .NET 11
  • Oakrey.Files 4.0.0
  • Oakrey.Log.Abstractions 3.0.0
  • Oakrey.Telemetry 2.0.1
  • System.Reactive 6.1.0

Installation

dotnet add package Oakrey.Applications.Trace

Package Manager Console:

Install-Package Oakrey.Applications.Trace

Configuration

using Oakrey.Applications.Trace;
using Oakrey.Files;

public sealed class MyTracerSettings : ITracerSettings
{
    public string LastTraceFolderPath { get; set; } = @"C:\Traces";
    public FileNamingPolicy TraceFileNamingPolicy { get; set; } =
        FileNamingPolicy.DateTimeCompact;
    public int LastTraceFileIncrement { get; set; }
    public string Format { get; set; } = string.Empty;
}

The configured directory must already exist. Assigning TracePath normalizes it to an absolute path.

Example tracer

using Oakrey.Applications.Trace;

public sealed class AppTracer(ITracerSettings settings)
    : TracerBase(settings), ITracer
{
    protected override string FileName => "application";
    protected override string SwName => "MyApplication";
    protected override string Extension => "log";

    public new void StartTrace() => base.StartTrace();

    public void Write(string message) => WriteLine(message);

    protected override void WriteHeader()
    {
        WriteLine("=== MyApplication trace ===");
    }
}

Usage:

using AppTracer tracer = new(new MyTracerSettings());

using IDisposable statusSubscription = tracer.StatusChanged.Subscribe(
    status => Console.WriteLine($"Status: {status}"));

tracer.StartTrace();
tracer.Write("Work started");
tracer.StopTrace();

Lifecycle and safety notes

  • File output uses StreamWriter with UTF-8 without BOM and flushes each completed line.
  • Elapsed time uses Stopwatch, so system clock changes do not alter the measured duration.
  • Timer callbacks and file lifecycle operations are synchronized.
  • Rx observer callbacks are synchronous. Elapsed-time notifications originate on the timer thread unless the subscriber changes scheduler.
  • TracerStatus.Paused remains part of the enum but is not published by TracerBase.
  • Calling protected write functionality without an active trace skips the line and records a warning.
  • Calling trace operations after disposal throws ObjectDisposedException.
  • Subjects, timer, writer, and underlying stream are released even when no trace is active.
  • Trace lines are application data and can contain sensitive information; callers are responsible for filtering content before writing.

License

MIT - Copyright (c) Oakrey 2016-present

Product Compatible and additional computed target framework versions.
.NET net11.0 is compatible. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
8.0.0 48 11/15/2026
7.0.2 151 9/21/2026
7.0.1 142 8/6/2026
7.0.0 138 7/20/2026
2.0.6 134 7/8/2026
2.0.5 144 7/3/2026
2.0.4 139 5/22/2026
2.0.3 128 5/15/2026
2.0.2 156 3/13/2026
2.0.1 167 2/11/2026
2.0.0 471 11/18/2025
1.0.1 274 9/29/2025
1.0.0 356 4/17/2025