📱 DeskPhonesController Documentation
Table of Contents
- Overview & Purpose
- Dependencies & Technologies
- Key Functional Areas
- API Endpoints Overview
- Routing & Authorization
- View Models & Data Models
- Helper Methods & Utilities
- Error Handling & Return Types
- Third-Party Integrations
- Class Diagram (UML)
- Usage Examples
- Conclusion
Overview & Purpose
DeskPhonesController is an ASP.NET Core MVC controller within the IrbyImaging.UI assembly that manages CRUD (Create, Read, Update, History) operations for Desk Phone assets. It interacts with:
- IAssetManager for business logic and data retrieval/updating.
- IDeskPhoneMapper to translate between domain models and view models.
- IrbyContext for EF Core context (via
BaseController). - IConfiguration for app settings.
🎯 Primary Goals
- Present paginated/searchable lists of desk phones
- Display details for a single desk phone
- Enable authorized users to create new desk phone records
- Allow editing of existing desk phones with audit history
- Show asset history (change log)
Dependencies & Technologies
| Technology | Version / Detail |
|---|---|
| ASP.NET Core MVC | Controllers, Views, Routing |
| Entity Framework Core | IrbyContext |
| Dependency Injection | Built-in DI container |
| Configuration | IConfiguration |
| Custom Business Logic | IAssetManager |
| AutoMapper-style Mapper | IDeskPhoneMapper |
| C# / .NET 6+ (assumed) | Async/await, Task-based programming |
Key Functional Areas
1. Index (List View)
- Purpose: Show a searchable list of desk phones, optionally filtered by asset status.
- Signature:
public async Task<IActionResult> Index(string search, AssetStatus status) - Workflow:
- Calls
_manager.GetDeskPhones_Async(search)to retrieve matching desk phones. - Uses
_mapper.GenerateDeskPhoneListViewModel(...)to produce aDeskPhoneListViewModel. - Returns the
View(viewModel)for rendering.
- Calls
2. Details View
- Purpose: Display all details of a single desk phone.
- Signature:
public async Task<IActionResult> Details(Guid? id) - Workflow:
- Validates
id != null; returnsNotFound()if missing. - Calls
_manager.GetDeskPhoneById_Async(id); returnsNotFound()if not found. - Maps to
DeskPhoneDetailViewModeland returns the view.
- Validates
3. Create Desk Phone
-
GET
public IActionResult Create()- Returns a fresh
DeskPhoneCreateViewModelfor user input.
- Returns a fresh
-
POST
[HttpPost] [ValidateAntiForgeryToken] public async Task<IActionResult> Create(DeskPhoneCreateViewModel viewModel)- Validates
ModelState. - Converts view model to domain model via
_mapper.CreateViewModelToDeskPhone(viewModel). - Invokes
_manager.AddNewAssetWithHistory_Async(...). - On failure, redisplay form with
ErrorMessage. - On success, redirects to
Index.
- Validates
4. Edit Desk Phone
-
GET
public async Task<IActionResult> Edit(Guid? id)- Loads existing desk phone, maps to
DeskPhoneEditViewModel.
- Loads existing desk phone, maps to
-
POST
[HttpPost] [ValidateAntiForgeryToken] public async Task<IActionResult> Edit(Guid id, DeskPhoneEditViewModel viewModel)- Checks route/data
idmatch. - Validates
ModelState. - Maps back to domain model and calls
_manager.UpdateAssetAndHistory_Async(...). - On failure, repopulates form with error.
- On success, redirects to
Index.
- Checks route/data
5. History View
- Purpose: Show audit/log history for a desk phone.
- Signature:
public async Task<IActionResult> History(Guid? id) - Workflow:
- Validate
id. - Retrieve list of history events (
_manager.GetHistoryByAssetId_Async). - Map to
DeskPhoneHistoryListViewModeland include current detail view. - Return view.
- Validate
API Endpoints Overview
| HTTP Verb | Route | Action | Description |
|---|---|---|---|
| GET | /DeskPhones | Index | List & search desk phones |
| GET | /DeskPhones/Details/{id} | Details | View a specific desk phone |
| GET | /DeskPhones/Create | Create (form) | Show create form |
| POST | /DeskPhones/Create | Create (submit) | Process new desk phone creation |
| GET | /DeskPhones/Edit/{id} | Edit (form) | Show edit form |
| POST | /DeskPhones/Edit/{id} | Edit (submit) | Process desk phone updates |
| GET | /DeskPhones/History/{id} | History | Display change history |
Routing & Authorization
- Base Controller: Inherits from
BaseController, which provides:- Access to
IrbyContext - Common functionality (e.g., user info, config)
- Access to
- [Authorize] Attributes (commented out in code, but expected in production):
- Class-Level:
ReadOnlyOrAdminPolicy - Create/Edit:
AdminPolicy
- Class-Level:
🔒 Apply appropriate policies to ensure data protection.
View Models & Data Models
Domain Model (Simplified)
public class DeskPhone {
public Guid Id { get; set; }
public string Manufacturer { get; set; }
public string Model { get; set; }
public AssetStatus Status { get; set; }
// ...other common asset properties...
}
View Models
| ViewModel | Purpose |
|---|---|
| DeskPhoneListViewModel | Presentation model for the Index page |
| DeskPhoneDetailViewModel | Detailed properties for a single asset |
| DeskPhoneCreateViewModel | Fields + validation for creating asset |
| DeskPhoneEditViewModel | Fields + validation for editing asset |
| DeskPhoneHistoryListViewModel | List of history entries + current detail |
Helper Methods & Utilities
All mapping between domain models and view models is encapsulated in IDeskPhoneMapper.
Business rules & data persistence live in IAssetManager.
Examples
// Creating a new ViewModel for the Create page
var viewModel = _mapper.GenerateDeskPhoneCreateViewModel();
// Mapping back to domain model
var deskPhone = _mapper.EditViewModelToDeskPhone(viewModel);
Error Handling & Return Types
- Null Checks
id == nullor returned entitynull→return NotFound();
- ModelState Validation
- Invalid input returns original
View(viewModel).
- Invalid input returns original
- Business Failures
- Manager returns
(Responses.Failure, message). - Controller displays
ErrorMessageon a fresh view model.
- Manager returns
- Success
- Redirect to
IndexviaRedirectToAction(nameof(Index)).
- Redirect to
Third-Party Integrations
- Entity Framework Core (
IrbyContext) - ASP.NET Core MVC (Views, Controllers, DI, Configuration)
Class Diagram (UML)
classDiagram
class DeskPhonesController {
- IAssetManager _manager
- IDeskPhoneMapper _mapper
- IrbyContext _context
- IConfiguration _configuration
+ Task<IActionResult> Index(string search, AssetStatus status)
+ Task<IActionResult> Details(Guid? id)
+ IActionResult Create()
+ Task<IActionResult> Create(DeskPhoneCreateViewModel vm)
+ Task<IActionResult> Edit(Guid? id)
+ Task<IActionResult> Edit(Guid id, DeskPhoneEditViewModel vm)
+ Task<IActionResult> History(Guid? id)
}
DeskPhonesController --> IAssetManager
DeskPhonesController --> IDeskPhoneMapper
DeskPhonesController --> IrbyContext
DeskPhonesController --> IConfiguration
Usage Examples
🔍 Search & Filter
GET /DeskPhones?search=Cisco&status=Active
📝 Create New Desk Phone (cURL)
curl -X POST https://yourapp/DeskPhones/Create \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "Manufacturer=Yealink&Model=T46S&Status=Available&SerialNumber=12345"
🚧 Edit / Update
GET /DeskPhones/Edit/3f5a9b20-8c3a-4ef7-8b9c-ff1a2bc3d9e0
POST /DeskPhones/Edit/3f5a9b20-8c3a-4ef7-8b9c-ff1a2bc3d9e0
📜 View History
GET /DeskPhones/History/3f5a9b20-8c3a-4ef7-8b9c-ff1a2bc3d9e0
Conclusion
The DeskPhonesController orchestrates all user interactions for desk phone asset management within IrbyImaging.UI. It cleanly separates concerns:
- Controller: HTTP request handling, routing, input validation.
- Manager: Business logic & data operations.
- Mapper: Translation between domain entities and UI models.
🎉 By following this pattern, the controller remains thin and testable, while the IAssetManager and IDeskPhoneMapper can be independently unit-tested and maintained. Enjoy building and extending your desk phone management features!