Pervaxis.Genesis.Base 3.4.4

Pervaxis.Genesis.Base

Core abstractions and foundational types for the Pervaxis Genesis AWS provider library collection.

👁 NuGet

Overview

Pervaxis.Genesis.Base provides the foundational abstractions, result types, configuration options, and utilities shared across all Genesis AWS provider implementations. This package is a required dependency for all other Genesis provider libraries.

Key Features:

• 🎯 Result Pattern - Consistent success/failure handling with ProviderResult<T>
• ⚙️ Base Configuration - Common options for AWS region, retry policies, timeouts, LocalStack support
• 📄 Template Loading - JSON and YAML template configuration loader
• 🔧 DI Extensions - Dependency injection registration helpers
• 🚨 Exception Hierarchy - Structured exception types for Genesis providers

Installation

Install via the .NET CLI:

dotnet add package Pervaxis.Genesis.Base

Or via Package Manager Console:

Install-Package Pervaxis.Genesis.Base

Or add directly to your .csproj:

<PackageReference Include="Pervaxis.Genesis.Base" Version="1.0.0" />

Quick Start

1. Register Base Services

using Pervaxis.Genesis.Base.Extensions;

var builder = WebApplication.CreateBuilder(args);

// Register Genesis base services
builder.Services.AddGenesisBase();

var app = builder.Build();

2. Use Provider Results

using Pervaxis.Genesis.Base.Results;

public class MyService
{
 public async Task<ProviderResult<string>> GetDataAsync(string id)
 {
 try
 {
 var data = await FetchDataAsync(id);
 return ProviderResult<string>.Success(data);
 }
 catch (Exception ex)
 {
 return ProviderResult<string>.Failure("Failed to fetch data", ex);
 }
 }
}

// Usage
var result = await myService.GetDataAsync("123");

if (result.IsSuccess)
{
 Console.WriteLine($"Data: {result.Data}");
}
else
{
 Console.WriteLine($"Error: {result.Error}");
}

3. Load Templates

using Pervaxis.Genesis.Base.Abstractions;

public class CloudFormationService
{
 private readonly ITemplateConfigurationLoader _loader;

 public CloudFormationService(ITemplateConfigurationLoader loader)
 {
 _loader = loader;
 }

 public async Task<IDictionary<string, object>> LoadTemplateAsync(string path)
 {
 // Supports .json and .yaml/.yml files
 var template = await _loader.LoadFromFileAsync(path);
 
 if (_loader.ValidateTemplate(template))
 {
 return template;
 }
 
 throw new InvalidOperationException("Invalid template");
 }
}

Configuration

Base Options Pattern

All Genesis providers inherit from GenesisOptionsBase, providing consistent configuration:

using Pervaxis.Genesis.Base.Options;

public class MyProviderOptions : GenesisOptionsBase
{
 public string CustomSetting { get; set; } = "default";
}

// appsettings.json
{
 "MyProvider": {
 "Region": "us-west-2",
 "EnableDetailedLogging": true,
 "TimeoutSeconds": 60,
 "MaxRetryAttempts": 5,
 "UseLocalStack": false
 }
}

// Program.cs
builder.Services.Configure<MyProviderOptions>(
 builder.Configuration.GetSection("MyProvider"));

LocalStack Support

For local development with LocalStack:

{
 "MyProvider": {
 "Region": "us-east-1",
 "UseLocalStack": true,
 "LocalStackUrl": "http://localhost:4566"
 }
}

API Reference

ProviderResult<T>

Represents the result of a provider operation with success/failure status and optional data.

Static Methods:

• Success(T data) - Creates a successful result
• Failure(string error) - Creates a failed result with error message
• Failure(string error, Exception exception) - Creates a failed result with exception

Properties:

• bool IsSuccess - True if operation succeeded
• bool IsFailure - True if operation failed
• T? Data - Result data (only on success)
• string? Error - Error message (only on failure)
• Exception? Exception - Exception (only on failure)

Example:

var result = ProviderResult<User>.Success(user);
// or
var result = ProviderResult<User>.Failure("User not found");

ProviderResult

Non-generic version for operations without return data.

Static Methods:

• Success() - Creates a successful result
• Failure(string error) - Creates a failed result
• Failure(string error, Exception exception) - Creates a failed result with exception

Example:

var result = ProviderResult.Success();
// or
var result = ProviderResult.Failure("Operation failed");

GenesisOptionsBase

Base configuration options for all Genesis providers.

Properties:

Methods:

• bool Validate() - Validates the options configuration

Example:

public class CachingOptions : GenesisOptionsBase
{
 public string ConnectionString { get; set; } = string.Empty;
 
 public override bool Validate()
 {
 if (!base.Validate())
 {
 return false;
 }
 
 if (string.IsNullOrWhiteSpace(ConnectionString))
 {
 return false;
 }
 
 return true;
 }
}

ITemplateConfigurationLoader

Defines methods for loading and parsing template configuration files (JSON/YAML).

Methods:

Task<IDictionary<string, object>> LoadFromFileAsync(
 string filePath, 
 CancellationToken cancellationToken = default);

