📚 DocksController Documentation
📑 Table of Contents
- Overview & Purpose
- Dependencies & Technologies
- Key Functional Areas
- API Endpoints Overview
- View Models & Data Models
- Helper Methods & Utilities
- Error Handling & Return Types
- UML & Sequence Diagrams
- Sample Usage & Code Snippets
- Conclusion
🔍 Overview & Purpose
The DocksController is part of the IrbyImaging.UI ASP.NET Core MVC application. It manages CRUD operations and history tracking for Dock assets. This controller:
- Lists docks (
Index) - Displays details (
Details) - Creates new docks (
Create) - Edits existing docks (
Edit) - Shows change history (
History)
It leverages the IAssetManager service for business logic, IDockMapper for view-model translations, and inherits from BaseController for shared context/configuration.
🔗 Dependencies & Technologies
| Layer | Technology / Service |
|---|---|
| Framework | ASP.NET Core MVC (Controllers, Routing, Views) |
| DI / Configuration | Microsoft.Extensions.DependencyInjection |
| Authorization | Microsoft.AspNetCore.Authorization (Policies) |
| Data Access | Entity Framework Core (IrbyContext) |
| Business Logic | IAssetManager |
| Mapping | IDockMapper |
| Utility | Shared Utility classes (Responses enum, etc.) |
// Constructor injection in Startup.cs
services.AddScoped<IAssetManager, AssetManager>();
services.AddScoped<IDockMapper, DockMapper>();
services.AddDbContext<IrbyContext>(options => /* ... */);
🏷️ Key Functional Areas
- Index: Search & list docks
- Details: Show single-dock details
- Create (GET/POST): Form to create a dock
- Edit (GET/POST): Form to update a dock
- History: Show asset history
Each action returns an IActionResult (View or Redirect).
🌐 API Endpoints Overview
Although this is an MVC controller (views, not pure JSON APIs), the routes map as follows:
| HTTP Verb | Route | Action | Purpose |
|---|---|---|---|
| GET | /Docks | Index | List/Search docks |
| GET | /Docks/Details/{id} | Details | View details of a single dock |
| GET | /Docks/Create | Create | Display create-dock form |
| POST | /Docks/Create | Create | Submit new-dock data |
| GET | /Docks/Edit/{id} | Edit | Display edit-dock form |
| POST | /Docks/Edit/{id} | Edit | Submit updated-dock data |
| GET | /Docks/History/{id} | History | Display change history for a dock |
🗂️ View Models & Data Models
| ViewModel | Purpose |
|---|---|
DockListViewModel |
Data for Index view |
DockDetailViewModel |
Data for Details view |
DockCreateViewModel |
Fields for creating a dock |
DockEditViewModel |
Fields for editing a dock |
DockHistoryListViewModel |
History entries & dock summary |
public class DockCreateViewModel
{
public string Name { get; set; }
public string Location { get; set; }
// ... validation attributes
public string ErrorMessage { get; set; }
}
🛠️ Helper Methods & Utilities
-
_manager(IAssetManager):GetDocks_Async(string search)GetDockById_Async(Guid? id)AddNewAssetWithHistory_Async(...)UpdateAssetAndHistory_Async(...)GetHistoryByAssetId_Async(Guid? id)
-
_mapper(IDockMapper):GenerateDockListViewModel(...)GenerateDockDetailViewModel(...)GenerateDockCreateViewModel()CreateViewModelToDock(...)DockToEditViewModel(...)EditViewModelToDock(...)GenerateDockHistoryListViewModel(...)
These abstract away mapping and business logic, keeping the controller slim.
⚠️ Error Handling & Return Types
| Condition | Response |
|---|---|
id == null |
NotFound() |
| Asset not found in DB | NotFound() |
ModelState.IsValid == false |
Return current View with ViewModel |
Manager returns Failure |
Show error message in view |
| Success (Create/Edit) | RedirectToAction(nameof(Index)) |
if (!ModelState.IsValid)
return View(viewModel);
(var response, var message) = await _manager.AddNewAssetWithHistory_Async(...);
if (response == Responses.Failure)
{
viewModel.ErrorMessage = message;
return View(viewModel);
}
📈 UML & Sequence Diagrams
1. Class Diagram (Mermaid)
classDiagram
class DocksController {
-IAssetManager _manager
-IDockMapper _mapper
-IrbyContext _context
-IConfiguration _configuration
+Index(string search, AssetStatus status) : IActionResult
+Details(Guid? id) : IActionResult
+Create() : IActionResult
+Create(DockCreateViewModel vm) : IActionResult
+Edit(Guid? id) : IActionResult
+Edit(Guid id, DockEditViewModel vm) : IActionResult
+History(Guid? id) : IActionResult
}
DocksController --> IAssetManager
DocksController --> IDockMapper
DocksController --> IrbyContext
DocksController --> IConfiguration
DocksController --|> BaseController
2. Sequence Diagram for Create (POST)
sequenceDiagram
participant User
participant Controller as DocksController
participant Mapper as IDockMapper
participant Manager as IAssetManager
participant DB as IrbyContext
User->>Controller: POST /Docks/Create (DockCreateViewModel)
Controller->>Mapper: CreateViewModelToDock(vm)
Mapper-->>Controller: Dock entity
Controller->>Manager: AddNewAssetWithHistory_Async(dock, username)
Manager->>DB: Insert Dock + History
DB-->>Manager: Success
Manager-->>Controller: (Responses.Success, "")
Controller->>User: Redirect to /Docks
💡 Sample Usage & Code Snippets
1. Invoking Index from Razor
<form asp-action="Index" method="get">
<input type="text" name="search" placeholder="Search docks..." />
<select name="status">
<option value="Active">Active</option>
<option value="Inactive">Inactive</option>
</select>
<button type="submit">🔍 Search</button>
</form>
<table>
@foreach(var dock in Model.Docks)
{
<tr>
<td>@dock.Name</td>
<td>@dock.Status</td>
<td>
<a asp-action="Details" asp-route-id="@dock.Id">Details</a>
</td>
</tr>
}
</table>
2. Creating a New Dock (Controller Test)
[Fact]
public async Task Create_Post_ReturnsRedirectOnSuccess()
{
// Arrange
var mockMgr = new Mock<IAssetManager>();
mockMgr.Setup(m => m.AddNewAssetWithHistory_Async(It.IsAny<Dock>(), It.IsAny<string>()))
.ReturnsAsync((Responses.Success, string.Empty));
var controller = new DocksController(mockMgr.Object, mockMapper, dbContext, config);
var vm = new DockCreateViewModel { Name="Dock1", Location="A1" };
// Act
var result = await controller.Create(vm);
// Assert
var redirect = Assert.IsType<RedirectToActionResult>(result);
Assert.Equal("Index", redirect.ActionName);
}
🏁 Conclusion
The DocksController orchestrates all Dock-related user interactions:
- Delegates mapping to
IDockMapper - Delegates business logic to
IAssetManager - Maintains clean MVC patterns with clear error handling
- Enables audit/history tracking
With this documentation, developers should be able to:
- Understand each endpoint & its flow
- Extend or update view models and business logic
- Write unit/integration tests against controller actions
Happy coding! 🚢