DeskPhoneMapper Service 📞

Welcome to the documentation for IrbyImaging/Services/DeskPhoneMapper.cs! This service sits in the middle of your application’s MVC layers, converting between domain entities and view models for Desk Phones. It streamlines Create/Read/Update/History operations, so your controllers only deal with strongly‑typed view models.


📑 Table of Contents

  1. Overview & Purpose
  2. Dependencies & Technologies
  3. Key Functional Areas
  4. Interface: IDeskPhoneMapper
  5. Implementation: DeskPhoneMapper
    5.1. Constructor
    5.2. Create Methods
    5.3. Read Methods
    5.4. Update Methods
    5.5. History Methods
  6. View Models & Data Models
  7. Helper Methods & Utilities
  8. Error Handling & Return Types
  9. Third‑party Integrations
  10. UML Class Diagram
  11. Sample Usage Examples
  12. Conclusion

1. Overview & Purpose 📋

The DeskPhoneMapper service centralizes logic for:

  • Building create form view models
  • Mapping create/edit view models back to domain entities
  • Converting domain entities into detail & list view models
  • Translating history records to view models

By isolating this mapping, controllers stay focused on HTTP concerns, while business logic remains in your services/repositories.


2. Dependencies & Technologies 🛠️

Dependency Purpose
IrbyImaging.BusinessLogic Provides IAssetManager for lookups
IrbyImaging.DomainClasses Contains DeskPhone, AssetHistory, etc.
IrbyImaging.Utility Helpers.GenerateSelectListFor(...)
IrbyImaging.Models All View Model definitions
Newtonsoft.Json JsonConvert.DeserializeObject(...)
.NET Core / .NET Framework C#, DI, MVC, etc.

3. Key Functional Areas 🎯

  • Create
    • GenerateDeskPhoneCreateViewModel
    • CreateViewModelToDeskPhone
  • Read
    • GenerateDeskPhoneDetailViewModel
    • GenerateDeskPhoneListViewModel
  • Update
    • DeskPhoneToEditViewModel
    • EditViewModelToDeskPhone
  • History
    • GenerateDeskPhoneHistoryViewModel
    • GenerateDeskPhoneHistoryListViewModel

4. Interface: IDeskPhoneMapper 📝

public interface IDeskPhoneMapper
{
  // Create
  DeskPhoneCreateViewModel GenerateDeskPhoneCreateViewModel();
  DeskPhone CreateViewModelToDeskPhone(DeskPhoneCreateViewModel vm);

  // Read
  DeskPhoneDetailViewModel GenerateDeskPhoneDetailViewModel(DeskPhone phone);
  DeskPhoneListViewModel GenerateDeskPhoneListViewModel(
      IEnumerable<DeskPhone> phones, AssetStatus status);

  // Update
  DeskPhoneEditViewModel DeskPhoneToEditViewModel(DeskPhone phone);
  DeskPhone EditViewModelToDeskPhone(DeskPhoneEditViewModel vm);

  // History
  HistoryViewModel GenerateDeskPhoneHistoryViewModel(AssetHistory hist);
  HistoryListViewModel GenerateDeskPhoneHistoryListViewModel(
      IEnumerable<AssetHistory> histories);
}

This interface defines all mapping contracts for Desk Phones.


5. Implementation: DeskPhoneMapper 💼

public class DeskPhoneMapper : IDeskPhoneMapper
{
    private readonly IAssetManager _assetManager;
    public DeskPhoneMapper(IAssetManager assetManager) 
      => _assetManager = assetManager;

    // … methods below …
}

5.1. Constructor

  • Injects: IAssetManager
  • Purpose: Fetches models & owners to populate dropdown lists in create/edit forms.

5.2. Create Methods 🔨

public DeskPhoneCreateViewModel GenerateDeskPhoneCreateViewModel()
  • Builds a fresh DeskPhoneCreateViewModel:
    • ModelList via _assetManager.GetModelsFor(AssetCategory.DeskPhone)
    • OwnerList via _assetManager.GetOwners()
    • PurchaseDate = DateTimeOffset.Now
public DeskPhone CreateViewModelToDeskPhone(DeskPhoneCreateViewModel vm)
  • Creates a new DeskPhone entity:
    • Id = Guid.NewGuid()
    • Maps all user‑entered fields (Serial, Status, PhoneNumber, etc.)

5.3. Read Methods 🔍

public DeskPhoneDetailViewModel GenerateDeskPhoneDetailViewModel(DeskPhone d)
  • Converts a DeskPhone to a Detail VM
  • Formats phone number: 123-456-7890
  • Computes StatusColor CSS class (irby-green, irby-blue, irby-red)