Task<IDictionary<string, object>> LoadFromStringAsync(
 string content, 
 string format, 
 CancellationToken cancellationToken = default);

Task<IDictionary<string, object>> LoadFromResourceAsync(
 string resourceName, 
 CancellationToken cancellationToken = default);

bool ValidateTemplate(IDictionary<string, object> template);

Example:

// From file
var template = await loader.LoadFromFileAsync("template.yaml");

// From string
var jsonContent = File.ReadAllText("template.json");
var template = await loader.LoadFromStringAsync(jsonContent, "json");

// From embedded resource
var template = await loader.LoadFromResourceAsync("MyApp.Templates.stack.yaml");

Supported Formats:

• json - JSON format
• yaml / yml - YAML format

Exceptions

GenesisException

Base exception for all Genesis provider errors.

public class GenesisException : Exception
{
 public string? ProviderName { get; }
 
 public GenesisException(string message);
 public GenesisException(string message, Exception innerException);
 public GenesisException(string providerName, string message);
 public GenesisException(string providerName, string message, Exception innerException);
}

GenesisConfigurationException

Exception thrown when Genesis provider configuration is invalid.

public sealed class GenesisConfigurationException : GenesisException
{
 public GenesisConfigurationException(string message);
 public GenesisConfigurationException(string message, Exception innerException);
 public GenesisConfigurationException(string providerName, string message);
}

Example:

try
{
 await provider.InitializeAsync();
}
catch (GenesisConfigurationException ex)
{
 _logger.LogError(ex, "Configuration error in provider: {Provider}", ex.ProviderName);
}
catch (GenesisException ex)
{
 _logger.LogError(ex, "Provider error: {Provider}", ex.ProviderName);
}

Extension Methods

GenesisServiceCollectionExtensions

public static IServiceCollection AddGenesisBase(this IServiceCollection services)

Registers the following services:

• ITemplateConfigurationLoader → TemplateConfigurationLoader (Singleton)

Example:

services.AddGenesisBase();

Advanced Usage

Custom Provider Implementation

using Pervasis.Genesis.Base.Options;
using Pervasis.Genesis.Base.Results;
using Pervasis.Genesis.Base.Exceptions;
using Microsoft.Extensions.Options;
using Microsoft.Extensions.Logging;

public class MyProviderOptions : GenesisOptionsBase
{
 public string ApiKey { get; set; } = string.Empty;
}

public interface IMyProvider
{
 Task<ProviderResult<string>> ProcessAsync(string input, CancellationToken ct);
}

public class MyProvider : IMyProvider
{
 private readonly MyProviderOptions _options;
 private readonly ILogger<MyProvider> _logger;

 public MyProvider(
 IOptions<MyProviderOptions> options,
 ILogger<MyProvider> logger)
 {
 _options = options.Value;
 _logger = logger;

 if (!_options.Validate())
 {
 throw new GenesisConfigurationException(
 nameof(MyProvider), 
 "Invalid configuration");
 }
 }

 public async Task<ProviderResult<string>> ProcessAsync(
 string input, 
 CancellationToken ct)
 {
 try
 {
 _logger.LogInformation("Processing input: {Input}", input);
 
 // Your implementation here
 var result = await DoWorkAsync(input, ct);
 
 return ProviderResult<string>.Success(result);
 }
 catch (Exception ex)
 {
 _logger.LogError(ex, "Failed to process input");
 return ProviderResult<string>.Failure("Processing failed", ex);
 }
 }
 
 private Task<string> DoWorkAsync(string input, CancellationToken ct)
 {
 // Implementation
 return Task.FromResult($"Processed: {input}");
 }
}

// Registration
services.Configure<MyProviderOptions>(configuration.GetSection("MyProvider"));
services.AddSingleton<IMyProvider, MyProvider>();

Dependencies

• Microsoft.Extensions.DependencyInjection.Abstractions (9.0.0)
• Microsoft.Extensions.Logging.Abstractions (9.0.0)
• Microsoft.Extensions.Options (9.0.0)
• YamlDotNet (16.2.1)

Related Packages

The Genesis provider ecosystem includes:

• Pervaxis.Genesis.Caching - ElastiCache Redis caching
• Pervaxis.Genesis.Messaging - SQS + SNS messaging
• Pervaxis.Genesis.FileStorage - S3 file storage
• Pervaxis.Genesis.Search - OpenSearch
• Pervaxis.Genesis.Notifications - SES email + SNS push notifications
• Pervaxis.Genesis.Workflow - Step Functions workflow orchestration
• Pervaxis.Genesis.AIAssistance - Bedrock AI models
• Pervaxis.Genesis.Reporting - Metabase reporting
• Pervaxis.Genesis.CloudFormation - CloudFormation stack management

Support

For issues, questions, or contributions:

• 📧 Email: support@clarivex.tech
• 🌐 Website: https://clarivex.tech/pervaxis
• 📚 Documentation: https://docs.clarivex.tech/genesis

License

Copyright © 2026 Clarivex Technologies Private Limited. All rights reserved.

This software is proprietary and confidential. Unauthorized copying, distribution, or use is strictly prohibited.