📄 UserController.cs Documentation
Welcome to the in-depth documentation for UserController.cs from the IrbyImaging.UI assembly. This controller is part of an ASP.NET Core Web API that retrieves detailed user information by combining database records with Azure Active Directory data.
📑 Table of Contents
- Overview & Purpose
- Dependencies & Technologies
- Data Models & ViewModels
- API Endpoints Overview
- Key Functional Areas
- Helper Methods & Utilities
- Error Handling & Return Types
- Third‑party Integrations
- Sample Code Snippets
- Usage Examples
- UML Class Diagram
- Conclusion
1. Overview & Purpose
File: IrbyImaging/Controllers/UserController.cs
Namespace: TicketSystem.Controllers
Author: kvamshi
Created: 05-17-2022
The UserController is responsible for exposing an HTTP GET endpoint that returns an EmployeeDetail view model. It merges data from:
- IrbyContext (Entity Framework Core context for the SQL database)
- Azure Active Directory (Azure AD) via a helper class
AzureADRead
Use Case:
When a client application calls
/api/User/{username}, the controller looks up the user in the company database and supplements or falls back to Azure AD data, returning contact, job, and departmental details.
2. Dependencies & Technologies
| Dependency | Purpose |
|---|---|
Microsoft.AspNetCore.Mvc |
ASP.NET Core MVC / ApiController base classes |
Microsoft.Extensions.Configuration |
Access to configuration (appsettings.json) |
IrbyImaging.DomainClasses |
EF Core entities & IrbyContext |
IrbyImaging.UI.Services |
IActiveDirectoryService & AzureADRead helper |
IrbyImaging.UI.Models.Employee |
EmployeeDetail view model |
Platform: .NET Core / ASP.NET Core Web API
ORM: Entity Framework Core
Directory: Controllers/UserController.cs
3. Data Models & ViewModels
3.1 Domain Models (EF Core)
-
Employee
EmployeeId(int)DisplayName(string)FirstName(string)LastName(string)WorkEmail(string)JobId(int)JdeNumber(string)FullName(string)
-
Job
JobId(int)JdeNumber(string)
3.2 View Models
- EmployeeDetail
public class EmployeeDetail { public string FullName { get; set; } public string EmployeeNumber { get; set; } public string JobNumber { get; set; } public string Title { get; set; } public string Department { get; set; } public string Email { get; set; } public string PhoneNumber { get; set; } }
4. API Endpoints Overview
| HTTP Method | Route | Description | Returns |
|---|---|---|---|
| GET | /api/User/{username} |
Retrieve details for a given username. |
EmployeeDetail |
Route Parameters
username(string): The DisplayName format"LastName, FirstName"of the employee.
5. Key Functional Areas
-
Constructor Injection
_activeDirectory(IActiveDirectoryService): (currently unused in method)_context(IrbyContext): EF Core DB context_configuration(IConfiguration): App settings
-
Name Parsing
var info = username.Split(','); var lname = info[0].Trim(); var fname = info[1].Trim(); -
Database Lookup
- Queries
EmployeesbyDisplayName - Queries
Jobsbyemployee.JobId
- Queries
-
Azure AD Data Fetch
var ad = new AzureADRead(_context, _configuration); var rec = ad.GetUserADList(employee.WorkEmail); var res = rec.Result; -
ViewModel Construction
- If an Employee record exists: populate
FullName,EmployeeNumber,JobNumber - If not, default
FullNameto Azure AD result - Always assign
Title,Department,Email,PhoneNumberfrom AD
- If an Employee record exists: populate
6. Helper Methods & Utilities
-
AzureADRead.GetUserADList(string email)
- Makes async calls to Azure Graph API
- Returns user’s AD profile (Title, Department, Phone, etc.)
-
String.Split & Trim
- Parses the
"LastName, FirstName"string format.
- Parses the
7. Error Handling & Return Types
- Return Type:
EmployeeDetail(HTTP 200 OK by default) - Potential Exceptions:
IndexOutOfRangeExceptionifusernamedoes not contain,InvalidOperationException/NullReferenceExceptionif DB or AD record is missing
- Improvements:
- Validate
usernameformat - Use
ActionResult<EmployeeDetail>and return404 NotFound()if no data - Wrap AD calls in
try/catchand handle timeouts
- Validate
8. Third‑party Integrations
- Azure Active Directory via Microsoft Graph API
- Entity Framework Core for SQL Server (configured in
IrbyContext)
9. Sample Code Snippets
9.1 Constructor
public UserController(
IActiveDirectoryService activeDirectory,
IrbyContext context,
IConfiguration configuration)
{
_activeDirectory = activeDirectory;
_context = context;
_configuration = configuration;
}
9.2 GetUserDetails Method
[HttpGet]
[Route("/api/User/{username}")]
public EmployeeDetail GetUserDetails(string username)
{
// Parse name
var info = username.Split(',');
var lname = info[0].Trim();
var fname = info[1].Trim();
// DB lookup
var employee = _context.Employees
.FirstOrDefault(e => e.DisplayName == username);
// Azure AD lookup
var ad = new AzureADRead(_context, _configuration);
var res = ad.GetUserADList(employee?.WorkEmail).Result;
// Map to view model
var user = new EmployeeDetail();
if (employee != null)
{
var job = _context.Jobs.Find(employee.JobId);
user.JobNumber = job?.JdeNumber;
user.FullName = employee.FullName;
user.EmployeeNumber = employee.JdeNumber;
}
else
{
user.FullName = res.FullName;
}
user.Title = res.Title;
user.Department = res.Department;
user.Email = res.Email;
user.PhoneNumber = res.PhoneNumber;
return user;
}
10. Usage Examples
Example Request
GET https://your-api-domain.com/api/User/Smith,%20John
Accept: application/json
Example Response (200 OK)
{
"fullName": "John Smith",
"employeeNumber": "EMP12345",
"jobNumber": "JDE67890",
"title": "Senior Engineer",
"department": "Research & Development",
"email": "[email protected]",
"phoneNumber": "+1-555-123-4567"
}
11. UML Class Diagram
classDiagram
UserController --> IActiveDirectoryService
UserController --> IrbyContext
UserController --> IConfiguration
UserController --> AzureADRead
AzureADRead --> IrbyContext
AzureADRead --> IConfiguration
UserController ..> EmployeeDetail : returns
UserController ..> Employee : queries
UserController ..> Job : queries
12. Conclusion
🎯 UserController is a straightforward, single-responsibility API controller that merges on-premise SQL data with Azure Active Directory profiles. It demonstrates:
- Constructor-based Dependency Injection
- EF Core data retrieval
- Async integration with Azure services
- Mapping domain models to API view models
🔧 Next Steps / Improvements
- Add robust error handling and status codes (
404,400,500) - Refactor AD calls to be fully asynchronous (
async/await) - Parameter validation on
usernameinput - Caching AD responses for performance
With this documentation, you now have a clear understanding of how to extend, debug, and consume the UserController API endpoint. 🚀