Davasorus.Utility.DotNet.Services 2026.2.2.4

Davasorus.Utility.DotNet.Services

Davasorus.Utility.DotNet.Services provides a set of service/client abstractions for managing Windows services (start, stop, load, manipulate) in .NET 8+ applications. It is designed for use with dependency injection (DI). End users should only interact with the service interfaces; the services handle all client interactions, error handling, and logging.

Note: Only interact with the service interfaces (e.g., IStartServiceService, IStopServicesService, ILoadServicesService, IManipulateServiceService) in your application code. The service classes manage all communication with their respective client classes internally.

Breaking Changes in This Release

The root namespace has been renamed from Tyler.Utility.DotNet.Services.* to Davasorus.Utility.DotNet.Services.* to align with the published NuGet package identity. Consumers upgrading from any prior 2026.2.1.x version must update their using directives:

// Before
using Tyler.Utility.DotNet.Services.Configuration;
using Tyler.Utility.DotNet.Services.Windows_Services.Start_Services.Service;

// After
using Davasorus.Utility.DotNet.Services.Configuration;
using Davasorus.Utility.DotNet.Services.Windows_Services.Start_Services.Service;

No public API signatures changed. This is purely a namespace rename.

B1 — API contract modernization (this version)

DI lifetimes changed to Singleton

All registrations in AddWindowsServices now use TryAddSingleton. Consumers depending on Scoped or Transient resolution semantics will see one instance for the lifetime of the host. Consumers wanting to override the default implementations (e.g., for testing) can pre-register their implementation before calling AddWindowsServices — TryAddSingleton honors consumer pre-registrations.

IDisposable removed from all 8 interfaces

ILoadServicesClient, ILoadServicesService, IManipulateServiceClient, IManipulateServiceService, IStartServiceClient, IStartServiceService, IStopServicesClient, IStopServicesService no longer declare void Dispose();. Consumers using using var x = service; patterns must drop the using keyword:

// Before
using var loadService = scope.ServiceProvider.GetRequiredService<ILoadServicesService>();
var list = await loadService.GetServiceList("HOST");

// After
var loadService = scope.ServiceProvider.GetRequiredService<ILoadServicesService>();
var list = await loadService.GetServiceList("HOST");

Method return types changed to ServiceResult<T> / ServiceResult

Every public method now returns a ServiceResult (non-generic) or ServiceResult<T> (generic) wrapping the operation's outcome. The streaming method GetServiceListStreaming is the one exception — it retains IAsyncEnumerable<ServiceObj> and exceptions propagate to the consumer's await foreach.

// Before
var list = await loadService.GetServiceList("HOST");
if (list != null) { ... }

// After
var result = await loadService.GetServiceList("HOST");
if (result.IsSuccess && result.Value != null)
{
    var list = result.Value;
    // ...
}
// or, to handle failure:
if (!result.IsSuccess)
{
    logger.LogError(result.Error, "List failed; reported to SQS: {Reported}", result.WasReportedToSqs);
}

ServiceResult carries IsSuccess, Error, and WasReportedToSqs. The WasReportedToSqs flag tells callers whether the package's catch-template successfully sent the error to SQS — useful for chain composition (don't double-report).

Manipulate methods now throw on null input (previously silent return false)

SetSpecifiedServiceOnMachineToEnabled, SetSpecifiedServiceOnMachineToDisabled, SetSpecifiedServiceOnMachineToManual and their Client-tier counterparts previously returned false silently when called with null or whitespace input. They now throw ArgumentException consistently with the other tiers. Inputs are validated via ArgumentException.ThrowIfNullOrWhiteSpace(...).

ServiceOptions changes

• ServiceOperationTimeoutSeconds has been split into two fields:
  • GeneralOperationTimeoutSeconds (default 60s) for general service operations
  • WebOperationTimeoutSeconds (default 30s) for IIS / w3svc operations
• EnableErrorLogging now actually does work — setting it to false skips SQS reporting (previously the field was read by nothing)
• MaxRetryAttempts now actually drives retry behavior via Polly (previously the field was read by nothing)

ServiceOptionsBuilder method renames

