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, System.Threading.CancellationToken cancellationToken);
Parameters
invoice Invoice
Fully formed invoice aggregate to persist.
userIdentifier System.Nullable<System.Guid>
Partition / tenant context for the invoice (acts as partition key); pass null for a cross-partition operation.
cancellationToken System.Threading.CancellationToken
Cancellation token to abort the operation (required).
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, System.Threading.CancellationToken cancellationToken);
Parameters
identifier System.Guid
Invoice identifier.
userIdentifier System.Nullable<System.Guid>
Partition / tenant context; pass null for a cross-partition operation.
cancellationToken System.Threading.CancellationToken
Cancellation token to abort the operation (required).
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);
Parameters
userIdentifier System.Guid
Partition / tenant context.
cancellationToken System.Threading.CancellationToken
Cancellation token to abort the operation (required).
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, System.Threading.CancellationToken cancellationToken);
Parameters
identifier System.Guid
Invoice aggregate identifier.
userIdentifier System.Nullable<System.Guid>
Partition / tenant context; pass null for a cross-partition operation.
cancellationToken System.Threading.CancellationToken
Cancellation token to abort the operation (required).
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, System.Threading.CancellationToken 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>
Partition / tenant context; pass null for a cross-partition operation.
cancellationToken System.Threading.CancellationToken
Cancellation token to abort the operation (required).
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, System.Threading.CancellationToken cancellationToken);
Parameters
invoice Invoice
Fully formed invoice aggregate to persist.
userIdentifier System.Nullable<System.Guid>
Partition / tenant context for the invoice (acts as partition key); pass null for a cross-partition operation.
cancellationToken System.Threading.CancellationToken
Cancellation token to abort the operation (required).
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, System.Threading.CancellationToken cancellationToken);
Parameters
identifier System.Guid
Invoice identifier.
userIdentifier System.Nullable<System.Guid>
Partition / tenant context; pass null for a cross-partition operation.
cancellationToken System.Threading.CancellationToken
Cancellation token to abort the operation (required).
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);
Parameters
userIdentifier System.Guid
Partition / tenant context.
cancellationToken System.Threading.CancellationToken
Cancellation token to abort the operation (required).
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, System.Threading.CancellationToken cancellationToken);
Parameters
identifier System.Guid
Invoice aggregate identifier.
userIdentifier System.Nullable<System.Guid>
Partition / tenant context; pass null for a cross-partition operation.
cancellationToken System.Threading.CancellationToken
Cancellation token to abort the operation (required).
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, System.Threading.CancellationToken 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>
Partition / tenant context; pass null for a cross-partition operation.
cancellationToken System.Threading.CancellationToken
Cancellation token to abort the operation (required).
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();