Zentient.Abstractions 2.0.0

There is a newer version of this package available.
See the version list below for details.
dotnet add package Zentient.Abstractions --version 2.0.0
                    
NuGet\Install-Package Zentient.Abstractions -Version 2.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="Zentient.Abstractions" Version="2.0.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Zentient.Abstractions" Version="2.0.0" />
                    
Directory.Packages.props
<PackageReference Include="Zentient.Abstractions" />
                    
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 Zentient.Abstractions --version 2.0.0
                    
#r "nuget: Zentient.Abstractions, 2.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 Zentient.Abstractions@2.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=Zentient.Abstractions&version=2.0.0
                    
Install as a Cake Addin
#tool nuget:?package=Zentient.Abstractions&version=2.0.0
                    
Install as a Cake Tool

Zentient.Abstractions

Zentient.Abstractions provides the foundational interfaces and core types for building robust, extensible, and protocol-agnostic applications across the entire Zentient Framework ecosystem. It defines the essential contracts for representing operation outcomes, contextual information, metadata, and common patterns like policies and formatters, promoting a clean, modular, and testable architecture. This library serves as a critical dependency for other Zentient components, including Zentient.Results, ensuring a consistent and unified approach to core concepts.

🚀 Getting Started

Install Zentient.Abstractions into your .NET project using NuGet Package Manager:

dotnet add package Zentient.Abstractions

Zentient.Abstractions supports .NET 6.0, .NET 7.0, .NET 8.0, and .NET 9.0.

✨ Key Concepts & Features

This library introduces several fundamental abstractions:

  • IContext: Represents a runtime execution context, allowing for the propagation of contextual information (e.g., request type, metadata) throughout an operation.

    public interface IContext
    {
        string Type { get; }
        IMetadata? Metadata { get; }
    }
    
  • IEnvelope & IEnvelope<TValue>: Defines a minimal, protocol-agnostic structure for the outcome of any operation. It indicates success or failure, provides a canonical code, optional messages, and metadata. IEnvelope<TValue> extends this for operations that yield a specific value.

    public interface IEnvelope
    {
        bool IsSuccess { get; }
        IEndpointCode? Code { get; }
        IReadOnlyCollection<string>? Messages { get; }
        IMetadata? Metadata { get; }
    }
    
    public interface IEnvelope<out TValue> : IEnvelope
    {
        TValue? Value { get; }
    }
    
  • IEndpointCode: Provides a structured, symbolic way to interpret endpoint outcome semantics. It includes a Name (e.g., "NotFound", "Success"), an optional Numeric representation (e.g., HTTP 404), and a Protocol hint.

    public interface IEndpointCode
    {
        string Name { get; }
        int? Numeric { get; }
        string? Protocol { get; }
    }
    
  • IMetadata: A flexible interface for attaching structured contextual metadata as key-value pairs to various entities (e.g., IContext, IEnvelope). It supports type-safe retrieval of tags.

    public interface IMetadata
    {
        IReadOnlyCollection<string> Keys { get; }
        IReadOnlyCollection<object> Values { get; }
        bool TryGetTag<TValue>(string key, out TValue? value);
        IMetadata WithTag<TValue>(string key, TValue value);
    }
    
  • IPolicy<T>: Defines a contract for applying cross-cutting concerns or retry logic to operations that produce a result of type T.

    public interface IPolicy<T>
    {
        Task<T> Execute(Func<CancellationToken, Task<T>> operation, CancellationToken cancellationToken = default);
    }
    
  • IFormatter<TIn, TOut>: A generic interface for transforming one type of value into another, useful for data serialization, deserialization, or mapping.

    public interface IFormatter<in TIn, TOut>
    {
        Task<TOut> Format(TIn input, CancellationToken cancellationToken = default);
    }
    
  • Unit: A lightweight, singleton value type used to represent the absence of a specific value in generic contexts, similar to void in C# or null but as a concrete, serializable type. It's particularly useful in functional programming patterns where a generic type parameter is required but no meaningful data needs to be conveyed.

    public readonly struct Unit : IEquatable<Unit>, IComparable, IComparable<Unit>
    {
        public static Unit Value { get; } // Singleton instance
        // ... operators and methods for equality, comparison, serialization
    }
    

💡 Why Use Zentient.Abstractions?

  • Protocol Agnostic: Design your core logic independently of specific transport protocols (HTTP, gRPC, Messaging).
  • Structured Outcomes: Standardize how operations report success, failure, and associated information, moving beyond exceptions for expected business flows. This is fundamental to how libraries like Zentient.Results operate.
  • Extensibility: Provides interfaces that can be easily implemented and extended to fit diverse application requirements.
  • Testability: Decoupled interfaces promote easier unit testing of business logic.
  • Consistency: Enforces a consistent approach to common application concerns across your codebase, serving as the common language for all Zentient Framework components.

🤝 Contributing

We welcome contributions! If you're interested in contributing to Zentient.Abstractions, please visit our GitHub Repository and refer to the CONTRIBUTING.md guide.

📄 License

Zentient.Abstractions is licensed under the MIT License. See the LICENSE file for more details.

Product Compatible and additional computed target framework versions.
.NET net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 is compatible.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 is compatible.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 was computed.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.
  • net6.0

    • No dependencies.
  • net7.0

    • No dependencies.
  • net8.0

    • No dependencies.
  • net9.0

    • No dependencies.

NuGet packages (3)

Showing the top 3 NuGet packages that depend on Zentient.Abstractions:

Package Downloads
Zentient.Metadata.Attributes

Attribute-based metadata for Zentient Framework. Implements the Zentient.Metadata Attribute Specification, supporting legacy and cross-package attributes. See README.md, CHANGELOG.md, and docs/Zentient_Metadata_Metadata-Attribute-Specification.md for details.

Zentient.Metadata.Abstractions

Forward-compatible metadata abstractions for Zentient Framework. Provides interfaces and contracts for metadata, builders, scanners, tags, and preset keys. See README.md and CHANGELOG.md for details.

Zentient.Metadata

Core metadata engine for Zentient Framework. See README.md and CHANGELOG.md for details.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
3.0.2 292 8/19/2025
3.0.1 168 8/9/2025
3.0.0 162 8/8/2025
2.0.1 159 7/17/2025
2.0.0 134 7/17/2025
1.0.0 143 7/15/2025