API Reference - Beep Data Management Engine Documentation

Source of truth (2026)

UnitofWork<T>: DataManagementEngineStandard/Editor/UOW/UnitofWork.Core.cs.
MultiDataSourceUnitOfWork: DataManagementEngineStandard/Editor/MultiDataSourceUnitOfWork.cs.
DMEEditor service surfaces: DataManagementEngineStandard/Editor/DM/DMEEditor.cs.
IAssemblyHandler: DataManagementModelsStandard/Tools/IAssemblyHandler.cs.

MultiDataSourceUnitOfWork Class

The MultiDataSourceUnitOfWork class manages multiple related entities across different data sources, providing sophisticated relationship management and navigation capabilities.

Verified Signature Snapshot (Current Code)

public partial class MultiDataSourceUnitOfWork : IDisposable
{
    public event EventHandler<ChildDataChangedEventArgs> ChildDataChanged;

    public MultiDataSourceUnitOfWork(IDMEEditor dmeEditor);

    public Task AddUnitOfWorkAsync<T>(string dataSourceName, string entityName, string primaryKey)
        where T : Entity, new();

    public void AddRelationship(string parentEntityName, string childEntityName,
        string parentKeyField, string childForeignKeyField,
        RelationshipBehavior deleteBehavior = RelationshipBehavior.CascadeDelete,
        bool isRequired = false);

    public ObservableBindingList<T> GetEntities<T>(string entityName) where T : Entity, new();
    public Task<IErrorsInfo> InsertAsync<T>(string entityName, T entity) where T : Entity, new();
    public Task<IErrorsInfo> UpdateAsync<T>(string entityName, T entity) where T : Entity, new();
    public Task<IErrorsInfo> DeleteAsync<T>(string entityName, T entity) where T : Entity, new();
    public Task<IErrorsInfo> CommitAsync();
}

› Constructor

public MultiDataSourceUnitOfWork(IDMEEditor dmeEditor)

Initializes a new instance of the MultiDataSourceUnitOfWork class.

Parameter	Type	Description
dmeEditor	IDMEEditor	The data management editor instance

› Properties

Public API exposes the ChildDataChanged event and method-based operations. Internal state such as unit dictionaries, parent cursor, and relationship maps are private fields in the current implementation.

› Core Methods

Task AddUnitOfWorkAsync<T>(string dataSourceName, string entityName, string primaryKey)

Adds a new UnitOfWork for the specified entity type.

void AddRelationship(string parentEntityName, string childEntityName, string parentKeyField, string childForeignKeyField, RelationshipBehavior deleteBehavior, bool isRequired)

Defines a relationship between two entities.

ObservableBindingList<T> GetEntities<T>(string entityName)

Gets the observable collection of entities for the specified entity type.

Task<Dictionary<string, ObservableBindingList<TChild>>> GetAllRelatedChildrenAsync<TChild, TParent>(string parentEntityName, TParent parentEntity)

Retrieves all related child entities for a given parent entity.

› CRUD Operations

Task<IErrorsInfo> InsertAsync<T>(string entityName, T entity)

Inserts a new entity and handles relationship updates.

Task<IErrorsInfo> UpdateAsync<T>(string entityName, T entity)

Updates an existing entity.

Task<IErrorsInfo> DeleteAsync<T>(string entityName, T entity)

Deletes an entity and handles related entities based on relationship behavior.

Task<IErrorsInfo> CommitAsync()

Commits all changes across all managed UnitOfWork instances.

› Navigation Methods

Task NavigateToParentAsync<T>(string parentEntityName, T parentEntity)

Navigates to a specific parent entity and loads related children.

Task NavigateToNextAsync<T>(string parentEntityName)

Navigates to the next parent entity in the collection.

Task NavigateToPreviousAsync<T>(string parentEntityName)

Navigates to the previous parent entity in the collection.

Task NavigateToFirstAsync<T>(string parentEntityName)

Navigates to the first parent entity in the collection.

Task NavigateToLastAsync<T>(string parentEntityName)

Navigates to the last parent entity in the collection.

UnitofWork<T> Class

The generic UnitofWork<T> class provides a complete implementation of the Unit of Work pattern with change tracking, validation, and transaction management for a specific entity type.

Verified Signature Snapshot (Current Code)