public DeskPhoneListViewModel GenerateDeskPhoneListViewModel(
    IEnumerable<DeskPhone> phones, AssetStatus status)
  • Filters by status (unless All)
  • Uses the Detail mapper for each item

5.4. Update Methods ✏️

public DeskPhoneEditViewModel DeskPhoneToEditViewModel(DeskPhone d)
  • Pre‑populates edit form with:
    • Current values (Serial, Status, etc.)
    • ModelList & OwnerList dropdowns
public DeskPhone EditViewModelToDeskPhone(DeskPhoneEditViewModel vm)
  • Maps edited values back into a DeskPhone

5.5. History Methods 📜

public HistoryViewModel GenerateDeskPhoneHistoryViewModel(AssetHistory h)
  • Deserializes h.SerializedProperties into DeskPhone
  • Builds a HistoryViewModel capturing who/when/why
public HistoryListViewModel GenerateDeskPhoneHistoryListViewModel(
    IEnumerable<AssetHistory> histories)
  • Aggregates multiple history entries & exposes the parent AssetId

6. View Models & Data Models 🗂️

Domain Entities

Class Key Properties
DeskPhone Guid Id, string SerialNumber, AssetStatus Status,DateTimeOffset PurchaseDate, string PhoneNumber, string MacAddress
AssetHistory Guid AssetId, Guid? OwnerId, string Owner,AssetStatus Status, string SerializedProperties

ViewModels

ViewModel Role
DeskPhoneCreateViewModel Fields for create form
DeskPhoneDetailViewModel Render details page
DeskPhoneListViewModel Render paged/filtered lists
DeskPhoneEditViewModel Fields for edit form
HistoryViewModel Single history record
HistoryListViewModel Collection of history entries

7. Helper Methods & Utilities 🔧

  • Helpers.GenerateSelectListFor(IEnumerable<T>)
    Creates SelectListItem collections for dropdowns.
  • JsonConvert.DeserializeObject<DeskPhone>
    Restores the serialized JSON snapshot in history records.

8. Error Handling & Return Types ⚠️

  • No explicit exception handling: upstream layers (controllers/services) should handle nulls or JSON errors.
  • All methods return fully‑instantiated objects; null results may surface if dependencies return no data.

9. Third‑party Integrations 🔌

  • Newtonsoft.Json:
    Used to deserialize the JSON snapshot stored in AssetHistory.SerializedProperties.

10. UML Class Diagram 🧩

classDiagram
  IDeskPhoneMapper <|.. DeskPhoneMapper
  DeskPhoneMapper o-- IAssetManager : <<inject>>
  DeskPhoneMapper --> DeskPhoneCreateViewModel
  DeskPhoneMapper --> DeskPhoneDetailViewModel
  DeskPhoneMapper --> DeskPhoneListViewModel
  DeskPhoneMapper --> DeskPhoneEditViewModel
  DeskPhoneMapper --> HistoryViewModel
  DeskPhoneMapper --> HistoryListViewModel

11. Sample Usage Examples 💡

Register in Startup.cs

public void ConfigureServices(IServiceCollection services)
{
    services.AddScoped<IAssetManager, AssetManager>();    // Business logic
    services.AddScoped<IDeskPhoneMapper, DeskPhoneMapper>(); 
    // ...
}

In a Controller

public class DeskPhoneController : Controller
{
    private readonly IDeskPhoneMapper _mapper;
    private readonly IDeskPhoneService _service; // Business logic

    public DeskPhoneController(
        IDeskPhoneMapper mapper, 
        IDeskPhoneService service)
    {
        _mapper  = mapper;
        _service = service;
    }

    // Render the create form
    public IActionResult Create()
    {
        var vm = _mapper.GenerateDeskPhoneCreateViewModel();
        return View(vm);
    }

    // Handle form post
    [HttpPost]
    public IActionResult Create(DeskPhoneCreateViewModel vm)
    {
        if (!ModelState.IsValid) 
            return View(vm);

        var deskPhone = _mapper.CreateViewModelToDeskPhone(vm);
        _service.AddDeskPhone(deskPhone);
        return RedirectToAction("Index");
    }

    // Details page
    public IActionResult Details(Guid id)
    {
        var phone    = _service.GetDeskPhone(id);
        var detailVm = _mapper.GenerateDeskPhoneDetailViewModel(phone);
        return View(detailVm);
    }
}

12. Conclusion 🏁

The DeskPhoneMapper class is your one-stop shop for translating between domain models and UI models for desk‑phone assets. By keeping mapping logic here, you achieve:

  • Consistency in how data is displayed & edited
  • Maintainability with centralized conversion logic
  • Separation of Concerns: Controllers/services stay lean

Enjoy building clean, testable MVC code! 🎉