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
bitcolumn namedIsLegalDocumentwith a default value offalseto ensure existing data is valid.
- Adds a non-nullable
Down Method
DropColumn- Removes the previously added
IsLegalDocumentcolumn from each table, fully reverting the schema change.
- Removes the previously added
๐ 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
-
Add Migration
dotnet ef migrations add NewIsLegalDocumentColumnDocumentCategory \ --project IrbyImaging.DbContext \ --startup-project IrbyImaging.API -
Update Database
dotnet ef database update \ --project IrbyImaging.DbContext \ --startup-project IrbyImaging.API -
Querying
using var context = new IrbyDbContext(...); var legalDocs = context.DocumentType .Where(dt => dt.IsLegalDocument) .ToList(); -
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
Upfails midโoperation, EF Core attempts to revert changes in that transaction. - Manual Rollback: Use
to step back.dotnet ef database update LastGoodMigrationName
โ Best Practices
- Backup your database before applying schema changes in production.
- Review Default Values carefully: here, a default of
falseensures 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! ๐