📑 Migration Documentation: 20240724182925_AddAutoIncrementTimesheetNumber.cs


📚 Table of Contents

  1. Overview & Purpose
  2. Dependencies & Technologies
  3. Key Functional Areas
  4. Data Model Impact
  5. UML Class Diagram
  6. Using This Migration
  7. Best Practices & Tips
  8. Conclusion 🎯

1. Overview & Purpose

This Entity Framework Core migration AddAutoIncrementTimesheetNumber introduces a new auto-incrementing column TimesheetNumber to the MechanicTimesheet table in the irby schema.

  • 📝 Why?
    • To assign each timesheet a unique, sequential number automatically.
    • Simplifies referencing and reporting on timesheets.
  • 🎯 Goal:
    Ensure MechanicTimesheet.TimesheetNumber starts at 1 and increments by 1 for each new record.

2. Dependencies & Technologies

Technology / Package Version Purpose
Microsoft.EntityFrameworkCore 7.x (or above) Core ORM and migration framework
Microsoft.EntityFrameworkCore.SqlServer 7.x (or above) SQL Server provider for EF Core migrations
.NET SDK 7.x (or above) .NET runtime and tooling
SQL Server 2012 (or above) Database engine supporting IDENTITY columns

3. Key Functional Areas

3.1 Migration Class Definition

namespace IrbyImaging.DbContext.Migrations
{
    public partial class AddAutoIncrementTimesheetNumber : Migration
    {
        // ... Up and Down methods ...
    }
}
  • Namespace: IrbyImaging.DbContext.Migrations
  • Class: AddAutoIncrementTimesheetNumber inherits from Migration
  • Attributes:
    • partial allows splitting across multiple files if needed.
    • <inheritdoc /> XML tags ensure inherited documentation.

3.2 Up Method 🔼

protected override void Up(MigrationBuilder migrationBuilder)
{
    migrationBuilder.AddColumn<int>(
        name: "TimesheetNumber",
        schema: "irby",
        table: "MechanicTimesheet",
        type: "int",
        nullable: false,
        defaultValue: 0)
    .Annotation("SqlServer:Identity", "1, 1");
}

What it does:

  • AddColumn<int>
    Adds a new column of SQL type int.

  • Column Options:

    Option Value Description
    name "TimesheetNumber" Column name
    schema "irby" Schema in the database
    table "MechanicTimesheet" Target table
    nullable false Column must have a value
    defaultValue 0 Default for backfilled rows
  • Identity Annotation:
    .Annotation("SqlServer:Identity", "1, 1")
    Automatically generates values starting at 1, incrementing by 1.


3.3 Down Method 🔽

protected override void Down(MigrationBuilder migrationBuilder)
{
    migrationBuilder.DropColumn(
        name: "TimesheetNumber",
        schema: "irby",
        table: "MechanicTimesheet");
}

Purpose:

  • Reverts the database to its prior state by dropping the TimesheetNumber column.
  • Ensures idempotence of migrations (you can roll back cleanly).

4. Data Model Impact

After applying this migration, the MechanicTimesheet table schema changes as follows:

Column Type Nullable Identity Default
*Id int ❌ ✅ —
MechanicId int ❌ ❌ —
... ... ... ... ...
TimesheetNumber int ❌ ✅ 0
  • New Column: TimesheetNumber
  • Usage: Serves as a human-friendly, sequential identifier.

5. UML Class Diagram

+---------------------------------------+
|         Migration (abstract)         |
+---------------------------------------+
| + Up(builder: MigrationBuilder)      |
| + Down(builder: MigrationBuilder)    |
+---------------------------------------+
               ▲
               |
+---------------------------------------+
| AddAutoIncrementTimesheetNumber      |
+---------------------------------------+
| // Inherits Up & Down                |
+---------------------------------------+
  • Migration: Base class providing Up/Down hooks
  • AddAutoIncrementTimesheetNumber: Concrete migration to add/drop the column

6. Using This Migration

6.1 Adding the Migration

dotnet ef migrations add AddAutoIncrementTimesheetNumber \
    --project IrbyImaging.DbContext \
    --output-dir Migrations

6.2 Applying to Database

dotnet ef database update \
    --project IrbyImaging.DbContext
  • ✅ Apply: Creates the column with auto-increment.
  • ⏪ Rollback:
    dotnet ef database update LastGoodMigrationName
    
    Invokes the Down method and removes TimesheetNumber.

7. Best Practices & Tips

  • 💾 Backup your database before running migrations in production.
  • 🔎 Test migrations in staging environments.
  • 📄 Review generated SQL via --verbose switch:
    dotnet ef migrations script --verbose
    
  • 🛠 Handle Large Tables: Back-filling default values on big tables may lock rows. Consider batching.

8. Conclusion 🎯

This migration automates the assignment of sequential TimesheetNumber values, improving data consistency and traceability. It follows EF Core best practices by providing reversible operations (Up / Down).

With this change in place, your application can reliably reference and display timesheet numbers without manual management.


End of Documentation
🚀 Happy Coding!