arolariu.Backend.Domain.Invoices.Services.Foundation.InvoiceStorage
arolariu.Backend.Domain.Invoices
arolariu.Backend.Domain.Invoices.Services.Foundation.InvoiceStorage Namespace
Classes
InvoiceStorageFoundationService Class
The Invoice Storage foundation service.
public class InvoiceStorageFoundationService : arolariu.Backend.Domain.Invoices.Services.Foundation.InvoiceStorage.IInvoiceStorageFoundationService
Inheritance System.Object 🡒 InvoiceStorageFoundationService
Implements IInvoiceStorageFoundationService
Constructors
InvoiceStorageFoundationService(IInvoiceNoSqlBroker, ILoggerFactory) Constructor
Constructor.
public InvoiceStorageFoundationService(arolariu.Backend.Domain.Invoices.Brokers.DatabaseBroker.IInvoiceNoSqlBroker invoiceNoSqlBroker, Microsoft.Extensions.Logging.ILoggerFactory loggerFactory);
Parameters
invoiceNoSqlBroker IInvoiceNoSqlBroker
loggerFactory Microsoft.Extensions.Logging.ILoggerFactory
Fields
InvoiceStorageFoundationService.invoiceNoSqlBroker Field
private readonly IInvoiceNoSqlBroker invoiceNoSqlBroker;
Field Value
InvoiceStorageFoundationService.logger Field
private readonly ILogger<IInvoiceStorageFoundationService> logger;
Field Value
Microsoft.Extensions.Logging.ILogger<IInvoiceStorageFoundationService>
Methods
InvoiceStorageFoundationService.Classify(Exception) Method
private System.Exception Classify(System.Exception exception);
Parameters
exception System.Exception
Returns
InvoiceStorageFoundationService.CreateInvoiceObject(Invoice, Nullable<Guid>, CancellationToken) Method
Persists a new Invoice aggregate.
public System.Threading.Tasks.Task CreateInvoiceObject(arolariu.Backend.Domain.Invoices.DDD.AggregatorRoots.Invoices.Invoice invoice, System.Nullable<System.Guid> userIdentifier=null, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));
Parameters
invoice Invoice
Fully formed invoice aggregate to persist.
userIdentifier System.Nullable<System.Guid>
Optional partition / tenant context for the invoice (acts as partition key).
cancellationToken System.Threading.CancellationToken
Optional cancellation token to abort the operation.
Implements CreateInvoiceObject(Invoice, Nullable<Guid>, CancellationToken)
Returns
System.Threading.Tasks.Task
Asynchronous task.
Exceptions
System.ArgumentNullException
If invoice is null.
System.OperationCanceledException
Thrown if the operation is cancelled.
Remarks
Validation: Ensures invoice id is non-empty, required collections initialized, and monetary totals non-negative.
Failure Modes: Throws validation exception on invariant breach; throws dependency / dependency validation exceptions on broker failures or conflicts.
InvoiceStorageFoundationService.DeleteInvoiceObject(Guid, Nullable<Guid>, CancellationToken) Method
Performs a logical or physical delete (implementation-defined) of an invoice.
public System.Threading.Tasks.Task DeleteInvoiceObject(System.Guid identifier, System.Nullable<System.Guid> userIdentifier=null, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));
Parameters
identifier System.Guid
Invoice identifier.
userIdentifier System.Nullable<System.Guid>
Optional partition / tenant context.
cancellationToken System.Threading.CancellationToken
Optional cancellation token to abort the operation.
Implements DeleteInvoiceObject(Guid, Nullable<Guid>, CancellationToken)
Returns
System.Threading.Tasks.Task
Asynchronous task.
Exceptions
System.OperationCanceledException
Thrown if the operation is cancelled.
Remarks
Soft Delete Policy: If soft delete is implemented, method SHOULD mark state and retain for audit; otherwise physically remove.
Idempotency: Multiple invocations with same identifier yield same terminal state (absent or marked deleted).
InvoiceStorageFoundationService.LogAndWrapDependency(Exception) Method
private arolariu.Backend.Domain.Invoices.DDD.AggregatorRoots.Invoices.Exceptions.Outer.Foundation.InvoiceFoundationDependencyException LogAndWrapDependency(System.Exception exception);
Parameters
exception System.Exception
Returns
InvoiceFoundationDependencyException
InvoiceStorageFoundationService.LogAndWrapDependencyValidation(Exception) Method
private arolariu.Backend.Domain.Invoices.DDD.AggregatorRoots.Invoices.Exceptions.Outer.Foundation.InvoiceFoundationDependencyValidationException LogAndWrapDependencyValidation(System.Exception exception);
Parameters
exception System.Exception
Returns
InvoiceFoundationDependencyValidationException
InvoiceStorageFoundationService.LogAndWrapService(Exception) Method
private arolariu.Backend.Domain.Invoices.DDD.AggregatorRoots.Invoices.Exceptions.Outer.Foundation.InvoiceFoundationServiceException LogAndWrapService(System.Exception exception);
Parameters
exception System.Exception
Returns
InvoiceFoundationServiceException
InvoiceStorageFoundationService.LogAndWrapValidation(Exception) Method
private arolariu.Backend.Domain.Invoices.DDD.AggregatorRoots.Invoices.Exceptions.Outer.Foundation.InvoiceFoundationValidationException LogAndWrapValidation(System.Exception exception);
Parameters
exception System.Exception
Returns
InvoiceFoundationValidationException
InvoiceStorageFoundationService.ReadAllInvoiceObjects(Guid, CancellationToken) Method
Enumerates all invoices for a given partition.
public System.Threading.Tasks.Task<System.Collections.Generic.IEnumerable<arolariu.Backend.Domain.Invoices.DDD.AggregatorRoots.Invoices.Invoice>> ReadAllInvoiceObjects(System.Guid userIdentifier, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));
Parameters
userIdentifier System.Guid
Partition / tenant context.
cancellationToken System.Threading.CancellationToken
Optional cancellation token to abort the operation.
Implements ReadAllInvoiceObjects(Guid, CancellationToken)
Returns
System.Threading.Tasks.Task<System.Collections.Generic.IEnumerable<Invoice>>
Enumerable collection (empty if none).
Exceptions
System.OperationCanceledException
Thrown if the operation is cancelled.
Remarks
Pagination: Not yet implemented; large result sets may incur high RU / memory usage (backlog item).
Soft Delete: Implementations SHOULD filter out soft-deleted invoices unless a diagnostic flag is added in future.
InvoiceStorageFoundationService.ReadInvoiceObject(Guid, Nullable<Guid>, CancellationToken) Method
Retrieves a single invoice by its identifier (and optional partition).
public System.Threading.Tasks.Task<arolariu.Backend.Domain.Invoices.DDD.AggregatorRoots.Invoices.Invoice> ReadInvoiceObject(System.Guid identifier, System.Nullable<System.Guid> userIdentifier=null, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));
Parameters
identifier System.Guid
Invoice aggregate identifier.
userIdentifier System.Nullable<System.Guid>
Optional partition / tenant context.
cancellationToken System.Threading.CancellationToken
Optional cancellation token to abort the operation.
Implements ReadInvoiceObject(Guid, Nullable<Guid>, CancellationToken)
Returns
System.Threading.Tasks.Task<Invoice>
Invoice instance or null.
Exceptions
System.OperationCanceledException
Thrown if the operation is cancelled.
Remarks
Return: Returns the invoice or null if not found (depending on implementation; may alternatively throw a not-found validation exception per policy).
Performance: Single point read; SHOULD leverage partition for optimal cost.
InvoiceStorageFoundationService.TryCatchAsync(ReturningInvoiceFunction) Method
private System.Threading.Tasks.Task<arolariu.Backend.Domain.Invoices.DDD.AggregatorRoots.Invoices.Invoice> TryCatchAsync(arolariu.Backend.Domain.Invoices.Services.Foundation.InvoiceStorage.InvoiceStorageFoundationService.ReturningInvoiceFunction returningInvoiceFunction);
Parameters
returningInvoiceFunction ReturningInvoiceFunction()
Returns
System.Threading.Tasks.Task<Invoice>
InvoiceStorageFoundationService.TryCatchAsync(ReturningInvoicesFunction) Method
private System.Threading.Tasks.Task<System.Collections.Generic.IEnumerable<arolariu.Backend.Domain.Invoices.DDD.AggregatorRoots.Invoices.Invoice>> TryCatchAsync(arolariu.Backend.Domain.Invoices.Services.Foundation.InvoiceStorage.InvoiceStorageFoundationService.ReturningInvoicesFunction returningInvoicesFunction);
Parameters
returningInvoicesFunction ReturningInvoicesFunction()
Returns
System.Threading.Tasks.Task<System.Collections.Generic.IEnumerable<Invoice>>
InvoiceStorageFoundationService.TryCatchAsync(ReturningTaskFunction) Method
private System.Threading.Tasks.Task TryCatchAsync(arolariu.Backend.Domain.Invoices.Services.Foundation.InvoiceStorage.InvoiceStorageFoundationService.ReturningTaskFunction returningTaskFunction);
Parameters
returningTaskFunction ReturningTaskFunction()
Returns
InvoiceStorageFoundationService.UpdateInvoiceObject(Invoice, Guid, Nullable<Guid>, CancellationToken) Method
Replaces an existing invoice with updated state.
public System.Threading.Tasks.Task<arolariu.Backend.Domain.Invoices.DDD.AggregatorRoots.Invoices.Invoice> UpdateInvoiceObject(arolariu.Backend.Domain.Invoices.DDD.AggregatorRoots.Invoices.Invoice updatedInvoice, System.Guid invoiceIdentifier, System.Nullable<System.Guid> userIdentifier=null, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));
Parameters
updatedInvoice Invoice
Proposed new aggregate state.
invoiceIdentifier System.Guid
Identity of the invoice being updated (must match updatedInvoice.id if enforced).
userIdentifier System.Nullable<System.Guid>
Optional partition / tenant context.
cancellationToken System.Threading.CancellationToken
Optional cancellation token to abort the operation.
Implements UpdateInvoiceObject(Invoice, Guid, Nullable<Guid>, CancellationToken)
Returns
System.Threading.Tasks.Task<Invoice>
Updated invoice instance.
Exceptions
System.OperationCanceledException
Thrown if the operation is cancelled.
Remarks
Preconditions: Target invoice must exist; invariants on updated aggregate re-validated.
Concurrency: No optimistic concurrency (ETag) yet; future enhancement may add concurrency token handling.
InvoiceStorageFoundationService.ValidateIdentifierIsSet(Nullable<Guid>) Method
private static void ValidateIdentifierIsSet(System.Nullable<System.Guid> identifier);
Parameters
identifier System.Nullable<System.Guid>
InvoiceStorageFoundationService.ValidateInvoiceInformationIsValid(Invoice) Method
private static void ValidateInvoiceInformationIsValid(arolariu.Backend.Domain.Invoices.DDD.AggregatorRoots.Invoices.Invoice invoice);
Parameters
invoice Invoice
Interfaces
IInvoiceStorageFoundationService Interface
Foundation (core) storage contract for persisting and retrieving Invoice aggregates.
public interface IInvoiceStorageFoundationService
Derived
↳ InvoiceStorageFoundationService
Remarks
Layer Role (The Standard): A foundation service encapsulates direct interaction with persistence concerns (through brokers) plus essential domain validations. It MUST NOT coordinate multi-aggregate workflows or invoke other foundation services (that is the orchestration layer's responsibility).
Responsibilities:
- Create, read, update, delete (CRUD) invoice aggregates in the underlying store.
- Enforce basic domain invariants prior to persistence (e.g., non-null identifiers, monetary value ranges, collection initialization).
- Propagate domain / validation failures via strongly typed exceptions (to be wrapped by higher layers).
Exclusions: No cross-invoice batch operations beyond those defined; no external messaging; no enrichment / AI analysis; no business flow branching.
Partitioning: Optional userIdentifier parameter represents a logical partition (e.g., Cosmos DB partition key). When provided it MUST be used
for scoped queries; when null the implementation MAY treat the operation as cross-partition (with potential RU / performance cost) or throw depending on policy.
Thread-Safety: Implementations SHOULD be stateless or utilize thread-safe dependencies (brokers).
Idempotency: Create is NOT idempotent (duplicate invoice ids should be prevented by domain uniqueness); Read/Delete are idempotent relative to state outcome.
Methods
IInvoiceStorageFoundationService.CreateInvoiceObject(Invoice, Nullable<Guid>, CancellationToken) Method
Persists a new Invoice aggregate.
System.Threading.Tasks.Task CreateInvoiceObject(arolariu.Backend.Domain.Invoices.DDD.AggregatorRoots.Invoices.Invoice invoice, System.Nullable<System.Guid> userIdentifier=null, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));
Parameters
invoice Invoice
Fully formed invoice aggregate to persist.
userIdentifier System.Nullable<System.Guid>
Optional partition / tenant context for the invoice (acts as partition key).
cancellationToken System.Threading.CancellationToken
Optional cancellation token to abort the operation.
Returns
System.Threading.Tasks.Task
Asynchronous task.
Exceptions
System.ArgumentNullException
If invoice is null.
System.OperationCanceledException
Thrown if the operation is cancelled.
Remarks
Validation: Ensures invoice id is non-empty, required collections initialized, and monetary totals non-negative.
Failure Modes: Throws validation exception on invariant breach; throws dependency / dependency validation exceptions on broker failures or conflicts.
IInvoiceStorageFoundationService.DeleteInvoiceObject(Guid, Nullable<Guid>, CancellationToken) Method
Performs a logical or physical delete (implementation-defined) of an invoice.
System.Threading.Tasks.Task DeleteInvoiceObject(System.Guid identifier, System.Nullable<System.Guid> userIdentifier=null, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));
Parameters
identifier System.Guid
Invoice identifier.
userIdentifier System.Nullable<System.Guid>
Optional partition / tenant context.
cancellationToken System.Threading.CancellationToken
Optional cancellation token to abort the operation.
Returns
System.Threading.Tasks.Task
Asynchronous task.
Exceptions
System.OperationCanceledException
Thrown if the operation is cancelled.
Remarks
Soft Delete Policy: If soft delete is implemented, method SHOULD mark state and retain for audit; otherwise physically remove.
Idempotency: Multiple invocations with same identifier yield same terminal state (absent or marked deleted).
IInvoiceStorageFoundationService.ReadAllInvoiceObjects(Guid, CancellationToken) Method
Enumerates all invoices for a given partition.
System.Threading.Tasks.Task<System.Collections.Generic.IEnumerable<arolariu.Backend.Domain.Invoices.DDD.AggregatorRoots.Invoices.Invoice>> ReadAllInvoiceObjects(System.Guid userIdentifier, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));
Parameters
userIdentifier System.Guid
Partition / tenant context.
cancellationToken System.Threading.CancellationToken
Optional cancellation token to abort the operation.
Returns
System.Threading.Tasks.Task<System.Collections.Generic.IEnumerable<Invoice>>
Enumerable collection (empty if none).
Exceptions
System.OperationCanceledException
Thrown if the operation is cancelled.
Remarks
Pagination: Not yet implemented; large result sets may incur high RU / memory usage (backlog item).
Soft Delete: Implementations SHOULD filter out soft-deleted invoices unless a diagnostic flag is added in future.
IInvoiceStorageFoundationService.ReadInvoiceObject(Guid, Nullable<Guid>, CancellationToken) Method
Retrieves a single invoice by its identifier (and optional partition).
System.Threading.Tasks.Task<arolariu.Backend.Domain.Invoices.DDD.AggregatorRoots.Invoices.Invoice> ReadInvoiceObject(System.Guid identifier, System.Nullable<System.Guid> userIdentifier=null, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));
Parameters
identifier System.Guid
Invoice aggregate identifier.
userIdentifier System.Nullable<System.Guid>
Optional partition / tenant context.
cancellationToken System.Threading.CancellationToken
Optional cancellation token to abort the operation.
Returns
System.Threading.Tasks.Task<Invoice>
Invoice instance or null.
Exceptions
System.OperationCanceledException
Thrown if the operation is cancelled.
Remarks
Return: Returns the invoice or null if not found (depending on implementation; may alternatively throw a not-found validation exception per policy).
Performance: Single point read; SHOULD leverage partition for optimal cost.
IInvoiceStorageFoundationService.UpdateInvoiceObject(Invoice, Guid, Nullable<Guid>, CancellationToken) Method
Replaces an existing invoice with updated state.
System.Threading.Tasks.Task<arolariu.Backend.Domain.Invoices.DDD.AggregatorRoots.Invoices.Invoice> UpdateInvoiceObject(arolariu.Backend.Domain.Invoices.DDD.AggregatorRoots.Invoices.Invoice updatedInvoice, System.Guid invoiceIdentifier, System.Nullable<System.Guid> userIdentifier=null, System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));
Parameters
updatedInvoice Invoice
Proposed new aggregate state.
invoiceIdentifier System.Guid
Identity of the invoice being updated (must match updatedInvoice.id if enforced).
userIdentifier System.Nullable<System.Guid>
Optional partition / tenant context.
cancellationToken System.Threading.CancellationToken
Optional cancellation token to abort the operation.
Returns
System.Threading.Tasks.Task<Invoice>
Updated invoice instance.
Exceptions
System.OperationCanceledException
Thrown if the operation is cancelled.
Remarks
Preconditions: Target invoice must exist; invariants on updated aggregate re-validated.
Concurrency: No optimistic concurrency (ETag) yet; future enhancement may add concurrency token handling.
Delegates
InvoiceStorageFoundationService.ReturningInvoiceFunction() Delegate
private delegate System.Threading.Tasks.Task<arolariu.Backend.Domain.Invoices.DDD.AggregatorRoots.Invoices.Invoice> InvoiceStorageFoundationService.ReturningInvoiceFunction();
Returns
System.Threading.Tasks.Task<Invoice>
InvoiceStorageFoundationService.ReturningInvoicesFunction() Delegate
private delegate System.Threading.Tasks.Task<System.Collections.Generic.IEnumerable<arolariu.Backend.Domain.Invoices.DDD.AggregatorRoots.Invoices.Invoice>> InvoiceStorageFoundationService.ReturningInvoicesFunction();
Returns
System.Threading.Tasks.Task<System.Collections.Generic.IEnumerable<Invoice>>
InvoiceStorageFoundationService.ReturningTaskFunction() Delegate
private delegate System.Threading.Tasks.Task InvoiceStorageFoundationService.ReturningTaskFunction();