// Before
services.AddWindowsServices(svc => svc.WithOperationTimeout(TimeSpan.FromSeconds(45)));

// After
services.AddWindowsServices(svc => svc.WithGeneralOperationTimeout(TimeSpan.FromSeconds(45)));
// or
services.AddWindowsServices(svc => svc.WithWebOperationTimeout(TimeSpan.FromSeconds(20)));

Polly retry on transient exceptions

Transient WMI / SCM / Registry exceptions (IOException, TimeoutException, SocketException, ServiceProcess.TimeoutException) now retry automatically per MaxRetryAttempts (default 3 retries). Non-transient exceptions (ArgumentException, UnauthorizedAccessException, etc.) do NOT retry. Worst-case wall-clock for a fully failing operation: (MaxRetryAttempts + 1) × timeout ≈ 4 × 60s = 240s for general operations under default settings.

If retry behavior is unwanted, set MaxRetryAttempts = 0 in options.

WaitForStatus is now an async polling loop

The blocking ServiceController.WaitForStatus(...) call inside Start/Stop has been replaced with an async polling loop (Internal/WaitForStatusAsyncHelper). The new loop polls every 500ms instead of blocking a thread-pool thread for the full timeout duration. Consumers observing thread-pool exhaustion under heavy Start/Stop load will see relief.

C2a — Telemetry semantic conventions migration

Two consumer-visible wire-format changes in this release:

Cache result tag changed from cache.hit (bool) to cache.result (enum)

Activity tags emitted by GetServiceList and GetServiceDescription on cache hit/miss now use the canonical OpenTelemetry-aligned enum-valued cache.result key instead of the bool cache.hit key. Dashboards observing the old key will return zero results.

# Before (dashboard query)
{cache.hit="true"}

# After
{cache.result="hit"}

# Before
{cache.hit="false"}

# After
{cache.result="miss"}

The cache.key tag is unchanged — only the bool→enum change applies.

Tag-key prefix normalization under windows.service.*

All Windows-service-related tag keys and event names now use the windows.service.* prefix per OpenTelemetry domain-prefix conventions. Dashboards observing the old (non-prefixed) keys will return zero results.

# Before                          → After
registry.key.path                  → windows.service.registry.key_path
service.timeout_seconds            → windows.service.timeout_seconds

# Event names
registry.operation.start           → windows.service.registry.operation_start
registry.set_value                 → windows.service.registry.set_value
registry.verified                  → windows.service.registry.verified
service.status.change              → windows.service.status_change

The existing windows.service.* keys (host, name, operation, type, success, count) are unchanged — they already used the prefix.

Migration: see the new "Observability" section below for the canonical constant locations.

C2b — Telemetry deepening

Five consumer-visible changes in this release. Most affect observability dashboards and APM topology; none affect functional behavior.

ActivityKind changed from Internal to Client on outbound operations

GetServiceList, GetServiceDescription, GetServiceListStreaming (WMI), EnableService/DisableService/SetServiceToManual (Registry), Start (SCM), Stop (SCM) now create activities with ActivityKind.Client instead of ActivityKind.Internal. Service-layer wrappers stay Internal. APM topology diagrams will start rendering Services as a "client" calling out to "Windows host" instead of as a leaf in the trace tree.

windows.service.success tag now emitted on all operations

Previously only Manipulate* operations emitted this tag. After C2b, Start, Stop, Load operations also emit it (true on happy path, false on caught exception). Dashboards can now filter on {windows.service.success="false"} across all operations uniformly.

Cache key suffix :v2 and envelope wire-format change

The Services pkg's internal cache entries now use the :v2 key suffix and a new CachedWithContext<T> envelope shape carrying both the cached value and a W3C traceparent string. Pre-C2b cache entries (key without :v2) are NOT read; this forces a one-time cache miss + WMI re-population on first read per host/operation after deploy. Operational impact: one burst of WMI queries during the deploy window. Once re-populated, the v2 entry is cached for the same 30-day-sliding/60-day-absolute TTL.

If you read this package's cache directly (you shouldn't), the stored value shape is now CachedWithContext<List<ServiceObj>> (or <string> for Description) instead of the bare collection/string.

