Sitewerk.Exceptions 8.0.0

Sitewerk.Exceptions

Sitewerk.Exceptions provides a simple, consistent way to create and handle domain-specific exceptions across Sitewerk .NET services. It standardizes:

• A clear exception taxonomy (InvalidData, Forbidden, Conflict, etc.) via dedicated exception types
• A builder pattern to compose exceptions with details, fault duration, and inner exceptions
• Lightweight metadata to aid diagnostics (fault duration, sensitive data flag, details)

This repository contains a single NuGet package built from Sitewerk.Exceptions/.

NuGet package

• Package ID: Sitewerk.Exceptions
• Version: 8.0.0
• Target framework: net8.0
• Authors: Sitewerk AG

Install

Use any of the following:

# In a project directory
dotnet add package Sitewerk.Exceptions --version 8.0.0

# Or in a Package Manager Console (Visual Studio)
Install-Package Sitewerk.Exceptions -Version 8.0.0

Quick start

Throw a standardized exception using the builder API:

using Sitewerk.Exceptions;

// Example: invalid data that is permanent and should not be retried
throw new ExceptionBuilder()
    .IsPermanent()
    .HasInvalidData()
    .AddDetail("CustomerService", "Email address format is invalid.")
    .AddDetail("CustomerService", "Allowed domains: example.com, example.org.")
    .Build();

Catch and handle by specific type or by the common base type:

try
{
    ProcessCustomer(customer);
}
catch (InvalidDataException ex)
{
    // Specific handling for invalid data
    LogValidationIssues(ex.Details);
}
catch (SitewerkException ex)
{
    // Generic handling for Sitewerk exceptions
    if (ex.FaultDuration == FaultDuration.Transient)
    {
        // Consider retrying
    }

    if (ex.HasInnerException)
    {
        // Inspect ex.InnerException
    }
}

Exception model

Core primitives:

• SitewerkException (base class)

  • FaultDuration FaultDuration — Unknown | Transient | Permanent
  • IReadOnlyList<ExceptionDetail> Details — optional key-value like details (Source, Message)
  • Exception? InnerException — optional inner exception
  • bool HasSensitiveData — indicates details may contain sensitive info (hide in client responses)

• ExceptionBuilder — fluent API to construct the correct exception type based on an ErrorReason and FaultDuration.

• ErrorReason — classification used by the builder: NotDefined, Unknown, Forbidden, Unauthenticated, InvalidDataStructure, InvalidData, MissingData, Conflict, UnreachableSystem, UnsupportedAcceptFormat, UnsupportedContentType, VirusDetected.

• ExceptionDetail — a record with Source and Message for diagnostics.

• FaultDuration — Unknown | Transient | Permanent (guides retry strategies).

Concrete exception types provided (all derive from SitewerkException):

• DataConflictException
• ForbiddenException
• InvalidDataException
• InvalidDataStructureException
• MissingDataException
• UnknownException
• UnreachableSystemException
• UnsupportedAcceptFormatException
• UnsupportedContentTypeException
• VirusDetectedException

Builder reference

Common builder methods:

• Duration: .IsTransient(), .IsPermanent()
• Reasons: .HasInvalidData(), .HasInvalidDataStructure(), .HasMissingData(), .HasDataConflict(), .HasInvalidAccessRight() (Forbidden), .CannotCommunicateWithOtherSystem() (Unreachable), .HasUnsupportedAcceptFormat(), .HasUnsupportedContentType(), .HasVirusDetected()
• Details: .AddDetail(source, message), .AddDetail(ExceptionDetail), .AddDetails(collection)
• Inner: .AddException(Exception)
• Sensitivity: .HasSensitiveExceptionData()
• Finalize: .Build() → returns the correct concrete SitewerkException

Usage patterns and guidance

• Prefer throwing specific types via the builder so consumers can catch by type.
• Set FaultDuration to guide retry logic (e.g., transient network hiccups vs. permanent validation failures).
• Use ExceptionDetail to aggregate multiple validation or diagnostic messages. Keep Source meaningful (e.g., component or field name).
• If details may contain secrets or PII, call .HasSensitiveExceptionData() and ensure downstream layers omit those details from client-facing responses.

Build and pack locally (optional)

You can build and pack the NuGet locally:

# Build the solution
dotnet build c:\Repo\framework-sw-projects\exceptions\Sitewerk.Exceptions.sln -c Release

# Pack the project to produce the .nupkg (bin/Release)
dotnet pack c:\Repo\framework-sw-projects\exceptions\Sitewerk.Exceptions\Sitewerk.Exceptions.csproj -c Release

The package icon is embedded from assets/sitewerk-logo.png. License acceptance is not required (PackageRequireLicenseAcceptance=false).

Versioning

The package version is 8.0.0 (aligned with .NET 8). Follow semantic versioning when publishing updates.