π± MobileDevicesController.md
Welcome to the comprehensive documentation for the MobileDevicesController in the IrbyImaging solution. This controller manages CRUD operations, listing, filtering, and history tracking of mobile devices in the system.
π Table of Contents
- Overview & Purpose
- Dependencies & Technologies
- Architecture & Key Components
- API Endpoints Overview
- Helper Methods & Utilities
- Error Handling & Return Types
- Models & ViewModels
- Usage Examples
- UML Class Diagram
- Conclusion
1. Overview & Purpose
The MobileDevicesController is an ASP.NET Core MVC controller that:
- π Lists all mobile devices (
Index,Telogis). - π Filters by search terms and asset status (persisted in session).
- π Creates new mobile devices (GET/POST).
- ποΈ Edits existing devices (GET/POST).
- π Displays history of changes for a given device.
- π Intended for internal use by Mobile Admin or Admin roles (via
BaseController).
This controller orchestrates calls between:
- Business Logic (
IAssetManager) - Mapping Layer (
IMobileDeviceMapper) - Data Context (
IrbyContext) - Session & Configuration (
IConfiguration,HttpContext.Session)
2. Dependencies & Technologies
| Category | Library / Technology | Purpose |
|---|---|---|
| Framework | ASP.NET Core MVC | Web application framework |
| Dependency Injection | Microsoft.Extensions | DI container for controllers & services |
| Data Access | Entity Framework Core | ORM via IrbyContext |
| Business Logic | IAssetManager |
Asset retrieval, creation, updates & history |
| Mapping | IMobileDeviceMapper |
Converts Domain β ViewModels |
| Configuration | IConfiguration |
App settings, connection strings, app policies |
| Utilities | System.Text |
Session key encoding/decoding |
| Authorization | Microsoft.AspNetCore.Authorization |
Restricts endpoints to admins (commented) |
3. Architecture & Key Components
BaseController
βββ MobileDevicesController
βββ IAssetManager (_manager)
βββ IMobileDeviceMapper (_mapper)
βββ IrbyContext (_context)
βββ IConfiguration (_configuration)
- BaseController
Contains common functionality (session, user context, error handling). IAssetManager- Retrieves and manages assets (mobile devices & Telogis devices).
- Methods:
GetMobileDevices_Async,GetMobileDeviceById_Async,AddNewAssetWithHistory_Async, etc.
IMobileDeviceMapper- Maps domain
MobileDeviceto/from various ViewModels (List, Detail, Create, Edit, History).
- Maps domain
IrbyContext- EF Core DbContext for database operations.
IConfiguration- Provides access to configuration values (e.g., session keys, policies).
4. API Endpoints Overview
| Method Signature | HTTP Verb | Route | Description |
|---|---|---|---|
| Index(string search, AssetStatus? status = null) | GET | /MobileDevices | List all devices, optional search & status filter. |
| Telogis(string search, AssetStatus status) | GET | /MobileDevices/Telogis | List Telogis devices by search & status. |
| Details(Guid? id) | GET | /MobileDevices/Details/{id} | Show details view for a single device. |
| Create(DeviceType deviceType) | GET | /MobileDevices/Create | Render form to create a new device of given type. |
| Create(MobileDeviceCreateViewModel viewModel) | POST | /MobileDevices/Create | Process creation form, validate, save, redirect. |
| Edit(Guid? id) | GET | /MobileDevices/Edit/{id} | Render form to edit an existing device. |
| Edit(Guid id, MobileDeviceEditViewModel viewModel) | POST | /MobileDevices/Edit/{id} | Process edit form, validate, update, redirect. |
| History(Guid? id) | GET | /MobileDevices/History/{id} | Display change history for a device. |
4.1 Index Action
public async Task<IActionResult> Index(string search, AssetStatus? status = null)
- π Parameters
search: free-text filterstatus: optional enum (Active,Retired,All, etc.)
- βοΈ Workflow
- Determine effective status (query string β session β default
All). - Fetch devices via
_manager.GetMobileDevices_Async(search). - Map to
MobileDeviceListViewModel. - Store chosen status in session for persistence.
- Return the
Indexview.
- Determine effective status (query string β session β default
5. Helper Methods & Utilities
| Method | Description |
|---|---|
| GetStatusFromSession() : AssetStatus? | Decode SelectedStatus from session into AssetStatus enum. |
| StoreStatusInSession(AssetStatus status) | Encode AssetStatus as UTF8 bytes & store in session. |
private AssetStatus? GetStatusFromSession()
{
if (HttpContext.Session.TryGetValue(SelectedStatusKey, out var statusBytes))
{
var statusString = Encoding.UTF8.GetString(statusBytes);
if (Enum.TryParse<AssetStatus>(statusString, out AssetStatus tempStatus))
return tempStatus;
}
return null;
}
6. Error Handling & Return Types
- Try/Catch blocks in
Indexto gracefully handle exceptions. - ModelState.IsValid checks in POST actions to re-display form with validation errors π₯.
- Response Tuples
(response, message)from_managercalls for domain-level success/failure. - HTTP 404 (
NotFound()) used whenid == nullor entity not found. - RedirectToAction(nameof(Index)) on successful Create/Edit.
- View("Error") fallback for unhandled exceptions.
7. Models & ViewModels
7.1 Domain Model: MobileDevice
| Property | Type | Description |
|---|---|---|
| Id | Guid | Primary key |
| Name | string | Device name |
| Serial | string | Serial number |
| Status | AssetStatus | Current asset status |
| Type | DeviceType | e.g., Phone, Tablet |
| β¦ | β¦ | Additional metadata |
7.2 ViewModels
| ViewModel | Purpose |
|---|---|
MobileDeviceListViewModel |
Data for Index & Telogis list views |
MobileDeviceDetailViewModel |
Data for single device details view |
MobileDeviceCreateViewModel |
Fields + validation for Create form |
MobileDeviceEditViewModel |
Fields + validation for Edit form |
MobileDeviceHistoryListViewModel |
History entries for device transactions |
8. Usage Examples
8.1 Listing Devices
GET /MobileDevices?search=iPhone&status=Active
- Returns a view listing all active devices whose name or serial contains βiPhoneβ.
8.2 Creating a New Device
// GET: Render form
GET /MobileDevices/Create?deviceType=Phone
// POST: Submit form
POST /MobileDevices/Create
Content-Type: application/x-www-form-urlencoded
Name=John's%20iPhone&Serial=XYZ123&Type=Phone&Status=Active
- On validation success, adds device & history, then redirects to Index.
8.3 Editing a Device
GET /MobileDevices/Edit/3f2e1a7f-2b9d-4c42-a4c0-4d2b4d38e5ad
POST /MobileDevices/Edit/3f2e1a7f-2b9d-4c42-a4c0-4d2b4d38e5ad
Reason=Updated%20status&Status=Retired&β¦
- Validates mismatch
id, ModelState, then calls_manager.UpdateAssetAndHistory_Async.
9. UML Class Diagram
@startuml
class BaseController {
+constructor(IrbyContext, IConfiguration)
+HttpContext : HttpContext
}
class MobileDevicesController {
- _manager : IAssetManager
- _mapper : IMobileDeviceMapper
- _context : IrbyContext
- _configuration : IConfiguration
+ Index(search:String, status:AssetStatus?)
+ Telogis(search:String, status:AssetStatus)
+ Details(id:Guid?)
+ Create(type:DeviceType)
+ Create(viewModel:MobileDeviceCreateViewModel)
+ Edit(id:Guid?)
+ Edit(id:Guid, viewModel:MobileDeviceEditViewModel)
+ History(id:Guid?)
- GetStatusFromSession() : AssetStatus?
- StoreStatusInSession(status:AssetStatus)
}
MobileDevicesController --|> BaseController
MobileDevicesController --> IAssetManager
MobileDevicesController --> IMobileDeviceMapper
MobileDevicesController --> IrbyContext
MobileDevicesController --> IConfiguration
@enduml
Use PlantUML to render the diagram.
10. Conclusion
β
MobileDevicesController provides a cohesive, session-aware interface for managing mobile device assets.
π οΈ It delegates to business and mapping services, focusing purely on HTTP concerns and view orchestration.
π With detailed error-handling, validation, and history-tracking, it ensures both robustness and traceability.
Feel free to extend this controller by:
- Adding AJAX endpoints for dynamic filtering.
- Introducing role-based segmentation for read/write.
- Implementing bulk import/export features for large device inventories.
Happy coding! π