public partial class UnitofWork<T> : IUnitofWork<T>, INotifyPropertyChanged where T : Entity, new()
{
    public UnitofWork();
    public UnitofWork(IDMEEditor dMEEditor, string datasourceName, string entityName);
    public UnitofWork(IDMEEditor dMEEditor, string datasourceName, string entityName, EntityStructure entityStructure);
    public UnitofWork(IDMEEditor dMEEditor, string datasourceName, string entityName, string primarykey);
    public UnitofWork(IDMEEditor dMEEditor, string datasourceName, string entityName, EntityStructure entityStructure, string primarykey);

    public bool IsDirty { get; }
    public ObservableBindingList<T> Units { get; set; }
    public ObservableBindingList<T> FilteredUnits { get; set; }
    public T CurrentItem { get; }
    public string PrimaryKey { get; set; }
    public string SoftDeleteFieldName { get; set; }
    public bool IncludeDeleted { get; set; }
    public ConcurrencyMode ConcurrencyMode { get; set; }
    public CommitOrder CommitOrder { get; set; }
}

› Constructors

public UnitofWork(IDMEEditor dMEEditor, string datasourceName, string entityName, string primarykey)

Creates a UnitOfWork instance connected to a data source.

public UnitofWork(IDMEEditor dMEEditor, string datasourceName, string entityName, EntityStructure entityStructure, string primarykey)

Creates a UnitOfWork instance with a pre-defined entity structure.

public UnitofWork(IDMEEditor dMEEditor, bool isInListMode, ObservableBindingList<T> ts, string primarykey)

Creates a UnitOfWork instance for in-memory operations only.

› Core Properties

Property	Type	Access	Description
Units	ObservableBindingList<T>	get/set	The main collection of entities
FilteredUnits	ObservableBindingList<T>	get/set	Filtered collection when filters are applied
CurrentItem	T	get	Currently selected entity
IsDirty	bool	get	True if there are uncommitted changes
IsInListMode	bool	get/set	True for in-memory operations only
PrimaryKey	string	get/set	Name of the primary key field
EntityName	string	get/set	Name of the entity
DataSource	IDataSource	get/set	Associated data source
IsIdentity	bool	get/set	True if primary key is auto-generated
SoftDeleteFieldName	string	get/set	Field used to apply soft-delete semantics
IncludeDeleted	bool	get/set	Controls inclusion of soft-deleted rows during retrieval
ConcurrencyMode	ConcurrencyMode	get/set	Optimistic-concurrency behavior for updates/deletes
CommitOrder	CommitOrder	get/set	Order for commit stages (for FK-safe persistence)

› Data Retrieval Methods

Task<ObservableBindingList<T>> Get()

Retrieves all entities from the data source.

Task<ObservableBindingList<T>> Get(List<AppFilter> filters)

Retrieves entities with applied filters.

Task<ObservableBindingList<T>> GetQuery(string query)

Executes a custom query and returns results.

T Get(string primaryKeyId)

Gets a single entity by its primary key value.

T Get(int key)

Gets entity at the specified index.

› CRUD Operations

void New()

Creates a new entity and adds it to the collection.

void Add(T entity)

Adds an existing entity to the collection.

Task<IErrorsInfo> InsertAsync(T doc)

Asynchronously inserts an entity to the data source.

Task<IErrorsInfo> UpdateAsync(T doc)

Asynchronously updates an entity in the data source.

Task<IErrorsInfo> DeleteAsync(T doc)

Asynchronously deletes an entity from the data source.

IErrorsInfo Update(T entity)

Updates an entity in the collection.

IErrorsInfo Delete(T entity)

Deletes an entity from the collection.

IErrorsInfo Delete(string id)

Deletes an entity by its primary key.

› Transaction Management

Task<IErrorsInfo> Commit()

Commits all pending changes to the data source.

Task<IErrorsInfo> Commit(IProgress<PassedArgs> progress, CancellationToken token)

Commits with progress reporting and cancellation support.

Task<IErrorsInfo> Rollback()

Rolls back all uncommitted changes.

› Change Tracking

IEnumerable<int> GetAddedEntities()

Gets indexes of entities that have been added.

IEnumerable<int> GetModifiedEntities()

Gets indexes of entities that have been modified.

IEnumerable<T> GetDeletedEntities()

Gets entities that have been deleted.

bool GetIsDirty()

Checks if there are any uncommitted changes.

› Navigation Methods