Cache-hit activities now emit ActivityLink to the populate-call trace

When a GetServiceList or GetServiceDescription returns a cached value, the resulting activity carries one ActivityLink back to the trace context of the call that originally populated the cache. Dashboards visualizing trace relationships can now show "cache hit → original populate" connections.

If the stored traceparent fails to parse (e.g., corrupted cache value), the cache-hit emits a cache.activitylink.malformed event and continues normally — the cache-hit semantics never become a cache-miss due to link parsing failure.

Five new OpenTelemetry metrics under windows_service.*

windows_service.operations              Counter<long>     tags: operation, host, success
windows_service.operation.duration      Histogram<double> unit: ms; tags: operation, host
windows_service.cache.hits              Counter<long>     tags: operation, host
windows_service.cache.misses            Counter<long>     tags: operation, host
windows_service.errors                  Counter<long>     tags: operation, host, exception.type

All metrics live on a single Meter named Davasorus.Utility.Services.WindowsServices. They're auto-wired by AddDavasorusTelemetry's wildcard meter subscription (Davasorus.Utility.*). See the new "Observability" section below.

Features

• Start, stop, and manipulate Windows services on remote or local hosts
• Retrieve service lists and descriptions, with streaming support
• Strongly-typed async APIs
• OpenTelemetry distributed tracing via ActivitySource on all operations
• Robust error handling and logging (ILogger + SQS integration)
• Designed for DI: all services registered as Singleton via TryAddSingleton
• Returns ServiceResult<T> for every public method, with explicit success/failure outcomes and SQS-report tracking
• Automatic retry on transient WMI/SCM/Registry exceptions via Polly resilience pipeline
• Async-polling wait loop replaces blocking WaitForStatus, avoiding thread-pool exhaustion under heavy load
• Hybrid validation: programmer errors throw, operational outcomes return

Dependency Injection Setup

Register all services using the AddWindowsServices() extension method:

using Davasorus.Utility.DotNet.Services.Configuration;

services.AddWindowsServices();

Or with fluent configuration:

services.AddWindowsServices(svc => svc
    .WithGeneralOperationTimeout(TimeSpan.FromSeconds(60))
    .WithWebOperationTimeout(TimeSpan.FromSeconds(30))
    .WithRetryPolicy(3)
    .WithErrorLogging(true));

This registers the following services automatically:

Example Usage

Start a Service

public class MyServiceStarter
{
    private readonly IStartServiceService _startService;
    public MyServiceStarter(IStartServiceService startService)
    {
        _startService = startService;
    }

    public async Task StartAsync(string host, string serviceName)
    {
        await _startService.StartService(host, serviceName);
    }
}

Stop a Service

public class MyServiceStopper
{
    private readonly IStopServicesService _stopService;
    public MyServiceStopper(IStopServicesService stopService)
    {
        _stopService = stopService;
    }

    public async Task StopAsync(string host, string serviceName)
    {
        await _stopService.StopService(host, serviceName);
    }
}

Load Services List

public class MyServiceLoader
{
    private readonly ILoadServicesService _loadService;
    public MyServiceLoader(ILoadServicesService loadService)
    {
        _loadService = loadService;
    }

    public async Task<List<ServiceObj>?> GetServicesAsync(string host)
    {
        return await _loadService.GetServiceList(host);
    }
}

Manipulate Service State

public class MyServiceManipulator
{
    private readonly IManipulateServiceService _manipulateService;
    public MyServiceManipulator(IManipulateServiceService manipulateService)
    {
        _manipulateService = manipulateService;
    }

    public async Task<bool> EnableServiceAsync(string host, string serviceName)
    {
        return await _manipulateService.SetSpecifiedServiceOnMachineToEnabled(host, serviceName);
    }
}

API Overview

IStartServiceService

• Task StartService(string hostName, string serviceName, TimeSpan? timeout = null) Starts the specified Windows service on the given host. Defaults to 60 seconds if no timeout is specified.

• Task StartWebServices(string hostName, TimeSpan? timeout = null) Starts all web-related Windows services on the specified host. Defaults to 30 seconds if no timeout is specified.

