🖨️ PrinterMapper Service Documentation

Welcome to the comprehensive documentation for the PrinterMapper service in the IrbyImaging solution. This document will walk you through the purpose, structure, methods, and usage examples of PrinterMapper.cs.


📑 Table of Contents

  1. Overview & Purpose
  2. Dependencies & Technologies
  3. Key Functional Areas
  4. View Models & Domain Models
  5. Helper Methods & Utilities
  6. Error Handling & Return Types
  7. Third‑party Integrations
  8. Sample Code Blocks
  9. Usage Examples
  10. UML Class Diagram
  11. Conclusion

🌟 Overview & Purpose

PrinterMapper implements the IPrinterMapper interface and serves as a mapping layer between:

  • Domain entities (e.g., Printer, AssetHistory)
  • View models (e.g., PrinterCreateViewModel, PrinterDetailViewModel, HistoryViewModel)

It centralizes the conversion logic, ensuring consistency across Create, Read, Update, and History-related operations for printer assets.

Primary goals:

  • Simplify controller code by offloading mapping concerns.
  • Provide strongly‑typed view models for UI rendering.
  • Maintain one source of truth for mapping logic.

⚙️ Dependencies & Technologies

Technology / Library Purpose
.NET Core / .NET 5+ Application framework
IrbyImaging.BusinessLogic Provides IAssetManager for data retrieval
IrbyImaging.DomainClasses Contains domain models: Printer, AssetHistory
IrbyImaging.Models Defines view models used in UI
IrbyImaging.Utility Contains helper methods (e.g., Helpers.GenerateSelectListFor)
Newtonsoft.Json JSON serialization/deserialization
C# / LINQ / Generics Core language features

🔑 Key Functional Areas

  1. Create

    • Generate a blank form model with select lists
    • Map a filled form to a new Printer entity
  2. Read (Detail/List)

    • Map a Printer entity to a detailed view model
    • Build a list view model with filtering by status
  3. Update (Edit)

    • Map an existing Printer entity to an edit form model
    • Map the edited form back to a Printer entity
  4. History

    • Deserialize historical snapshots into view models
    • Aggregate history records into a list view

🗂 View Models & Domain Models

Domain Entities (from IrbyImaging.DomainClasses)

Class Description
Printer Represents a printer asset
AssetHistory Tracks changes to an asset’s state
AssetStatus Enum: Active | Available | LostOrStolen | All
AssetCategory Enum: Printer, Scanner, etc.

View Models (from IrbyImaging.Models)

View Model Used For
PrinterCreateViewModel Create form page
PrinterDetailViewModel Details page
PrinterListViewModel List page
PrinterEditViewModel Edit form page
HistoryViewModel Single history record display
HistoryListViewModel History list for an asset

🛠️ Helper Methods & Utilities

  • Helpers.GenerateSelectListFor(Collection)
    Creates a <select>-friendly list (e.g., IEnumerable<SelectListItem>) for dropdowns.

  • JsonConvert.DeserializeObject
    Used to reconstruct a Printer from serialized JSON in AssetHistory.SerializedProperties.


🚨 Error Handling & Return Types

  • Null Checks
    • In GeneratePrinterDetailViewModel, if OwnerId is null, fallback to "Error".
  • Exception Handling
    • No explicit try/catch; relies on upper layers (controllers/global filters).
  • Return Types
    • All methods return non-null view models or domain objects.
    • List methods return empty lists if no data matches filter.

🔗 Third‑party Integrations

  • Newtonsoft.Json
    Used to serialize/deserialize the SomeAsset property for history records.

💻 Sample Code Blocks

Interface Definition

public interface IPrinterMapper
{
    // Create
    PrinterCreateViewModel GeneratePrinterCreateViewModel();
    Printer CreateViewModelToPrinter(PrinterCreateViewModel viewModel);

    // Read
    PrinterDetailViewModel GeneratePrinterDetailViewModel(Printer printer);
    PrinterListViewModel GeneratePrinterListViewModel(IEnumerable<Printer> printers, AssetStatus status);

    // Update
    PrinterEditViewModel PrinterToEditViewModel(Printer printer);
    Printer EditViewModelToPrinter(PrinterEditViewModel viewModel);

    // History
    HistoryViewModel GeneratePrinterHistoryViewModel(AssetHistory history);
    HistoryListViewModel GeneratePrinterHistoryListViewModel(IEnumerable<AssetHistory> assetHistories);
}

Constructor & Dependency Injection

public class PrinterMapper : IPrinterMapper
{
    private readonly IAssetManager _assetManager;

    public PrinterMapper(IAssetManager assetManager)
    {
        _assetManager = assetManager;
    }
    // ...
}

🚀 Usage Examples

1. Registering in Startup.cs (ASP.NET Core)

public void ConfigureServices(IServiceCollection services)
{
    services.AddScoped<IAssetManager, AssetManager>();
    services.AddScoped<IPrinterMapper, PrinterMapper>();
    // ...
}

2. Injecting into a Controller

public class PrinterController : Controller
{
    private readonly IPrinterMapper _printerMapper;

    public PrinterController(IPrinterMapper printerMapper)
    {
        _printerMapper = printerMapper;
    }

    // Display create form
    public IActionResult Create()
    {
        var vm = _printerMapper.GeneratePrinterCreateViewModel();
        return View(vm);
    }

    // Handle POST
    [HttpPost]
    public IActionResult Create(PrinterCreateViewModel vm)
    {
        if (!ModelState.IsValid) return View(vm);
        var entity = _printerMapper.CreateViewModelToPrinter(vm);
        _assetManager.SavePrinter(entity);
        return RedirectToAction("List");
    }
}

🧩 UML Class Diagram

@startuml
interface IPrinterMapper {
    +GeneratePrinterCreateViewModel()
    +CreateViewModelToPrinter(vm)
    +GeneratePrinterDetailViewModel(printer)
    +GeneratePrinterListViewModel(printers, status)
    +PrinterToEditViewModel(printer)
    +EditViewModelToPrinter(vm)
    +GeneratePrinterHistoryViewModel(history)
    +GeneratePrinterHistoryListViewModel(histories)
}

class PrinterMapper {
    -IAssetManager _assetManager
    +PrinterMapper(assetManager)
    +GeneratePrinterCreateViewModel()
    +CreateViewModelToPrinter(vm)
    +GeneratePrinterDetailViewModel(printer)
    +GeneratePrinterListViewModel(printers, status)
    +PrinterToEditViewModel(printer)
    +EditViewModelToPrinter(vm)
    +GeneratePrinterHistoryViewModel(history)
    +GeneratePrinterHistoryListViewModel(histories)
}

IPrinterMapper <|.. PrinterMapper
PrinterMapper --> IAssetManager : uses
@enduml

🏁 Conclusion

The PrinterMapper service is a centralized mapping hub for printer-related CRUD and history operations. By encapsulating all translation logic between domain entities and UI models, it keeps controllers clean, promotes reuse, and ensures consistent data shapes across the application. Whether you’re adding new fields, adjusting status colors, or extending history tracking, PrinterMapper is the go‑to place for mapping concerns! 🎯


Happy coding! 🚀