📘 NetworkEquipmentMapper Documentation


Table of Contents

  1. Overview & Purpose
  2. Dependencies & Technologies
  3. Key Functional Areas
  4. Interface: INetworkEquipmentMapper
  5. Implementation: NetworkEquipmentMapper
  6. View Models & Domain Models
  7. Helper Methods & Utilities
  8. Error Handling & Return Types
  9. UML Class Diagram
  10. Usage Examples
  11. Mermaid Sequence Example
  12. Conclusion

Overview & Purpose

📝 What is NetworkEquipmentMapper?
NetworkEquipmentMapper is a service responsible for mapping between domain entities (NetworkEquipment, AssetHistory) and their respective ViewModels (Create, Detail, List, Edit, History). It encapsulates all the transformation logic needed by your UI/Controllers to render forms, lists, details, and history pages—ensuring separation of concerns and clean architecture.

Primary Goals

  • Centralize mapping logic
  • Provide strongly‐typed ViewModels prepopulated with dropdown lists
  • Convert back-and-forth between ViewModels and Domain Models
  • Apply UI‐specific formatting (e.g., status color CSS classes)

Dependencies & Technologies

Technology / Package Purpose
.NET Core / .NET 5+ Application framework
IrbyImaging.BusinessLogic Provides IAssetManager interface & business logic
IrbyImaging.DomainClasses Domain entities: NetworkEquipment, AssetHistory
IrbyImaging.Utility UI Helpers: generating SelectListItems
IrbyImaging.Models View Models for Create/Detail/Edit/List/History
Newtonsoft.Json JSON serialization/deserialization

Key Functional Areas

The mapper handles four main operations:

  1. Create 🎉
  2. Read 🔍
  3. Update ✏️
  4. History 📜

Each area has two sides:

  • Generate ViewModel (for UI)
  • Map ViewModel → Domain Model (for persistence)

1. Create

Method In Out Purpose
GenerateNetworkEquipmentCreateViewModel() – NetworkEquipmentCreateViewModel Prepares dropdown lists & defaults for “Create” form
CreateViewModelToNetworkEquipment(viewModel) NetworkEquipmentCreateViewModel NetworkEquipment Maps user input into a Domain NetworkEquipment

2. Read (Detail & List)

Method In Out Purpose
GenerateNetworkEquipmentDetailViewModel(netEq) NetworkEquipment NetworkEquipmentDetailViewModel Map single entity → detail ViewModel
GenerateNetworkEquipmentListViewModel(list, status) IEnumerable<NetworkEquipment>, AssetStatus NetworkEquipmentListViewModel Filter & map list for UI

3. Update

Method In Out Purpose
NetworkEquipmentToEditViewModel(netEq) NetworkEquipment NetworkEquipmentEditViewModel Populate “Edit” form ViewModel
EditViewModelToNetworkEquipment(viewModel) NetworkEquipmentEditViewModel NetworkEquipment Map edited fields → Domain model

4. History

Method In Out Purpose
GenerateNetworkEquipmentHistoryViewModel(history) AssetHistory HistoryViewModel Map single history record → UI model
GenerateNetworkEquipmentHistoryListViewModel(histories) IEnumerable<AssetHistory> HistoryListViewModel Aggregate & map history records → list for UI

Interface: INetworkEquipmentMapper

namespace IrbyImaging.Services
{
    public interface INetworkEquipmentMapper
    {
        // CREATE
        NetworkEquipmentCreateViewModel GenerateNetworkEquipmentCreateViewModel();
        NetworkEquipment CreateViewModelToNetworkEquipment(NetworkEquipmentCreateViewModel vm);

        // READ
        NetworkEquipmentDetailViewModel GenerateNetworkEquipmentDetailViewModel(NetworkEquipment net);
        NetworkEquipmentListViewModel GenerateNetworkEquipmentListViewModel(IEnumerable<NetworkEquipment> list, AssetStatus status);

        // UPDATE
        NetworkEquipmentEditViewModel NetworkEquipmentToEditViewModel(NetworkEquipment net);
        NetworkEquipment EditViewModelToNetworkEquipment(NetworkEquipmentEditViewModel vm);

