π 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
- Overview & Purpose
- Dependencies & Technologies
- Data Model & Schema Mapping
- Class Definition & Key Functional Areas
- UML Class Diagram
- Sample Code Blocks
- Usage Examples
- Error Handling & Validation
- Best Practices & Conventions
- 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: AGuidacting as the primary key.VehicleId: Astringrepresenting 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 ofId. - Null Checks: Because
VehicleIdis a plainstring, it can be null unless constrained further.- Consider adding
[Required]or a max-length attribute[MaxLength(50)]if business rules demand.
- Consider adding
- Exception Handling: Wrap EF calls in try/catch to handle
DbUpdateException,SqlException, etc.
9. Best Practices & Conventions
- π± Always assign a new
GuidtoIdbefore adding to the context, or configure EF to generate it automatically. - π Protect sensitive schemas by limiting context privileges to the
irbyschema 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