πŸ“± MobileDeviceMapper.cs Documentation


Table of Contents

  1. Overview & Purpose
  2. Dependencies & Technologies
  3. UML Class Diagram
  4. Interface: IMobileDeviceMapper
  5. Implementation: MobileDeviceMapper
    5.1. Create Operations πŸ› οΈ
    5.2. Read Operations πŸ”
    5.3. Update Operations πŸ“
    5.4. History Operations πŸ“œ
  6. View Models & Domain Models
  7. Helper Methods & Utilities
  8. Error Handling & Return Types
  9. Third-party Integrations
  10. Sample Usage
  11. Conclusion

1. Overview & Purpose

MobileDeviceMapper.cs is part of the IrbyImaging.Services namespace and provides a bi-directional mapping between domain entities (MobileDevice, AssetHistory) and various ViewModels used in the UI layer (MobileDeviceCreateViewModel, MobileDeviceDetailViewModel, etc.).

  • πŸ”„ Create: Prepare a form model and convert it back to a domain object.
  • πŸ” Read: Transform domain objects into rich detail and list view models.
  • πŸ“ Update: Map existing domain objects to edit forms and back.
  • πŸ“œ History: Build history lists by deserializing past states.

This service decouples UI concerns from business logic, ensuring that controllers and views receive exactly the data and formatting they need.


2. Dependencies & Technologies

Category Details
Language C# (.NET)
JSON Serializer Newtonsoft.Json
Domain Layer IrbyImaging.DomainClasses (e.g., MobileDevice, AssetHistory)
Business Logic Layer IrbyImaging.BusinessLogic.IAssetManager
Utility Helpers IrbyImaging.Utility.Helpers
ViewModel Layer IrbyImaging.Models (various *ViewModel classes)

3. UML Class Diagram

classDiagram
    direction LR
    class IMobileDeviceMapper {
        +GenerateMobileDeviceCreateViewModelFor(DeviceType) : MobileDeviceCreateViewModel
        +CreateViewModelToMobileDevice(MobileDeviceCreateViewModel) : MobileDevice
        +GenerateMobileDeviceDetailViewModel(MobileDevice) : MobileDeviceDetailViewModel
        +GenerateMobileDeviceListViewModel(IEnumerable~MobileDevice~, AssetStatus) : MobileDeviceListViewModel
        +MobileDeviceToEditViewModel(MobileDevice) : MobileDeviceEditViewModel
        +EditViewModelToMobileDevice(MobileDeviceEditViewModel) : MobileDevice
        +GenerateMobileDeviceHistoryListViewModel(IEnumerable~AssetHistory~) : HistoryListViewModel
    }

    class MobileDeviceMapper {
        -IAssetManager _assetManager
        +MobileDeviceMapper(IAssetManager)
        +GenerateMobileDeviceCreateViewModelFor(DeviceType)
        +CreateViewModelToMobileDevice(MobileDeviceCreateViewModel)
        +GenerateMobileDeviceDetailViewModel(MobileDevice)
        +GenerateMobileDeviceListViewModel(IEnumerable~MobileDevice~, AssetStatus)
        +MobileDeviceToEditViewModel(MobileDevice)
        +EditViewModelToMobileDevice(MobileDeviceEditViewModel)
        -GenerateMobileDeviceHistoryViewModel(AssetHistory)
        +GenerateMobileDeviceHistoryListViewModel(IEnumerable~AssetHistory~)
    }

    IMobileDeviceMapper <|.. MobileDeviceMapper

4. Interface: IMobileDeviceMapper

public interface IMobileDeviceMapper
{
    // Create
    MobileDeviceCreateViewModel GenerateMobileDeviceCreateViewModelFor(DeviceType deviceType);
    MobileDevice CreateViewModelToMobileDevice(MobileDeviceCreateViewModel viewModel);

    // Read
    MobileDeviceDetailViewModel GenerateMobileDeviceDetailViewModel(MobileDevice mobileDevice);
    MobileDeviceListViewModel GenerateMobileDeviceListViewModel(
        IEnumerable<MobileDevice> mobileDevices, AssetStatus status);

