📦 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

  1. Overview & Purpose
  2. Dependencies & Technologies
  3. Architecture & UML Diagram
  4. Key Functional Areas
    4.1. Create Operations 🆕
    4.2. Read Operations 🔍
    4.3. Update Operations ✏️
    4.4. History Operations 📜
  5. Data Models & ViewModels
  6. Helper Methods & Utilities
  7. Error Handling & Return Types
  8. Usage Examples & Snippets
  9. 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! 🚀