IStopServicesService

• Task StopService(string hostName, string serviceName, TimeSpan? timeout = null) Stops the specified Windows service on the given host. Defaults to 60 seconds if no timeout is specified.

• Task StopWebServices(string hostName, TimeSpan? timeout = null) Stops all web-related Windows services on the specified host. Defaults to 30 seconds if no timeout is specified.

ILoadServicesService

• Task<List<ServiceObj>?> GetServiceList(string hostName) Retrieves a list of Windows services from the specified host. Returns a list of ServiceObj instances representing each service, or null if retrieval fails.

• Task<string> GetServiceDescription(string hostName, string serviceName) Gets the description of a specific Windows service on the given host. Returns the service description as a string.

• IAsyncEnumerable<ServiceObj> GetServiceListStreaming(string hostName) Streams Windows services from the specified host as they are discovered. Returns an async stream of ServiceObj instances.

IManipulateServiceService

• Task<bool> SetSpecifiedServiceOnMachineToEnabled(string hostName, string serviceName) Enables the specified Windows service on the given host, setting its startup type to "Automatic". Returns true if successful.

• Task<bool> SetSpecifiedServiceOnMachineToDisabled(string hostName, string serviceName) Disables the specified Windows service on the given host, setting its startup type to "Disabled". Returns true if successful.

• Task<bool> SetSpecifiedServiceOnMachineToManual(string hostName, string serviceName) Sets the specified Windows service on the given host to "Manual" startup type. Returns true if successful.

Observability

This package emits OpenTelemetry activities and metrics. Both are auto-wired into the OTel pipeline by AddDavasorusTelemetry's default wildcard subscription (Davasorus.Utility.*). No additional registration extension is required.

Activities

Tag keys come from Davasorus.Utility.DotNet.Telemetry's SemanticConventions.WindowsService group (and SemanticConventions.Cache for cache tags). Reference them in dashboard query / processing code:

using Davasorus.Utility.DotNet.Telemetry;

// Tag keys
var hostKey       = SemanticConventions.WindowsService.Host;       // "windows.service.host"
var operationKey  = SemanticConventions.WindowsService.Operation;  // "windows.service.operation"
var successKey    = SemanticConventions.WindowsService.Success;    // "windows.service.success"
var cacheKey      = SemanticConventions.Cache.Key;                 // "cache.key"
var cacheResult   = SemanticConventions.Cache.Result;              // "cache.result" — values: "hit" | "miss"

Metrics

Single Meter: Davasorus.Utility.Services.WindowsServices.

ActivityLink: cache-hit → populate trace

GetServiceList and GetServiceDescription cache-hit activities carry one ActivityLink back to the trace context of the call that originally populated the cache value (recorded in the cached envelope as a W3C traceparent). Visualize cache-hit relationships in your tracing UI.

If the stored traceparent is malformed (corrupted serialization, unexpected wire format), the cache-hit activity emits a cache.activitylink.malformed event and continues with the cached value. Malformed traceparents never downgrade a cache-hit to a cache-miss.

Example dashboard queries (PromQL-style)

# Per-host operation rate
rate(windows_service_operations_total{}[5m])

# Per-operation p99 latency (ms)
histogram_quantile(0.99, rate(windows_service_operation_duration_bucket{}[5m]))

# Cache hit ratio
rate(windows_service_cache_hits_total{}[5m]) / (rate(windows_service_cache_hits_total{}[5m]) + rate(windows_service_cache_misses_total{}[5m]))

# Error rate by exception type
rate(windows_service_errors_total{}[5m])

# All failed operations
rate(windows_service_operations_total{windows_service_success="false"}[5m])

See the Davasorus.Utility.DotNet.Telemetry documentation for the full semantic conventions catalog.

Error Handling

All errors are logged via ILogger and reported to SQS. Service methods return null, false, or the exception message as appropriate, and log details for diagnostics. All operations are instrumented with OpenTelemetry ActivitySource spans for distributed tracing.

Requirements

• .NET 8.0 or .NET 10.0

License

MIT License