    // Update
    MobileDeviceEditViewModel MobileDeviceToEditViewModel(MobileDevice mobileDevice);
    MobileDevice EditViewModelToMobileDevice(MobileDeviceEditViewModel viewModel);

    // History
    HistoryListViewModel GenerateMobileDeviceHistoryListViewModel(
        IEnumerable<AssetHistory> assetHistories);
}
  • Purpose: Defines contracts for mapping domain models ↔ view models.
  • Separation of Concerns: UI layer depends only on these abstractions, not on domain logic.

5. Implementation: MobileDeviceMapper

public class MobileDeviceMapper : IMobileDeviceMapper
{
    private readonly IAssetManager _assetManager;

    public MobileDeviceMapper(IAssetManager assetManager)
    {
        _assetManager = assetManager;
    }

    // ... methods below ...
}

Create Operations

Method Description
GenerateMobileDeviceCreateViewModelFor(DeviceType type) Builds MobileDeviceCreateViewModel with select lists & defaults.
CreateViewModelToMobileDevice(MobileDeviceCreateViewModel) Converts the create-view-model to a new MobileDevice domain object.
public MobileDeviceCreateViewModel GenerateMobileDeviceCreateViewModelFor(DeviceType deviceType)
{
    return new MobileDeviceCreateViewModel
    {
        ModelList     = Helpers.GenerateSelectListFor(_assetManager.GetModelsFor(deviceType)),
        OwnerList     = Helpers.GenerateSelectListFor(_assetManager.GetOwners()),
        PurchaseDate  = DateTimeOffset.Now,
        Type          = deviceType,
        IsTelogis     = false
    };
}

public MobileDevice CreateViewModelToMobileDevice(MobileDeviceCreateViewModel vm)
{
    return new MobileDevice
    {
        Id           = Guid.NewGuid(),
        SerialNumber = vm.SerialNumber,
        Status       = vm.Status,
        PurchaseDate = vm.PurchaseDate,
        ModelId      = vm.ModelId,
        OwnerId      = vm.OwnerId,
        Carrier      = vm.Carrier,
        Type         = vm.Type,
        PhoneNumber  = vm.PhoneNumber,
        Imei         = vm.Imei,
        Sim          = vm.Sim,
        Notes        = vm.Notes,
        IsTelogis    = vm.IsTelogis,
        NeedsReview  = vm.NeedsReview
    };
}

Read Operations

Method Description
GenerateMobileDeviceDetailViewModel(MobileDevice) Creates rich detail VM (warranty, CSS classes, formatted phone, etc.)
GenerateMobileDeviceListViewModel(IEnumerable<MobileDevice>, status) Builds a list VM, filters by status, counts warranty categories.
public MobileDeviceDetailViewModel GenerateMobileDeviceDetailViewModel(MobileDevice md)
{
    var vm = new MobileDeviceDetailViewModel
    {
        Id               = md.Id,
        SerialNumber     = md.SerialNumber,
        OwnerFullName    = md.Owner?.FullName ?? "Unknown",
        MakeAndModel     = $"{md.Model.Make.Name} {md.Model.Name}",
        PurchaseDate     = md.PurchaseDate,
        EndOfWarranty    = md.PurchaseDate.AddYears(2).AddDays(-1),
        Status           = md.Status,
        Carrier          = md.Carrier,
        PhoneNumber      = FormatPhone(md.PhoneNumber),
        Imei             = md.Imei,
        Sim              = md.Sim,
        Notes            = md.Notes,
        IsTelogis        = md.IsTelogis ? "Telogis" : "",
        NeedsReview      = md.NeedsReview
    };

    // Determine warranty status
    if (DateTimeOffset.Now > vm.EndOfWarranty)
    {
        vm.WarrantyColorClass      = "outOfWarranty";
        vm.IsOutOfWarranty         = true;
    }
    else if (DateTimeOffset.Now > vm.EndOfWarranty.AddMonths(-6))
    {
        vm.WarrantyColorClass         = "approachingEndOfWarranty";
        vm.IsApproachingEndOfWarranty = true;
    }
    else
    {
        vm.WarrantyColorClass = "inWarranty";
    }

    // Map asset status to CSS color
    vm.StatusColor = md.Status switch
    {
        AssetStatus.Active       => "irby-green",
        AssetStatus.Available    => "irby-blue",
        AssetStatus.LostOrStolen => "irby-red",
        _                        => ""
    };

    return vm;
}

