π± MobileDeviceMapper.cs Documentation
Table of Contents
- Overview & Purpose
- Dependencies & Technologies
- UML Class Diagram
- Interface:
IMobileDeviceMapper
- Implementation:
MobileDeviceMapper
5.1. Create Operations π οΈ
5.2. Read Operations π
5.3. Update Operations π
5.4. History Operations π
- View Models & Domain Models
- Helper Methods & Utilities
- Error Handling & Return Types
- Third-party Integrations
- Sample Usage
- 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! π