        // HISTORY
        HistoryViewModel GenerateNetworkEquipmentHistoryViewModel(AssetHistory h);
        HistoryListViewModel GenerateNetworkEquipmentHistoryListViewModel(IEnumerable<AssetHistory> hs);
    }
}
  • Segregated by operation (Create, Read, Update, History)
  • Defines contracts for mapping logic

Implementation: NetworkEquipmentMapper

public class NetworkEquipmentMapper : INetworkEquipmentMapper
{
    private readonly IAssetManager _assetManager;

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

    // --- CREATE ---
    public NetworkEquipmentCreateViewModel GenerateNetworkEquipmentCreateViewModel() { … }
    public NetworkEquipment CreateViewModelToNetworkEquipment(NetworkEquipmentCreateViewModel viewModel) { … }

    // --- READ ---
    public NetworkEquipmentDetailViewModel GenerateNetworkEquipmentDetailViewModel(NetworkEquipment networkEquipment) { … }
    public NetworkEquipmentListViewModel GenerateNetworkEquipmentListViewModel(IEnumerable<NetworkEquipment> networkEquipments, AssetStatus status) { … }

    // --- UPDATE ---
    public NetworkEquipmentEditViewModel NetworkEquipmentToEditViewModel(NetworkEquipment networkEquipment) { … }
    public NetworkEquipment EditViewModelToNetworkEquipment(NetworkEquipmentEditViewModel viewModel) { … }

    // --- HISTORY ---
    public HistoryViewModel GenerateNetworkEquipmentHistoryViewModel(AssetHistory history) { … }
    public HistoryListViewModel GenerateNetworkEquipmentHistoryListViewModel(IEnumerable<AssetHistory> assetHistories) { … }
}

Highlights

  • Dependency Injection:
    • IAssetManager is injected to fetch related data (Models, Field Offices)
  • Helpers:
    • Helpers.GenerateSelectListFor(...) builds lists for <select> inputs
  • Status Color Logic:
    switch (networkEquipment.Status)
    {
      case AssetStatus.Active:       colorClass = "irby-green"; break;
      case AssetStatus.Available:    colorClass = "irby-blue";  break;
      case AssetStatus.LostOrStolen: colorClass = "irby-red";   break;
      default:                       colorClass = "";           break;
    }
    
  • JSON Deserialization (History):
    SomeAsset = JsonConvert.DeserializeObject<NetworkEquipment>(history.SerializedProperties)
    

View Models & Domain Models

ViewModel Purpose
NetworkEquipmentCreateViewModel Data for Create form
NetworkEquipmentDetailViewModel Data for Detail view
NetworkEquipmentListViewModel Contains list of detail items + filter status
NetworkEquipmentEditViewModel Data for Edit form
HistoryViewModel Single history record
HistoryListViewModel Aggregates history records for an asset

Domain Models (from IrbyImaging.DomainClasses):

  • NetworkEquipment
  • AssetHistory
  • Enum AssetStatus { Active, Available, LostOrStolen, All }

Helper Methods & Utilities

  • Helpers.GenerateSelectListFor(IEnumerable<T>)
    • Converts an IEnumerable of domain objects into IEnumerable<SelectListItem> for dropdowns.
  • IAssetManager
    • Methods:
      • GetModelsFor(AssetCategory.NetworkEquipment)
      • GetFieldOffices()

Error Handling & Return Types

  • No explicit try/catch: relies on upstream exception handling (e.g., middleware or calling controllers).
  • Return Types:
    • Always returns non-null ViewModels or Domain Models.
    • Filters in list‐generation skip mismatched statuses.

UML Class Diagram

