📚 Documentation: AddNewColumnToDocumentImage Migration

Location:
IrbyImaging.DbContext/Migrations/20230210162723_AddNewColumnToDocumentImage.cs


🗂 Table of Contents

  1. Overview & Purpose
  2. Dependencies & Technologies
  3. Key Functional Areas
  4. Migration Class Details
  5. Data Model Impact
  6. Usage & Examples
  7. UML Diagram
  8. Best Practices & Error Handling
  9. Conclusion

1. Overview & Purpose

This Entity Framework Core migration introduces two new columns—CompletedBy and WorkOrder—to the DocumentImage table in the irby schema.

  • 🎯 Goal: Track who completed processing of each document image and associate it with a specific work order number.
  • 📅 Created On: 2023-02-10 16:27:23
  • 🔄 Migration Type: Add / Remove columns to an existing table

2. Dependencies & Technologies

Technology / Package Version / Notes
.NET SDK ≥ 6.0 (or compatible)
Microsoft.EntityFrameworkCore EF Core for migrations, schema management
Microsoft.EntityFrameworkCore.Relational Adds relational database support
SQL Server (or any EF Core provider) Schema “irby” used in SQL Server example
  • The project must reference Microsoft.EntityFrameworkCore.Design to enable CLI commands.
  • Ensure the DbContext (IrbyImaging.DbContext) is configured to use the correct connection string and provider.

3. Key Functional Areas

  • ➕ Schema Evolution: Adds new data columns without dropping or affecting existing data.
  • 🔄 Versioning: EF Core tracks this migration; Up applies changes, Down reverts them.
  • 📦 Modularity: A self-contained class under the Migrations namespace.

4. Migration Class Details

using Microsoft.EntityFrameworkCore.Migrations;

namespace IrbyImaging.DbContext.Migrations
{
    public partial class AddNewColumnToDocumentImage : Migration
    {
        protected override void Up(MigrationBuilder migrationBuilder)
        {
            migrationBuilder.AddColumn<string>(
                name: "CompletedBy",
                schema: "irby",
                table: "DocumentImage",
                type: "nvarchar(max)",
                nullable: true);

            migrationBuilder.AddColumn<string>(
                name: "WorkOrder",
                schema: "irby",
                table: "DocumentImage",
                type: "nvarchar(max)",
                nullable: true);
        }

        protected override void Down(MigrationBuilder migrationBuilder)
        {
            migrationBuilder.DropColumn(
                name: "CompletedBy",
                schema: "irby",
                table: "DocumentImage");

            migrationBuilder.DropColumn(
                name: "WorkOrder",
                schema: "irby",
                table: "DocumentImage");
        }
    }
}

Up Method

  • Purpose: Applies the migration—adds two nullable nvarchar(max) columns.
  • Calls:
    • migrationBuilder.AddColumn<string>(...)
  • Columns Added:
    1. CompletedBy (string, nullable)
    2. WorkOrder (string, nullable)

Down Method

  • Purpose: Rolls back the migration—drops the two columns if they exist.
  • Calls:
    • migrationBuilder.DropColumn(...)

5. Data Model Impact

DocumentImage Table: Before vs. After

Column Name Data Type Nullable Description
DocumentImageId int No Primary key
ImageUrl nvarchar(max) Yes URL or path of the image
... ... ... Other pre-existing columns
CompletedBy nvarchar(max) Yes User or process that completed the image
WorkOrder nvarchar(max) Yes Associated work order number or ID

6. Usage & Examples

  1. Add the Migration
    dotnet ef migrations add AddNewColumnToDocumentImage \
        --context IrbyImagingDbContext \
        --output-dir Migrations
    
  2. Update the Database
    dotnet ef database update \
        --context IrbyImagingDbContext
    
  3. Revert (if needed)
    dotnet ef database update LastGoodMigrationName
    

💡 Tip: Always review the generated SQL in your development environment before deploying to production.


7. UML Diagram

classDiagram
    class DocumentImage {
        +int DocumentImageId
        +string ImageUrl
        +string CompletedBy
        +string WorkOrder
    }
    class Migration {
        <<abstract>>
        +Up(MigrationBuilder)
        +Down(MigrationBuilder)
    }
    Migration <|-- AddNewColumnToDocumentImage

8. Best Practices & Error Handling

  • Backups: Always back up your database before applying schema changes.
  • Nullability: Making new columns nullable avoids breaking existing INSERTs.
  • Testing:
    • Unit-test your DbContext to ensure it still reads/writes correctly.
    • Use a staging database to run database update.
  • Error Scenarios:
    • Column already exists: EF will error; use IF NOT EXISTS in raw SQL if dynamic checks are needed.
    • Data type mismatch on rollback: Ensure no dependent objects (e.g., views, SPs) reference these columns when dropping.

9. Conclusion

🎉 This migration cleanly extends the DocumentImage entity by adding CompletedBy and WorkOrder, enabling richer metadata tracking for document processing workflows. Through EF Core’s Up and Down methods, you get reversible, versioned schema changes that fit smoothly into CI/CD pipelines.

“Schema migrations are like time travel for your database. Migrations let you move your schema forward and back, one step at a time.” – EF Core Docs


Generated on: 2024‑06‑xx
IrbyImaging.DbContext • Migration: AddNewColumnToDocumentImage 🚀