20230706142626_NewIsLegalDocumentColumnDocumentCategory.cs

# ๐Ÿ“‹ Table of Contents

1. [๐Ÿš€ Overview & Purpose](#-overview--purpose)  
2. [โš™๏ธ Dependencies & Technologies](#๏ธ-dependencies--technologies)  
3. [๐Ÿ”‘ Key Functional Areas](#๏ธ-key-functional-areas)  
4. [๐Ÿ“ฆ Data Models Affected](#-data-models-affected)  
5. [๐Ÿ›  Migration Implementation](#-migration-implementation)  
   - [Up Method](#up-method)  
   - [Down Method](#down-method)  
6. [๐Ÿ“ˆ Entityโ€‘Relationship UML Diagram](#-entityrelationship-uml-diagram)  
7. [๐Ÿ’ก Usage Examples & Commands](#-usage-examples--commands)  
8. [โš–๏ธ Error Handling & Rollback](#๏ธ-error-handling--rollback)  
9. [โœ… Best Practices](#-best-practices)  
10. [๐Ÿ“ Conclusion](#-conclusion)  

---

## ๐Ÿš€ Overview & Purpose

The **`20230706142626_NewIsLegalDocumentColumnDocumentCategory`** migration introduces a new boolean column **`IsLegalDocument`** into three core database tables within the `irby` schema:

- **`DocumentType`**  
- **`DocumentCategory`**  
- **`DocumentAttribute`**

**Why?**  
Legal regulations often require that certain documents be flagged for special handling, retention, or audit trails. By adding **`IsLegalDocument`**, the application can:

- ๐Ÿ” Easily filter or classify โ€œlegalโ€ vs. โ€œnon-legalโ€ documents  
- ๐Ÿ—‚๏ธ Trigger workflows (e.g., retention policies) for documents marked as legal  
- ๐Ÿ“Š Generate compliance reports  

---

## โš™๏ธ Dependencies & Technologies

| Technology / Package                          | Version / Notes                                    |
|-----------------------------------------------|-----------------------------------------------------|
| .NET / C#                                     | .NET 6.0+ (C# 10)                                   |
| Microsoft.EntityFrameworkCore                 | >= 6.0.0                                            |
| Microsoft.EntityFrameworkCore.Design          | >= 6.0.0                                            |
| Microsoft.EntityFrameworkCore.SqlServer       | >= 6.0.0 (assuming SQL Server)                     |
| Microsoft.EntityFrameworkCore.Tools           | >= 6.0.0                                            |

- **Schema**: All tables reside under the **`irby`** schema.  
- **Migration System**: Utilizes EF Core Codeโ€‘First Migrations.

---

## ๐Ÿ”‘ Key Functional Areas

1. **Schema Evolution**  
   - Schema-first approach to add a new column across multiple tables.  
2. **Backward Compatibility**  
   - Default value (`false`) ensures existing rows are unaffected logically.  
3. **Rollback Support**  
   - The **`Down`** method cleanly drops the added columns.  

---

## ๐Ÿ“ฆ Data Models Affected

After applying this migration, your **entity classes** (in `IrbyImaging.DbContext`) should include:

```csharp
namespace IrbyImaging.DbContext.Entities
{
    public class DocumentType
    {
        public int Id { get; set; }
        // ... other properties ...
        public bool IsLegalDocument { get; set; }  // <-- New
    }

    public class DocumentCategory
    {
        public int Id { get; set; }
        // ... other properties ...
        public bool IsLegalDocument { get; set; }  // <-- New
    }

    public class DocumentAttribute
    {
        public int Id { get; set; }
        // ... other properties ...
        public bool IsLegalDocument { get; set; }  // <-- New
    }
}
Table New Column CLR Type SQL Type Default
DocumentType IsLegalDocument bool bit false
DocumentCategory IsLegalDocument bool bit false
DocumentAttribute` IsLegalDocument bool bit false

๐Ÿ›  Migration Implementation

using Microsoft.EntityFrameworkCore.Migrations;

#nullable disable

namespace IrbyImaging.DbContext.Migrations
{
    /// <inheritdoc />
    public partial class NewIsLegalDocumentColumnDocumentCategory : Migration
    {
        /// <inheritdoc />
        protected override void Up(MigrationBuilder migrationBuilder)
        {
            migrationBuilder.AddColumn<bool>(
                name: "IsLegalDocument",
                schema: "irby",
                table: "DocumentType",
                type: "bit",
                nullable: false,
                defaultValue: false);

            migrationBuilder.AddColumn<bool>(
                name: "IsLegalDocument",
                schema: "irby",
                table: "DocumentCategory",
                type: "bit",
                nullable: false,
                defaultValue: false);

            migrationBuilder.AddColumn<bool>(
                name: "IsLegalDocument",
                schema: "irby",
                table: "DocumentAttribute",
                type: "bit",
                nullable: false,
                defaultValue: false);
        }

        /// <inheritdoc />
        protected override void Down(MigrationBuilder migrationBuilder)
        {
            migrationBuilder.DropColumn(
                name: "IsLegalDocument",
                schema: "irby",
                table: "DocumentType");

            migrationBuilder.DropColumn(
                name: "IsLegalDocument",
                schema: "irby",
                table: "DocumentCategory");

            migrationBuilder.DropColumn(
                name: "IsLegalDocument",
                schema: "irby",
                table: "DocumentAttribute");
        }
    }
}

Up Method

  • AddColumn<bool>
    • Adds a non-nullable bit column named IsLegalDocument with a default value of false to ensure existing data is valid.

Down Method

  • DropColumn
    • Removes the previously added IsLegalDocument column from each table, fully reverting the schema change.

๐Ÿ“ˆ EntityRelationship UML Diagram

erDiagram
    DOCUMENT_TYPE {
        int    Id PK
        bool   IsLegalDocument
        -- other fields --
    }
    DOCUMENT_CATEGORY {
        int    Id PK
        bool   IsLegalDocument
        -- other fields --
    }
    DOCUMENT_ATTRIBUTE {
        int    Id PK
        bool   IsLegalDocument
        -- other fields --
    }

๐Ÿ’ก Usage Examples & Commands

  1. Add Migration

    dotnet ef migrations add NewIsLegalDocumentColumnDocumentCategory \
      --project IrbyImaging.DbContext \
      --startup-project IrbyImaging.API
    
  2. Update Database

    dotnet ef database update \
      --project IrbyImaging.DbContext \
      --startup-project IrbyImaging.API
    
  3. Querying

    using var context = new IrbyDbContext(...);
    var legalDocs = context.DocumentType
                            .Where(dt => dt.IsLegalDocument)
                            .ToList();
    
  4. Seeding Example

    migrationBuilder.UpdateData(
        schema: "irby",
        table: "DocumentCategory",
        keyColumn: "Id",
        keyValue: 1,
        column: "IsLegalDocument",
        value: true);
    

โš–๏ธ Error Handling & Rollback

  • Migration Failures: EF Core will throw a descriptive exception if the column addition conflicts (e.g., existing column of same name).
  • Automatic Rollback: If Up fails midโ€‘operation, EF Core attempts to revert changes in that transaction.
  • Manual Rollback: Use
    dotnet ef database update LastGoodMigrationName
    
    to step back.

โœ… Best Practices

  • Backup your database before applying schema changes in production.
  • Review Default Values carefully: here, a default of false ensures no document is accidentally marked legal.
  • Incremental Migrations: Keep migration files small and focused on a single concern.
  • Documentation & Comments: Use XML comments (/// <inheritdoc/>) to link to EF Core base behavior.

๐Ÿ“ Conclusion

This migration is a minimal yet critical enhancement that enables legal-document flagging across key tables. It lays the groundwork for legal compliance featuresโ€”retention policies, audits, and reporting. By following the steps above, you can generate, apply, and roll back this migration smoothly while integrating IsLegalDocument into your codebase and workflows.


Happy Coding! ๐ŸŽ‰