📦 DockMapper Service Documentation
Welcome to the comprehensive documentation for the IrbyImaging.Services.DockMapper class. This guide covers everything from high‑level overviews to detailed method descriptions, UML diagrams, usage examples, and more. Whether you’re integrating this service into your application or simply trying to understand how it works, you’ll find all the information you need below.
📑 Table of Contents
- Overview & Purpose
- Dependencies & Technologies
- Architecture & UML Diagram
- Key Functional Areas
4.1. Create Operations 🆕
4.2. Read Operations 🔍
4.3. Update Operations ✏️
4.4. History Operations 📜
- Data Models & ViewModels
- Helper Methods & Utilities
- Error Handling & Return Types
- Usage Examples & Snippets
- Conclusion
🔍 Overview & Purpose
The DockMapper class acts as a translator between your Domain Model (Dock, AssetHistory) and your UI ViewModels (DockCreateViewModel, DockDetailViewModel, etc.). It centralizes all mapping logic to:
- Provide strongly‑typed, DRY, and consistent transformations.
- Keep Controllers and Business Logic thin, focusing only on orchestration.
- Support Create, Read, Update, and History‑related view models for Dock assets.
🛠️ Dependencies & Technologies
| Dependency |
Purpose |
IrbyImaging.BusinessLogic |
Fetching master data (models, owners) |
IrbyImaging.DomainClasses |
Domain entities (Dock, AssetHistory, enums) |
IrbyImaging.Utility |
Helper methods (select list generation) |
IrbyImaging.Models |
ViewModel definitions |
Newtonsoft.Json |
Serializing / deserializing history snapshots |
System, System.Linq, System.Collections.Generic |
Base types & LINQ |
🏗️ Architecture & UML Diagram
classDiagram
direction LR
class IAssetManager {
<<interface>>
+GetModelsFor(category): IEnumerable<Model>
+GetOwners(): IEnumerable<Owner>
}
class DockMapper {
- IAssetManager _assetManager
+ GenerateDockCreateViewModel(): DockCreateViewModel
+ CreateViewModelToDock(vm: DockCreateViewModel): Dock
+ GenerateDockDetailViewModel(d: Dock): DockDetailViewModel
+ GenerateDockListViewModel(ds: IEnumerable~Dock~, status: AssetStatus): DockListViewModel
+ DockToEditViewModel(d: Dock): DockEditViewModel
+ EditViewModelToDock(vm: DockEditViewModel): Dock
+ GenerateDockHistoryViewModel(h: AssetHistory): HistoryViewModel
+ GenerateDockHistoryListViewModel(hs: IEnumerable~AssetHistory~): HistoryListViewModel
}
IAssetManager --> DockMapper : injects
DockMapper --> DockCreateViewModel
DockMapper --> DockDetailViewModel
DockMapper --> DockListViewModel
DockMapper --> DockEditViewModel
DockMapper --> HistoryViewModel
DockMapper --> HistoryListViewModel
🔑 Key Functional Areas
Create Operations 🆕
| Method |
Input |
Output |
Description |
GenerateDockCreateViewModel() |
— |
DockCreateViewModel |
Pre‑populates Make/Model & Owner dropdowns and sets today’s date. |
CreateViewModelToDock(viewModel) |
DockCreateViewModel viewModel |
Dock |
Generates a new Dock entity (with a new Guid) from the view model. |
Code Sample: Generating a Create VM
// In your Controller or Service
var createVm = _dockMapper.GenerateDockCreateViewModel();
// createVm.ModelList & createVm.OwnerList are ready for the UI
Read Operations 🔍
| Method |
Input |
Output |
Description |
GenerateDockDetailViewModel(dock) |
Dock dock |
DockDetailViewModel |
Maps every property and sets a CSS StatusColor based on status. |
GenerateDockListViewModel(docks, status) |
IEnumerable<Dock>, AssetStatus |
DockListViewModel |
Filters by status (unless All) and returns a list of detail VMs. |
var activeDocks = repository.GetDocks();
var listVm = _dockMapper.GenerateDockListViewModel(activeDocks, AssetStatus.Available);
Update Operations ✏️
| Method |
Input |
Output |
Description |
DockToEditViewModel(dock) |
Dock dock |
DockEditViewModel |
Prepares the existing dock for editing; repopulates dropdowns. |
EditViewModelToDock(viewModel) |
DockEditViewModel viewModel |
Dock |
Applies changes from VM back to a Dock entity. |
History Operations 📜
| Method |
Input |
Output |
Description |
GenerateDockHistoryViewModel(history) |
AssetHistory history |
HistoryViewModel |
Deserializes the snapshot and populates history entry details. |
GenerateDockHistoryListViewModel(histories) |
IEnumerable<AssetHistory> |
HistoryListViewModel |
Aggregates multiple history entries into a list. |
🔖 Data Models & ViewModels
| Category |
Class |
Key Properties |
| Domain |
Dock |
Guid Id, string SerialNumber, AssetStatus Status, DateTimeOffset PurchaseDate, Model Model, Owner Owner, string Notes |
|
AssetHistory |
Guid AssetId, AssetStatus Status, string SerializedProperties, DateTimeOffset Timestamp, … |
| ViewModels |
DockCreateViewModel |
SerialNumber, PurchaseDate, ModelList, OwnerList, Notes |
|
DockDetailViewModel |
Id, SerialNumber, OwnerFullName, MakeAndModel, StatusColor, Notes |
|
DockListViewModel |
IEnumerable<DockDetailViewModel> Docks, AssetStatus Status |
|
DockEditViewModel |
All editable dock fields + dropdown lists |
|
HistoryViewModel |
AssetId, Owner, Status, Timestamp, SomeAsset |
|
HistoryListViewModel |
Guid AssetId, IEnumerable<HistoryViewModel> Histories |
🔧 Helper Methods & Utilities
-
Helpers.GenerateSelectListFor(...) (from IrbyImaging.Utility):
Generates dropdown <select> items for a given collection of models or owners.
-
JsonConvert.DeserializeObject<Dock>(...)
Used to reconstruct a snapshot of a Dock from AssetHistory.SerializedProperties.
⚠️ Error Handling & Return Types
- All mapper methods assume non-null inputs.
- Domain validation must occur before mapping (e.g., checking required fields).
- No exceptions are thrown directly by the mapper—invalid states will bubble up from underlying services (e.g.,
IAssetManager).
- Returns strongly‑typed objects—no ambiguous or dynamic results.
💡 Usage Examples & Snippets
1. Registering in DI Container
services.AddScoped<IAssetManager, AssetManager>();
services.AddScoped<IDockMapper, DockMapper>();
2. Creating a Dock
// Controller
public IActionResult NewDock()
{
var vm = _dockMapper.GenerateDockCreateViewModel();
return View(vm);
}
[HttpPost]
public IActionResult NewDock(DockCreateViewModel vm)
{
if(!ModelState.IsValid) return View(vm);
var dockEntity = _dockMapper.CreateViewModelToDock(vm);
_assetManager.AddDock(dockEntity);
return RedirectToAction("List");
}
3. Editing a Dock
public IActionResult Edit(Guid id)
{
var dock = _assetManager.GetDockById(id);
var vm = _dockMapper.DockToEditViewModel(dock);
return View(vm);
}
[HttpPost]
public IActionResult Edit(DockEditViewModel vm)
{
var updatedDock = _dockMapper.EditViewModelToDock(vm);
_assetManager.UpdateDock(updatedDock);
return RedirectToAction("Detail", new { id = vm.Id });
}
4. Viewing History
public IActionResult History(Guid id)
{
var histories = _assetManager.GetAssetHistory(id);
var vm = _dockMapper.GenerateDockHistoryListViewModel(histories);
return View(vm);
}
🏁 Conclusion
The DockMapper service abstracts away repetitive mapping code, promotes consistency across your controllers, and cleanly separates concerns between UI and Domain layers. By centralizing transformations, you can:
- Accelerate feature development
- Lower bug rates in mapping logic
- Easily adjust view models or domain models in one location
Use this guide to integrate, extend, or troubleshoot the Dock mapping pipeline within the IrbyImaging application. Happy coding! 🚀