DCTekSolutions.ExternalCallGuard.Abstractions 1.0.0

ExternalCallGuard.Abstractions

ExternalCallGuard.Abstractions by DC Tek Solutions contains the small, provider-neutral contract layer shared by the ExternalCallGuard package family. Use it when a library needs to describe guarded work, invoke an injected guard, or consume telemetry without taking a dependency on Polly, NLog, or the core resilience implementation.

Free to use in personal and commercial projects. This package is closed-source proprietary software; see LICENSE.md.

Install

dotnet add package DCTekSolutions.ExternalCallGuard.Abstractions --version 1.0.0

Most applications should install DCTekSolutions.ExternalCallGuard, which brings this package in automatically. Install Abstractions directly in reusable integration libraries, shared domain-facing services, and telemetry adapters that should not depend on a specific implementation.

Package family

What is included?

Public API reference

IExternalCallGuard

IExternalCallGuard is the execution boundary used by application and library code. The host application supplies an implementation and decides which retry, timeout, and circuit-breaker behavior each policy key selects.

Both methods use the same parameters:

Use the non-result overload for commands:

var call = new ExternalCallDescriptor("SearchApi", "RefreshIndex");

await externalCallGuard.ExecuteAsync(
    call,
    ct => searchClient.RefreshIndexAsync(ct),
    cancellationToken);

Use the generic overload for queries:

var call = new ExternalCallDescriptor("WeatherApi", "GetForecast");

string forecast = await externalCallGuard.ExecuteAsync(
    call,
    ct => weatherClient.GetForecastAsync(ct),
    cancellationToken);

IExternalCallTelemetrySink

IExternalCallTelemetrySink receives provider-neutral lifecycle events. Implement it to translate those events into metrics, traces, logs, audit records, or test observations.

Its WriteAsync(telemetry, cancellationToken) method has these parameters:

The method returns a ValueTask that completes when the sink has finished processing the event. The custom telemetry sink example shows a complete implementation.

ExternalCallDescriptor

ExternalCallDescriptor gives one kind of external operation a stable identity and selects its host-configured policy. Construct it with:

new ExternalCallDescriptor(dependency, operation, policy, metadata)

Its read-only properties expose the corresponding values:

See Describe calls clearly for a complete construction example and metadata safety guidance.

ExternalCallPolicyKey and ExternalCallPolicyKeys

ExternalCallPolicyKey is a small value object containing a policy name. Construct it with a non-empty value; null, empty, and whitespace values cause ArgumentException. A key selects settings registered by the host—it does not contain those settings.

var readOnly = new ExternalCallPolicyKey("Weather.ReadOnly");
var sameKey = new ExternalCallPolicyKey("Weather.ReadOnly");
var differentCase = new ExternalCallPolicyKey("weather.readonly");

bool namesMatch = readOnly.Equals(sameKey);       // true
bool operatorsMatch = readOnly == sameKey;        // true
bool casingIsSignificant = readOnly != differentCase; // true
string policyName = readOnly.ToString();           // Weather.ReadOnly

var registrations = new Dictionary<ExternalCallPolicyKey, string>
{
    [readOnly] = "registered"
};

Telemetry models

ExternalCallTelemetryEvent is the abstract base class for all lifecycle events. Its constructor values become three read-only properties shared by every event:

Each sealed event adds details for one lifecycle stage:

The guard implementation normally creates these models. Tests, guard implementations, and telemetry adapter tests can construct them directly:

var call = new ExternalCallDescriptor("WeatherApi", "GetForecast");
var now = DateTimeOffset.UtcNow;
var elapsed = TimeSpan.FromMilliseconds(250);
var requestFailure = new HttpRequestException("The dependency was unavailable.");

ExternalCallTelemetryEvent[] examples =
{
    new ExternalCallStartedEvent(call, now),
    new ExternalCallRetryEvent(
        call, now, elapsed, attempt: 1,
        retryDelay: TimeSpan.FromSeconds(1),
        exception: requestFailure),
    new ExternalCallSucceededEvent(call, now, elapsed, attemptCount: 2),
    new ExternalCallFailedEvent(call, now, elapsed, requestFailure, attemptCount: 3),
    new ExternalCallCancelledEvent(
        call, now, elapsed,
        new OperationCanceledException("The caller cancelled the operation."),
        attemptCount: 1),
    new ExternalCallTimedOutEvent(
        call, now, elapsed,
        new TimeoutException("The configured time limit was exceeded."),
        attemptCount: 2)
};

The call and exception parameters cannot be null. Event constructors preserve the supplied timestamp, duration, and attempt values; the component creating telemetry is responsible for supplying values with the documented meanings.

ExternalCallGuardConfigurationException

ExternalCallGuardConfigurationException means that the host's guard setup is invalid or incomplete—for example, a descriptor selected a policy key that was never registered. It is not an external dependency failure.

throw new ExternalCallGuardConfigurationException(
    "No external-call policy is registered with the key 'Weather.ReadOnly'.");

// Preserve a lower-level error when it explains why configuration could not load.
throw new ExternalCallGuardConfigurationException(
    "The external-call timeout is not a valid duration.",
    formatException);

Use the guard from a reusable library

Your library can depend on the interface while the consuming application decides how resilience is implemented:

using DCTekSolutions.ExternalCallGuard.Abstractions.Interfaces;
using DCTekSolutions.ExternalCallGuard.Abstractions.Models;

