πŸš— Vehicle Domain Class Documentation

Welcome to the Vehicle domain class documentation! This guide provides a detailed overview, usage examples, UML diagrams, and best practices for working with the Vehicle entity in the IrbyImaging.DomainClasses project.


πŸ“‘ Table of Contents

  1. Overview & Purpose
  2. Dependencies & Technologies
  3. Data Model & Schema Mapping
  4. Class Definition & Key Functional Areas
  5. UML Class Diagram
  6. Sample Code Blocks
  7. Usage Examples
  8. Error Handling & Validation
  9. Best Practices & Conventions
  10. Conclusion

1. Overview & Purpose

Vehicle.cs defines a simple domain entity representing a vehicle in the Irby Imaging system. It is part of the DomainClasses layer, which models core business concepts and is mapped to a relational database using Entity Framework (EF).

  • πŸ“Œ Primary goal: Store and retrieve vehicle identifiers in a strongly-typed, schema-aware manner.
  • 🎯 Intended use:
    • Persist vehicle records in the database.
    • Participate in domain-driven operations such as registration, lookup, and reporting.

2. Dependencies & Technologies

Technology / Package Version (example) Purpose
.NET / .NET Core β‰₯ 5.0 Runtime framework
Microsoft.EntityFrameworkCore β‰₯ 5.0 ORM for database mapping
System.ComponentModel.DataAnnotations Built‑in Data annotation attributes (keys, etc.)
System.ComponentModel.DataAnnotations.Schema Built‑in Table & schema mapping

3. Data Model & Schema Mapping

The Vehicle class is decorated with EF Core attributes to control how it maps to your database schema.

Attribute Applies To Description
[Table("Vehicle", Schema = "irby")] Class Maps this entity to the irby.Vehicle table.
[Key] Id property Marks Id as the primary key for this entity.

4. Class Definition & Key Functional Areas

using System;
using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace IrbyImaging.DomainClasses
{
    [Table("Vehicle", Schema = "irby")]
    public class Vehicle
    {
        /// <summary>
        /// Gets or sets the unique identifier of the record.
        /// </summary>
        [Key]
        public Guid Id { get; set; }

        /// <summary>
        /// Gets or sets the business-level vehicle identifier.
        /// </summary>
        public string VehicleId { get; set; }
    }
}

Key Points

  • Id: A Guid acting as the primary key.
  • VehicleId: A string representing a human- or system-readable identifier (e.g., VIN or internal code).

5. UML Class Diagram

classDiagram
    class Vehicle {
        <<Entity>>
        + Guid Id
        + string VehicleId
    }
    note for Vehicle "Mapped to irby.Vehicle table\nusing EF Core Data Annotations"

6. Sample Code Blocks

6.1. Defining the DbContext

public class ImagingDbContext : DbContext
{
    public ImagingDbContext(DbContextOptions<ImagingDbContext> options)
        : base(options) { }

    public DbSet<Vehicle> Vehicles { get; set; }

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        modelBuilder
            .HasDefaultSchema("irby")
            .Entity<Vehicle>()
                .ToTable("Vehicle");
    }
}

6.2. Repository Pattern Example

public interface IVehicleRepository
{
    Task<Vehicle> GetByIdAsync(Guid id);
    Task AddAsync(Vehicle vehicle);
    // ... other methods
}

public class VehicleRepository : IVehicleRepository
{
    private readonly ImagingDbContext _context;
    public VehicleRepository(ImagingDbContext context) => _context = context;

    public async Task<Vehicle> GetByIdAsync(Guid id) =>
        await _context.Vehicles.FindAsync(id);

    public async Task AddAsync(Vehicle vehicle)
    {
        await _context.Vehicles.AddAsync(vehicle);
        await _context.SaveChangesAsync();
    }
}

7. Usage Examples

7.1. Creating and Saving a Vehicle

// 1. Initialize context (e.g., via DI in ASP.NET Core)
var dbContext = serviceProvider.GetRequiredService<ImagingDbContext>();

// 2. Instantiate the domain entity
var newVehicle = new Vehicle
{
    Id = Guid.NewGuid(),         // Unique record key
    VehicleId = "IRBY-TRUCK-001" // Business identifier
};

// 3. Persist to database
await dbContext.Vehicles.AddAsync(newVehicle);
await dbContext.SaveChangesAsync();

Console.WriteLine($"Vehicle {newVehicle.VehicleId} saved with Id {newVehicle.Id}");

7.2. Retrieving a Vehicle

var existing = await dbContext.Vehicles
    .FirstOrDefaultAsync(v => v.VehicleId == "IRBY-TRUCK-001");

if (existing != null)
{
    Console.WriteLine($"Found vehicle with GUID: {existing.Id}");
}

8. Error Handling & Validation

  • DataAnnotations: The [Key] attribute ensures EF will validate presence of Id.
  • Null Checks: Because VehicleId is a plain string, it can be null unless constrained further.
    • Consider adding [Required] or a max-length attribute [MaxLength(50)] if business rules demand.
  • Exception Handling: Wrap EF calls in try/catch to handle DbUpdateException, SqlException, etc.

9. Best Practices & Conventions

  • 🌱 Always assign a new Guid to Id before adding to the context, or configure EF to generate it automatically.
  • πŸ”’ Protect sensitive schemas by limiting context privileges to the irby schema only.
  • πŸ“ Document business rules for VehicleId (format, uniqueness) and enforce via code or database constraints.
  • πŸ”„ Naming Conventions: Class names match table names (singular) by default, keeping consistency.

10. Conclusion

The Vehicle domain class is a foundational piece in the Irby Imaging system for representing and persisting vehicle records. By leveraging Entity Framework Core’s data annotations and following the best practices illustrated above, you can seamlessly integrate this entity into repositories, services, and API endpoints.

Feel free to extend this class with additional properties (e.g., Make, Model, Year) or methods (e.g., ToString(), domain behaviors) as your business requirements evolve. Happy coding! πŸš€


End of Vehicle.cs Documentation