public MobileDeviceListViewModel GenerateMobileDeviceListViewModel(
    IEnumerable<MobileDevice> mobileDevices, AssetStatus statusFilter)
{
    var items                     = new List<MobileDeviceDetailViewModel>();
    int countOut = 0, countApproach = 0;

    foreach (var device in mobileDevices.Distinct())
    {
        if (statusFilter != AssetStatus.All && device.Status != statusFilter)
            continue;

        var detailVm = GenerateMobileDeviceDetailViewModel(device);
        if (detailVm.IsOutOfWarranty)        countOut++;
        else if (detailVm.IsApproachingEndOfWarranty) countApproach++;

        items.Add(detailVm);
    }

    return new MobileDeviceListViewModel
    {
        MobileDevices              = items,
        NumberOutOfWarranty        = countOut.ToString(),
        NumberApproachingEndOfWarranty = countApproach.ToString(),
        Status                     = statusFilter
    };
}

Update Operations

Method Description
MobileDeviceToEditViewModel(MobileDevice) Maps a domain object to an edit view model (pre-populate form).
EditViewModelToMobileDevice(MobileDeviceEditViewModel) Converts edited VM back to domain entity for persistence.
public MobileDeviceEditViewModel MobileDeviceToEditViewModel(MobileDevice md)
{
    return new MobileDeviceEditViewModel
    {
        Id         = md.Id,
        SerialNumber = md.SerialNumber,
        Status     = md.Status,
        PurchaseDate= md.PurchaseDate,
        ModelId    = md.ModelId,
        OwnerId    = md.OwnerId ?? Guid.Empty,
        ModelList  = Helpers.GenerateSelectListFor(_assetManager.GetModelsFor(md.Type)),
        OwnerList  = Helpers.GenerateSelectListFor(_assetManager.GetOwners()),
        Carrier    = md.Carrier,
        PhoneNumber= md.PhoneNumber,
        Imei       = md.Imei,
        Sim        = md.Sim,
        Notes      = md.Notes,
        NeedsReview= md.NeedsReview,
        IsTelogis  = md.IsTelogis
    };
}

public MobileDevice EditViewModelToMobileDevice(MobileDeviceEditViewModel vm)
{
    return new MobileDevice
    {
        Id           = vm.Id,
        SerialNumber = vm.SerialNumber,
        Status       = vm.Status,
        PurchaseDate = vm.PurchaseDate,
        ModelId      = vm.ModelId,
        OwnerId      = vm.OwnerId,
        Carrier      = vm.Carrier,
        PhoneNumber  = vm.PhoneNumber,
        Imei         = vm.Imei,
        Sim          = vm.Sim,
        Notes        = vm.Notes,
        NeedsReview  = vm.NeedsReview,
        IsTelogis    = vm.IsTelogis
    };
}

History Operations

Method Description
GenerateMobileDeviceHistoryListViewModel(IEnumerable<AssetHistory>) Builds HistoryListViewModel by deserializing each history entry.
private HistoryViewModel GenerateMobileDeviceHistoryViewModel(AssetHistory history)
{
    return new HistoryViewModel
    {
        AssetId              = history.AssetId,
        Owner                = history.Owner,
        ModifiedBy           = history.ModifiedBy,
        Status               = history.Status,
        Timestamp            = history.Timestamp,
        Reason               = history.Reason,
        SomeAsset            = JsonConvert.DeserializeObject<MobileDevice>(history.SerializedProperties)
    };
}