public sealed class WeatherGateway(
    HttpClient httpClient,
    IExternalCallGuard externalCallGuard)
{
    public Task<string> GetForecastAsync(
        string postalCode,
        CancellationToken cancellationToken = default)
    {
        var call = new ExternalCallDescriptor(
            dependency: "WeatherApi",
            operation: "GetForecast",
            policy: WeatherPolicies.ReadOnly);

        return externalCallGuard.ExecuteAsync(
            call,
            async ct =>
            {
                using var response = await httpClient.GetAsync(
                    $"forecast/{Uri.EscapeDataString(postalCode)}",
                    ct);

                response.EnsureSuccessStatusCode();
                return await response.Content.ReadAsStringAsync();
            },
            cancellationToken);
    }
}

The host application installs DCTekSolutions.ExternalCallGuard, registers it with dependency injection, and defines the ReadOnly policy. Your gateway stays independent of those implementation details.

Define policy keys once

Policy keys are value objects. Keep shared keys in one place so names cannot drift between registration and use:

using DCTekSolutions.ExternalCallGuard.Abstractions.Models;

public static class WeatherPolicies
{
    public static readonly ExternalCallPolicyKey ReadOnly = new("Weather.ReadOnly");
    public static readonly ExternalCallPolicyKey Mutation = new("Weather.Mutation");
}

A policy key only selects configuration. It does not itself contain retry, timeout, or circuit-breaker settings. Those settings belong to the host application's core ExternalCallGuard registration.

Describe calls clearly

var call = new ExternalCallDescriptor(
    dependency: "ShippingApi",
    operation: "GetRate",
    policy: ShippingPolicies.ReadOnly,
    metadata: new Dictionary<string, object?>
    {
        ["carrier"] = "ExampleCarrier",
        ["region"] = "east"
    });

• Dependency identifies the remote system, such as ShippingApi or CustomerDatabase.
• Operation identifies the stable action, such as GetRate or LoadCustomer.
• Policy selects behavior registered by the application. Omitting it selects Default.
• Metadata adds low-cardinality context for telemetry. The descriptor makes its own read-only copy.

Use stable names instead of IDs or URLs. Never include credentials, tokens, connection strings, request/response bodies, personal information, or other secrets.

Build a custom telemetry sink

A sink can translate semantic events into metrics, tracing, audit records, another logger, or a test probe:

using DCTekSolutions.ExternalCallGuard.Abstractions.Interfaces;
using DCTekSolutions.ExternalCallGuard.Abstractions.Models;

public sealed class MetricsTelemetrySink(IMetrics metrics)
    : IExternalCallTelemetrySink
{
    public ValueTask WriteAsync(
        ExternalCallTelemetryEvent telemetry,
        CancellationToken cancellationToken = default)
    {
        var tags = new Dictionary<string, string>
        {
            ["dependency"] = telemetry.Call.Dependency,
            ["operation"] = telemetry.Call.Operation,
            ["policy"] = telemetry.Call.Policy.Value
        };

        switch (telemetry)
        {
            case ExternalCallStartedEvent:
                metrics.Increment("external_call_started", tags);
                break;

            case ExternalCallRetryEvent retry:
                metrics.Increment("external_call_retry", tags);
                metrics.Record("external_call_retry_delay_ms",
                    retry.RetryDelay.TotalMilliseconds,
                    tags);
                break;

            case ExternalCallSucceededEvent:
                metrics.Increment("external_call_success", tags);
                break;

            case ExternalCallFailedEvent:
                metrics.Increment("external_call_failure", tags);
                break;

            case ExternalCallTimedOutEvent:
                metrics.Increment("external_call_timeout", tags);
                break;

            case ExternalCallCancelledEvent:
                metrics.Increment("external_call_cancelled", tags);
                break;
        }

        metrics.Record("external_call_duration_ms",
            telemetry.Duration.TotalMilliseconds,
            tags);

        return ValueTask.CompletedTask;
    }
}

Register it in the host application's dependency injection container:

services.AddSingleton<IExternalCallTelemetrySink, MetricsTelemetrySink>();

Multiple sinks are supported by the core package. They run in registration order, and a broken or slow sink does not replace the result or exception from the business operation.

Test code that depends on the abstraction

A simple fake keeps unit tests independent of resilience timing:

public sealed class PassThroughExternalCallGuard : IExternalCallGuard
{
    public Task ExecuteAsync(
        ExternalCallDescriptor call,
        Func<CancellationToken, Task> operation,
        CancellationToken cancellationToken = default) =>
        operation(cancellationToken);

    public Task<TResult> ExecuteAsync<TResult>(
        ExternalCallDescriptor call,
        Func<CancellationToken, Task<TResult>> operation,
        CancellationToken cancellationToken = default) =>
        operation(cancellationToken);
}

Use the real core implementation in integration tests that need to verify retry, timeout, circuit-breaker, or telemetry behavior.

Compatibility and design guarantees

• Single-targets .NET Standard 2.1 and can be consumed by runtimes that implement that standard. .NET Framework does not implement .NET Standard 2.1.
• Exposes no Polly, Microsoft resilience, NLog, HTTP-client, SQL-client, or application-specific types.
• Contains no retry engine and performs no network or file I/O by itself.
• Supports both operations that return a result and operations that return only Task.
• Uses framework-neutral telemetry models so adapters can live in separate packages.

License

Free for personal and commercial use under the included DC Tek Solutions license. Package license acceptance is required during installation.

Support / Donate

ExternalCallGuard is developed by DC Tek Solutions. For documentation and support, visit the ExternalCallGuard support wiki.

If this package saves you time, please consider supporting continued development:

Thank you for your support!