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
- Overview & Purpose
- Dependencies & Technologies
- Key Functional Areas
- Interface:
IDeskPhoneMapper - Implementation:
DeskPhoneMapper
5.1. Constructor
5.2. Create Methods
5.3. Read Methods
5.4. Update Methods
5.5. History Methods - View Models & Data Models
- Helper Methods & Utilities
- Error Handling & Return Types
- Third‑party Integrations
- UML Class Diagram
- Sample Usage Examples
- 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:
•ModelListvia_assetManager.GetModelsFor(AssetCategory.DeskPhone)
•OwnerListvia_assetManager.GetOwners()
•PurchaseDate = DateTimeOffset.Now
public DeskPhone CreateViewModelToDeskPhone(DeskPhoneCreateViewModel vm)
- Creates a new
DeskPhoneentity:
•Id = Guid.NewGuid()
• Maps all user‑entered fields (Serial, Status, PhoneNumber, etc.)
5.3. Read Methods 🔍
public DeskPhoneDetailViewModel GenerateDeskPhoneDetailViewModel(DeskPhone d)
- Converts a
DeskPhoneto a Detail VM - Formats phone number:
123-456-7890 - Computes
StatusColorCSS class (irby-green,irby-blue,irby-red)
public DeskPhoneListViewModel GenerateDeskPhoneListViewModel(
IEnumerable<DeskPhone> phones, AssetStatus status)
- Filters by
status(unlessAll) - 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&OwnerListdropdowns
public DeskPhone EditViewModelToDeskPhone(DeskPhoneEditViewModel vm)
- Maps edited values back into a
DeskPhone
5.5. History Methods 📜
public HistoryViewModel GenerateDeskPhoneHistoryViewModel(AssetHistory h)
- Deserializes
h.SerializedPropertiesintoDeskPhone - Builds a
HistoryViewModelcapturing 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>)
CreatesSelectListItemcollections 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 inAssetHistory.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! 🎉