public HistoryListViewModel GenerateMobileDeviceHistoryListViewModel(IEnumerable<AssetHistory> histories)
{
    var vmList = histories.Select(GenerateMobileDeviceHistoryViewModel).ToList();
    return new HistoryListViewModel
    {
        AssetId   = vmList.FirstOrDefault()?.AssetId ?? Guid.Empty,
        Histories = vmList
    };
}

6. View Models & Domain Models

Layer Class / Enum Purpose
Domain MobileDevice Represents a device in the business domain.
Domain AssetHistory Captures audit/history record.
Domain DeviceType, AssetStatus (enums) Types & statuses for assets.
ViewModels MobileDeviceCreateViewModel Data needed for Create pages.
ViewModels MobileDeviceDetailViewModel Rich details for Read pages.
ViewModels MobileDeviceListViewModel Aggregated list + summary counts.
ViewModels MobileDeviceEditViewModel Data for Update pages.
ViewModels HistoryViewModel, HistoryListViewModel Represent the audit trail/history.

7. Helper Methods & Utilities

  • Helpers.GenerateSelectListFor(...)
    Generates a SelectList for dropdown controls in MVC views.

  • FormatPhone(string) (private to this mapper)
    Formats a raw 10-digit string into XXX-XXX-XXXX.

    private string FormatPhone(string phone) =>
        string.IsNullOrEmpty(phone)
          ? ""
          : $"{phone.Substring(0,3)}-{phone.Substring(3,3)}-{phone.Substring(6)}";
    
  • JSON Deserialization
    Uses JsonConvert.DeserializeObject<MobileDevice> to reconstruct historical snapshots.


8. Error Handling & Return Types

  • Exceptions
    No explicit try/catchβ€”exceptions bubble up to the caller (e.g., controller or global error handler).
  • Null-Safety
    Fallbacks such as md.Owner?.FullName ?? "Unknown" and FirstOrDefault()?.AssetId ?? Guid.Empty.
  • Return Types
    All methods return strongly-typed ViewModels or Domain models to ensure compile-time checking.

9. Third-party Integrations

  • Newtonsoft.Json
    • Version: (as referenced in project)
    • Purpose: Deserialize the SerializedProperties JSON in AssetHistory to reconstruct a MobileDevice.

10. Sample Usage

public class MobileDeviceController : Controller
{
    private readonly IMobileDeviceMapper _mapper;
    private readonly IAssetManager     _assetManager;

    public MobileDeviceController(IMobileDeviceMapper mapper, IAssetManager assetManager)
    {
        _mapper       = mapper;
        _assetManager = assetManager;
    }

    // GET: /MobileDevice/Create
    public IActionResult Create(DeviceType type)
    {
        var vm = _mapper.GenerateMobileDeviceCreateViewModelFor(type);
        return View(vm);
    }

    // POST: /MobileDevice/Create
    [HttpPost]
    public IActionResult Create(MobileDeviceCreateViewModel vm)
    {
        if (!ModelState.IsValid)
            return View(vm);

        var newDevice = _mapper.CreateViewModelToMobileDevice(vm);
        _assetManager.AddOrUpdateMobileDevice(newDevice);
        return RedirectToAction("List", new { status = AssetStatus.Active });
    }

    // GET: /MobileDevice/History/{id}
    public IActionResult History(Guid id)
    {
        var histories = _assetManager.GetAssetHistory(id);
        var vm        = _mapper.GenerateMobileDeviceHistoryListViewModel(histories);
        return View(vm);
    }
}

11. Conclusion

⭐ MobileDeviceMapper.cs provides a clean, reusable, and testable way to convert between domain objects and view models in your IrbyImaging application. By centralizing conversion logic:

  • You avoid repetitive code in controllers.
  • You ensure consistent formatting (phone numbers, date logic, CSS classes).
  • You simplify maintenance when view requirements change.

Embrace this mapper pattern to keep your application layers well-separated and your code DRY! πŸš€