π Migration Documentation: AddNewColumnToDocumentImageTable
File Path:
IrbyImaging.DbContext/Migrations/20230802150235_AddNewColumnToDocumentImageTable.cs
π Table of Contents
- Overview & Purpose
- Dependencies & Technologies
- Key Functional Areas
- Data Model Change
- Migration Class Structure
- Methods: Up() & Down()
- Applying & Rolling Back the Migration
- Usage Example
- UML Diagram
- Common Pitfalls & Troubleshooting
- Conclusion
π Overview & Purpose
This Entity Framework Core Migration adds a new nullable column named RolesCanAccess to the DocumentImage table in the irby schema.
-
Why?
- π The application requires the ability to store which user roles are permitted to view or manipulate each document image.
- π Instead of overloading existing tables or creating a separate join table, a simple string column holds role identifiers (e.g.,
"Admin,Editor,Viewer").
-
When?
- During deployment of a new feature that introduces role-based access control for document images.
π Dependencies & Technologies
| Layer / Tool | Version / Notes |
|---|---|
| .NET SDK | 6.0 / 7.0+ |
| Entity Framework Core | 6.x / 7.x |
| Database Provider (e.g. SQLServer) | Microsoft.EntityFrameworkCore.SqlServer |
| C# Language | 10+ |
Note:
This migration file depends on the EF Core CLI to scaffold and apply migrations (dotnet ef).
π Key Functional Areas
- Schema Modification
- Adds or removes a column in the DB.
- Versioning
- Each migration is timestamped and can be applied or rolled back.
- Idempotence
Up()andDown()ensure safe forward/backward steps.
π οΈ Data Model Change
| Table | Schema | Column Name | Data Type | Nullable | Purpose |
|---|---|---|---|---|---|
| DocumentImage | irby | RolesCanAccess | nvarchar(max) | Yes | Commaβdelimited list of roles allowed. |
Entity class update (C#):
public class DocumentImage { public int Id { get; set; } public byte[] Content { get; set; } // NEW PROPERTY: public string? RolesCanAccess { get; set; } }
ποΈ Migration Class Structure
namespace IrbyImaging.DbContext.Migrations
{
public partial class AddNewColumnToDocumentImageTable : Migration
{
protected override void Up(MigrationBuilder migrationBuilder) { /* ... */ }
protected override void Down(MigrationBuilder migrationBuilder) { /* ... */ }
}
}
AddNewColumnToDocumentImageTable- Inherits from
Migration. - Contains two essential methods:
Up(...)β defines schema changes to apply.Down(...)β reverts those changes.
- Inherits from
π Methods: Up() & Down()
Up(MigrationBuilder migrationBuilder)
-
Purpose: Applies the schema change.
-
Key Call:
migrationBuilder.AddColumn<string>( name: "RolesCanAccess", schema: "irby", table: "DocumentImage", type: "nvarchar(max)", nullable: true); -
Effect:
- Adds a new column that can store a long Unicode string.
- Because
nullable: true, existing rows wonβt break.
Down(MigrationBuilder migrationBuilder)
-
Purpose: Rolls back the schema change.
-
Key Call:
migrationBuilder.DropColumn( name: "RolesCanAccess", schema: "irby", table: "DocumentImage"); -
Effect:
- Completely removes the column.
- All stored data in
RolesCanAccesswill be lost.
π Applying & Rolling Back the Migration
- Add the Migration
dotnet ef migrations add AddNewColumnToDocumentImageTable - Apply to Database
dotnet ef database update - Rollback (if needed)
dotnet ef database update LastGoodMigrationName
π Usage Example
Suppose you want to restrict a document image to Admins and Editors:
var image = new DocumentImage
{
Content = GetImageBytes(),
RolesCanAccess = "Admin,Editor"
};
dbContext.DocumentImages.Add(image);
dbContext.SaveChanges();
Later, in your authorization logic:
bool CanUserView(DocumentImage img, string userRole)
{
var roles = img.RolesCanAccess?.Split(',', StringSplitOptions.RemoveEmptyEntries)
?? Array.Empty<string>();
return roles.Contains(userRole, StringComparer.OrdinalIgnoreCase);
}
π UML Diagram
classDiagram
class Migration {
<<abstract>>
+void Up(MigrationBuilder)
+void Down(MigrationBuilder)
}
class AddNewColumnToDocumentImageTable {
+void Up(MigrationBuilder)
+void Down(MigrationBuilder)
}
Migration <|-- AddNewColumnToDocumentImageTable
π§ Common Pitfalls & Troubleshooting
| Issue | Solution |
|---|---|
| EF CLI timeout / network issues | Ensure DB is reachable. Use connection string in appsettings.json. |
| Column already exists | Check __EFMigrationsHistory table. Rolled-back partially? Remove duplicate migration or adjust. |
| Data loss on Down() | Backup your DB before rolling back. |
| Mismatched namespace or schema | Verify schema: "irby" matches your DB schema. |
π― Conclusion
This migration is a lightweight yet crucial step toward implementing role-based access control on document images.
By following the steps above and integrating the new property into your application logic, you can dynamically configure which roles may access each image record.
Happy coding! π