void MoveFirst()

Moves to the first entity in the collection.

void MoveNext()

Moves to the next entity in the collection.

void MovePrevious()

Moves to the previous entity in the collection.

void MoveLast()

Moves to the last entity in the collection.

void MoveTo(int index)

Moves to the entity at the specified index.

› Events

Event	Type	Description
PreCreate	EventHandler<UnitofWorkParams>	Before creating new entity
PostCreate	EventHandler<UnitofWorkParams>	After creating new entity
PreInsert	EventHandler<UnitofWorkParams>	Before inserting to data source
PostInsert	EventHandler<UnitofWorkParams>	After inserting to data source
PreUpdate	EventHandler<UnitofWorkParams>	Before updating in data source
PostUpdate	EventHandler<UnitofWorkParams>	After updating in data source
PreDelete	EventHandler<UnitofWorkParams>	Before deleting from data source
PostDelete	EventHandler<UnitofWorkParams>	After deleting from data source
PreCommit	EventHandler<UnitofWorkParams>	Before committing changes
PostCommit	EventHandler<UnitofWorkParams>	After committing changes
PostEdit	EventHandler<UnitofWorkParams>	After property changes

› Utility Methods

void UndoLastChange()

Undoes the last change made to the collection.

void UndoDelete()

Undoes the most recent delete operation.

bool SaveLog(string pathandname)

Saves the change log to a JSON file.

void Clear()

Clears all data from the collection.

int Getindex(string id)

Gets the index of an entity by its ID.

int Getindex(T entity)

Gets the index of a specific entity.

UnitOfWorkFactory Class

The UnitOfWorkFactory provides static methods for creating UnitOfWork instances dynamically based on runtime type information.

› Static Methods

object CreateUnitOfWork(Type entityType, IDMEEditor dMEEditor, string datasourceName, string entityName, string primarykey)

Creates a new UnitOfWork instance for the specified entity type.

object CreateUnitOfWork(Type entityType, IDMEEditor dMEEditor, string datasourceName, string entityName, EntityStructure entityStructure, string primarykey)

Creates a new UnitOfWork instance with entity structure.

object GetUnitOfWork(string entityName, string dataSourceName, IDMEEditor DMEEditor)

Gets a UnitOfWork instance for the specified entity name.

UnitOfWorkWrapper Class

The UnitOfWorkWrapper provides a dynamic wrapper around UnitOfWork instances, allowing access to strongly-typed UnitOfWork methods without compile-time type knowledge.

› Constructor

public UnitOfWorkWrapper(object unitOfWork)

Initializes a new wrapper around a UnitOfWork instance.

› Dynamic Properties

The UnitOfWorkWrapper exposes all properties of the wrapped UnitOfWork instance dynamically. Key properties include:

Units: The entity collection
IsDirty: Change tracking status
PrimaryKey: Primary key field name
EntityName: Entity name
DataSource: Associated data source

› Dynamic Methods

The UnitOfWorkWrapper forwards all method calls to the wrapped UnitOfWork instance. All CRUD operations, navigation methods, and utility functions are available through the wrapper.

IAssemblyHandler Interface

The IAssemblyHandler contract provides the runtime surface for assembly loading/scanning, NuGet package acquisition, source management, driver-package tracking, and load statistics.

Signature-Verified Snapshot (Current Code)

public interface IAssemblyHandler : IDisposable
{
    // Properties
    List<string> NamespacestoIgnore { get; set; }
    List<assemblies_rep> Assemblies { get; set; }
    List<Assembly> LoadedAssemblies { get; set; }
    List<Type> LoaderExtensions { get; set; }
    List<AssemblyClassDefinition> LoaderExtensionClasses { get; set; }
    List<ILoaderExtention> LoaderExtensionInstances { get; set; }
    List<AssemblyClassDefinition> DataSourcesClasses { get; set; }
    IConfigEditor ConfigEditor { get; set; }
    IErrorsInfo ErrorObject { get; set; }
    IDMLogger Logger { get; set; }
    IUtil Utilfunction { get; set; }

    // Loading
    Assembly LoadAssembly(string path);
    string LoadAssembly(string path, FolderFileTypes fileTypes);
    IErrorsInfo LoadAllAssembly(IProgress<PassedArgs> progress, CancellationToken token);
    List<Assembly> LoadAssembliesFromFolder(string folderPath, FolderFileTypes folderFileType, bool scanForDataSources = true);