classDiagram
    INetworkEquipmentMapper <|.. NetworkEquipmentMapper

    class INetworkEquipmentMapper {
      +GenerateNetworkEquipmentCreateViewModel() NetworkEquipmentCreateViewModel
      +CreateViewModelToNetworkEquipment(vm) NetworkEquipment
      +GenerateNetworkEquipmentDetailViewModel(net) NetworkEquipmentDetailViewModel
      +GenerateNetworkEquipmentListViewModel(list, status) NetworkEquipmentListViewModel
      +NetworkEquipmentToEditViewModel(net) NetworkEquipmentEditViewModel
      +EditViewModelToNetworkEquipment(vm) NetworkEquipment
      +GenerateNetworkEquipmentHistoryViewModel(h) HistoryViewModel
      +GenerateNetworkEquipmentHistoryListViewModel(hs) HistoryListViewModel
    }

    class NetworkEquipmentMapper {
      -IAssetManager _assetManager
      +NetworkEquipmentMapper(assetManager)
      +GenerateNetworkEquipmentCreateViewModel()
      +CreateViewModelToNetworkEquipment(vm)
      +GenerateNetworkEquipmentDetailViewModel(net)
      +GenerateNetworkEquipmentListViewModel(list, status)
      +NetworkEquipmentToEditViewModel(net)
      +EditViewModelToNetworkEquipment(vm)
      +GenerateNetworkEquipmentHistoryViewModel(h)
      +GenerateNetworkEquipmentHistoryListViewModel(hs)
    }

    IAssetManager <.. NetworkEquipmentMapper

Usage Examples

1. Registering in Dependency Injection

services.AddScoped<INetworkEquipmentMapper, NetworkEquipmentMapper>();
services.AddScoped<IAssetManager, AssetManager>();

2. Controller Example

public class NetworkEquipmentController : Controller
{
    private readonly INetworkEquipmentMapper _mapper;
    private readonly IAssetManager _assetManager;

    public NetworkEquipmentController(
        INetworkEquipmentMapper mapper,
        IAssetManager assetManager)
    {
        _mapper     = mapper;
        _assetManager = assetManager;
    }

    // GET: /NetworkEquipment/Create
    public IActionResult Create()
    {
        var vm = _mapper.GenerateNetworkEquipmentCreateViewModel();
        return View(vm);
    }

    // POST: /NetworkEquipment/Create
    [HttpPost]
    public IActionResult Create(NetworkEquipmentCreateViewModel model)
    {
        if (ModelState.IsValid)
        {
            var entity = _mapper.CreateViewModelToNetworkEquipment(model);
            _assetManager.AddNetworkEquipment(entity);
            return RedirectToAction("List");
        }
        // Redisplay form with errors
        return View(model);
    }

    // GET: /NetworkEquipment/Edit/{id}
    public IActionResult Edit(Guid id)
    {
        var netEq = _assetManager.GetNetworkEquipmentById(id);
        var vm    = _mapper.NetworkEquipmentToEditViewModel(netEq);
        return View(vm);
    }

    [HttpPost]
    public IActionResult Edit(NetworkEquipmentEditViewModel model)
    {
        if (ModelState.IsValid)
        {
            var updated = _mapper.EditViewModelToNetworkEquipment(model);
            _assetManager.UpdateNetworkEquipment(updated);
            return RedirectToAction("Details", new { id = model.Id });
        }
        return View(model);
    }

    // GET: /NetworkEquipment/History/{id}
    public IActionResult History(Guid id)
    {
        var histories = _assetManager.GetAssetHistoryByAssetId(id);
        var vm        = _mapper.GenerateNetworkEquipmentHistoryListViewModel(histories);
        return View(vm);
    }
}

Mermaid Sequence Example

sequenceDiagram
    participant U as User Browser
    participant C as Controller
    participant M as NetworkEquipmentMapper
    participant A as AssetManager

    U->>C: GET /NetworkEquipment/Create
    C->>M: GenerateNetworkEquipmentCreateViewModel()
    M->>A: GetModelsFor(NetworkEquipment)
    M->>A: GetFieldOffices()
    M-->>C: CreateViewModel
    C-->>U: Render Create View

    U->>C: POST form data
    C->>M: CreateViewModelToNetworkEquipment(vm)
    M-->>C: DomainEntity
    C->>A: AddNetworkEquipment(entity)
    C-->>U: Redirect to List

Conclusion

🚀 NetworkEquipmentMapper centralizes and organizes all mapping logic between your domain and view layers for network equipment assets. By following SOLID principles and using Dependency Injection, it makes your codebase:

  • Maintainable: all mappings in one place
  • Testable: easily unit‑test each mapping method
  • Extensible: new ViewModels or mapping rules can be added with minimal impact

With this comprehensive guide, you can confidently integrate, extend, and maintain your network equipment asset workflows in the UI layer! 🎉