📄 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

  1. Overview & Purpose
  2. Dependencies & Technologies
  3. Data Models & ViewModels
  4. API Endpoints Overview
  5. Key Functional Areas
  6. Helper Methods & Utilities
  7. Error Handling & Return Types
  8. Third‑party Integrations
  9. Sample Code Snippets
  10. Usage Examples
  11. UML Class Diagram
  12. 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

  1. Constructor Injection

    • _activeDirectory (IActiveDirectoryService): (currently unused in method)
    • _context (IrbyContext): EF Core DB context
    • _configuration (IConfiguration): App settings
  2. Name Parsing

    var info = username.Split(',');
    var lname = info[0].Trim();
    var fname = info[1].Trim();
    
  3. Database Lookup

    • Queries Employees by DisplayName
    • Queries Jobs by employee.JobId
  4. Azure AD Data Fetch

    var ad = new AzureADRead(_context, _configuration);
    var rec = ad.GetUserADList(employee.WorkEmail);
    var res = rec.Result;
    
  5. ViewModel Construction

    • If an Employee record exists: populate FullName, EmployeeNumber, JobNumber
    • If not, default FullName to Azure AD result
    • Always assign Title, Department, Email, PhoneNumber from AD

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.

7. Error Handling & Return Types

  • Return Type: EmployeeDetail (HTTP 200 OK by default)
  • Potential Exceptions:
    • IndexOutOfRangeException if username does not contain ,
    • InvalidOperationException / NullReferenceException if DB or AD record is missing
  • Improvements:
    • Validate username format
    • Use ActionResult<EmployeeDetail> and return 404 NotFound() if no data
    • Wrap AD calls in try/catch and handle timeouts

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 username input
  • 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. 🚀