    // NuGet
    Task<List<NuGetSearchResult>> SearchNuGetPackagesAsync(string searchTerm, int skip = 0, int take = 20, bool includePrerelease = false, CancellationToken token = default);
    Task<List<string>> GetNuGetPackageVersionsAsync(string packageId, bool includePrerelease = false, CancellationToken token = default);
    Task<List<Assembly>> LoadNuggetFromNuGetAsync(string packageName, string version = null, IEnumerable<string> sources = null, bool useSingleSharedContext = true, string appInstallPath = null, bool useProcessHost = false);

    // Sources
    List<NuGetSourceConfig> GetNuGetSources();
    void AddNuGetSource(string name, string url, bool isEnabled = true);
    void RemoveNuGetSource(string name);
    List<string> GetActiveSourceUrls();

    // Tracking + statistics
    void TrackDriverPackage(string packageId, string version, string driverClassName, DataSourceType dsType);
    List<DriverPackageMapping> GetAllDriverPackageMappings();
    bool IsDriverFromNuGet(string driverClassName);
    AssemblyLoadStatistics GetLoadStatistics();
}

› Grouped Properties

Group	Members	Purpose
Loading	`Assemblies`, `LoadedAssemblies`, `DataSourcesClasses`	Tracks discovered assemblies and datasource class registrations.
Extensions	`LoaderExtensions`, `LoaderExtensionClasses`, `LoaderExtensionInstances`, `NamespacestoIgnore`	Controls extension scanner discovery and execution scope.
Runtime Dependencies	`ConfigEditor`, `ErrorObject`, `Logger`, `Utilfunction`	Provides config persistence, error transport, logging, and shared utilities.

› Loading Methods

Method	Return	Description
`LoadAssembly(path)`	`Assembly`	Loads one DLL and registers it in handler collections.
`LoadAssembly(path, fileTypes)`	`string`	Loads all DLL files from a folder path for a given folder type.
`LoadAllAssembly(progress, token)`	`IErrorsInfo`	Runs the full builtin, folder, scan, and extension discovery sequence.
`LoadAssembliesFromFolder(...)`	`List<Assembly>`	Folder-focused load with optional datasource scan.

› NuGet Methods

Method	Return	Description
`SearchNuGetPackagesAsync(...)`	`Task<List<NuGetSearchResult>>`	Searches package feeds using current active sources.
`GetNuGetPackageVersionsAsync(...)`	`Task<List<string>>`	Returns available versions for a package ID.
`LoadNuggetFromNuGetAsync(...)`	`Task<List<Assembly>>`	Downloads, loads, and syncs loaded assemblies into handler caches.

› Source Methods

Method	Return	Description
`GetNuGetSources()`	`List<NuGetSourceConfig>`	Gets persisted source definitions and enabled flags.
`AddNuGetSource(...)`	`void`	Adds or updates a source entry.
`RemoveNuGetSource(name)`	`void`	Removes a source by name.
`GetActiveSourceUrls()`	`List<string>`	Returns enabled source URLs used by NuGet operations.

› Tracking and Statistics Methods

Group	Methods	Description
Driver Tracking	`TrackDriverPackage(...)`, `GetAllDriverPackageMappings()`, `IsDriverFromNuGet(...)`	Persists and resolves driver-to-package provenance metadata.
Statistics	`GetLoadStatistics()`	Returns assembly loading and NuGet operation counters/timing snapshots.

Supporting Enums and Classes

› RelationshipBehavior Enum

Value	Description
CascadeDelete	Deletes related child entities when parent is deleted
SetNull	Sets foreign key to null when parent is deleted
Restrict	Prevents deletion if related children exist

› EntityState Enum

Value	Description
Added	Entity is new and not yet persisted
Modified	Entity has been changed
Deleted	Entity is marked for deletion
Unchanged	Entity has no modifications

› ChildDataChangedEventArgs Class

Property	Type	Description
ParentEntityName	string	Name of the parent entity
ChildEntityName	string	Name of the child entity

› UnitofWorkParams Class

Property	Type	Description
Cancel	bool	Set to true to cancel the operation
EventAction	EventAction	The type of event being fired
PropertyName	string	Name of the property that changed
PropertyValue	string	New value of the property

UnitOfWork Deep Dive Best Practices