هدف از این مطلب، ارائه راه حلی برای تولید خودکار کد یا شماره یکتا و ترتیبی در زمان ثبت رکورد جدید به صورت یکپارچه با EF Core، میباشد. به عنوان مثال فرض کنید در زمان ثبت سفارش، نیاز است بر اساس یکسری تنظیمات، یک شماره منحصر به فرد برای آن سفارش، تولید شده و در فیلدی تحت عنوان Number قرار گیرد؛ یا به صورت کلی برای موجودیتهایی که نیاز به یک نوع شماره گذاری منحصر به فرد دارند، مانند: سفارش، طرف حساب و ...
یک مثال واقعی
در زمان ثبت یک Task، کاربر میتواند به صورت دستی یک شماره منحصر به فرد را نیز وارد کند؛ در غیر این صورت سیستم به طور خودکار شمارهای را به رکورد در حال ثبت اختصاص خواهد داد. بررسی یکتایی این کد در صورت وارد کردن به صورت دستی، توسط اعتبارسنج مرتبط باید انجام گیرد؛ ولی در غیر این صورت، زیرساخت مورد نظر تضمین میکند که شماره یکتایی را ایجاد کند.
ایجاد یک قرارداد برای موجودیتهای دارای شماره منحصر به فرد
public interface INumberedEntity
{
string Number { get; set; }
}
با استفاده از این واسط میتوان از تکرار یکسری از تنظیمات مانند تنظیم طول فیلد Number و همچنین ایجاد ایندکس منحصر به فرد برروی آن، به شکل زیر جلوگیری کرد.
foreach (var entityType in builder.Model.GetEntityTypes()
.Where(e => typeof(INumberedEntity).IsAssignableFrom(e.ClrType)))
{
builder.Entity(entityType.ClrType)
.Property(nameof(INumberedEntity.Number)).IsRequired().HasMaxLength(50);
if (typeof(IMultiTenantEntity).IsAssignableFrom(entityType.ClrType))
{
builder.Entity(entityType.ClrType)
.HasIndex(nameof(INumberedEntity.Number), nameof(IMultiTenantEntity.TenantId))
.HasName(
$"UIX_{entityType.ClrType.Name}_{nameof(IMultiTenantEntity.TenantId)}_{nameof(INumberedEntity.Number)}")
.IsUnique();
}
else
{
builder.Entity(entityType.ClrType)
.HasIndex(nameof(INumberedEntity.Number))
.HasName($"UIX_{entityType.ClrType.Name}_{nameof(INumberedEntity.Number)}")
.IsUnique();
}
}
ایجاد یک Entity برای نگهداری شماره قابل استفاده بعدی مرتبط با موجودیتها
public class NumberedEntity : Entity, IMultiTenantEntity
{
public string EntityName { get; set; }
public long NextNumber { get; set; }
public long TenantId { get; set; }
}
با تنظیمات زیر:
public class NumberedEntityConfiguration : IEntityTypeConfiguration<NumberedEntity>
{
public void Configure(EntityTypeBuilder<NumberedEntity> builder)
{
builder.Property(a => a.EntityName).HasMaxLength(256).IsRequired().IsUnicode(false);
builder.HasIndex(a => a.EntityName).HasName("UIX_NumberedEntity_EntityName").IsUnique();
builder.ToTable(nameof(NumberedEntity));
}
}
شاید به نظر، استفاده از این موجودیت ضروریتی نداشته باشد و خیلی راحت میتوان آخرین شماره ثبت شدهی در جدول مورد نظر را واکشی، مقداری را به آن اضافه و به عنوان شماره منحصر به فرد رکورد جدید استفاده کرد؛ با این رویکرد حداقل دو مشکل زیر را خواهیم داشت:
- ایجاد Gap مابین شمارههای تولید شده، که مدنظر ما نمیباشد. (با توجه به اینکه امکان ثبت دستی را هم داریم، ممکن است کاربر شمارهای را وارد کرده باشد که با آخرین شماره ثبت شده تعداد زیادی فاصله دارد که به خودی خود مشکل ساز نیست؛ ولی در زمان ثبت رکورد بعدی اگر به صورت خودکار ثبت شماره داشته باشد، قطعا آخرین شماره (بزرگترین) را که به صورت دستی وارد شده بود، از جدول دریافت خواهد کرد)
پیاده سازی یک PreInsertHook برای مقداردهی پراپرتی Number
internal class NumberingPreInsertHook : PreInsertHook<INumberedEntity>
{
private readonly IUnitOfWork _uow;
private readonly IOptions<NumberingConfiguration> _configuration;
public NumberingPreInsertHook(IUnitOfWork uow, IOptions<NumberingConfiguration> configuration)
{
_uow = uow ?? throw new ArgumentNullException(nameof(uow));
_configuration = configuration ?? throw new ArgumentNullException(nameof(configuration));
}
protected override void Hook(INumberedEntity entity, HookEntityMetadata metadata)
{
if (!entity.Number.IsNullOrEmpty()) return;
bool retry;
string nextNumber;
do
{
nextNumber = GenerateNumber(entity);
var exists = CheckDuplicateNumber(entity, nextNumber);
retry = exists;
} while (retry);
entity.Number = nextNumber;
}
private bool CheckDuplicateNumber(INumberedEntity entity, string nextNumber)
{
//...
}
private string GenerateNumber(INumberedEntity entity)
{
//...
}
}
ابتدا بررسی میشود اگر پراپرتی Number مقداردهی شدهاست، عملیات مقداردهی خودکار برروی آن انجام نگیرد. سپس با توجه به اینکه ممکن است به صورت دستی قبلا شمارهای مانند Task_1000 وارد شده باشد و NextNumber مرتبط هم مقدار 1000 را داشته باشد؛ در این صورت به هنگام ثبت رکورد بعدی، با توجه به Prefix تنظیم شده، دوباره به شماره Task_1000 خواهیم رسید که در این مورد خاص با استفاده از متد CheckDuplicateNumber این قضیه تشخیص داده شده و سعی مجددی برای تولید شماره جدید صورت میگیرد.
بررسی متد GenerateNumber
private string GenerateNumber(INumberedEntity entity)
{
var option = _configuration.Value.NumberedEntityOptions[entity.GetType()];
var entityName = $"{entity.GetType().FullName}";
var lockKey = $"Tenant_{_uow.TenantId}_" + entityName;
_uow.ObtainApplicationLevelDatabaseLock(lockKey);
var nextNumber = option.Start.ToString();
var numberedEntity = _uow.Set<NumberedEntity>().AsNoTracking().FirstOrDefault(a => a.EntityName == entityName);
if (numberedEntity == null)
{
_uow.ExecuteSqlCommand(
"INSERT INTO [dbo].[NumberedEntity]([EntityName], [NextNumber], [TenantId]) VALUES(@p0,@p1,@p2)", entityName,
option.Start + option.IncrementBy, _uow.TenantId);
}
else
{
nextNumber = numberedEntity.NextNumber.ToString();
_uow.ExecuteSqlCommand("UPDATE [dbo].[NumberedEntity] SET [NextNumber] = @p0 WHERE [Id] = @p1 ",
numberedEntity.NextNumber + option.IncrementBy, numberedEntity.Id);
}
if (!string.IsNullOrEmpty(option.Prefix))
nextNumber = option.Prefix + nextNumber;
return nextNumber;
}
ابتدا با استفاده از متد الحاقی ObtainApplicationLevelDatabaseLock یک قفل منطقی را برروی یک منبع مجازی (lockKey) در سطح نرم افزار از طریق sp_getapplock ایجاد میکنیم. به این ترتیب بدون نیاز به درگیر شدن با مباحث isolation level بین تراکنشهای همزمان یا سایر مباحث locking در سطح row یا table، به نتیجه مطلوب رسیده و تراکنش دوم که خواهان ثبت Task جدید میباشد، با توجه به اینکه INumberedEntity میباشد، لازم است پشت این global lock صبر کند و بعد از commit یا rollback شدن تراکنش جاری، به صورت خودکار قفل منبع مورد نظر باز خواهد شد.
پیاده سازی متد مذکور به شکل زیر میباشد:
public static void ObtainApplicationLevelDatabaseLock(this IUnitOfWork uow, string resource)
{
uow.ExecuteSqlCommand(@"EXEC sp_getapplock @Resource={0}, @LockOwner={1},
@LockMode={2} , @LockTimeout={3};", resource, "Transaction", "Exclusive", 15000);
}
با توجه به اینکه ممکن است درون تراکنش جاری چندین نمونه از موجودیتهای INumberedEntity در حال ذخیره سازی باشند و از طرفی Hook ایجاد شده به ازای تک تک نمونهها قرار است اجرا شود، ممکن است تصور این باشد که اجرای مجدد sp مذکور مشکل ساز شود و در واقع به Lock خود برخواهد خورد؛ ولی از آنجایی که پارامتر LockOwner با "Transaction" مقداردهی میشود، لذا فراخوانی مجدد این sp درون تراکنش جاری مشکل ساز نخواهد بود.
گام بعدی، واکشی NextNumber مرتبط با موجودیت جاری میباشد؛ اگر در حال ثبت اولین رکورد هستیم، لذا numberedEntity مورد نظر مقدار null را خواهد داشت و لازم است شماره بعدی را برای موجودیت جاری ثبت کنیم. در غیر این صورت عملیات ویرایش با اضافه کردن IncrementBy به مقدار فعلی انجام میگیرد. در نهایت اگر Prefix ای تنظیم شده باشد نیز به ابتدای شماره تولیدی اضافه شده و بازگشت داده خواهد شد.
ساختار NumberingConfiguration
public class NumberingConfiguration
{
public bool Enabled { get; set; }
public IDictionary<Type, NumberedEntityOption> NumberedEntityOptions { get; } =
new Dictionary<Type, NumberedEntityOption>();
}
public class NumberedEntityOption
{
public string Prefix { get; set; }
public int Start { get; set; } = 1;
public int IncrementBy { get; set; } = 1;
}
با استفاده از دوکلاس بالا، امکان تنظیم الگوی تولید برای موجودیتها را خواهیم داشت.
گام آخر: ثبت PreInsertHook توسعه داده شده و همچنین تنظیمات مرتبط با الگوی تولید شماره موجودیتها
public static void AddNumbering(this IServiceCollection services,
IDictionary<Type, NumberedEntityOption> options)
{
services.Configure<NumberingConfiguration>(configuration =>
{
configuration.Enabled = true;
configuration.NumberedEntityOptions.AddRange(options);
});
services.AddTransient<IPreActionHook, NumberingPreInsertHook>();
}
و استفاده از این متد الحاقی در Startup پروژه
services.AddNumbering(new Dictionary<Type, NumberedEntityOption>
{
[typeof(Task)] = new NumberedEntityOption
{
Prefix = "T_",
Start = 1000,
IncrementBy = 5
}
});
و موجودیت Task
public class Task : TrackableEntity, IAggregateRoot, INumberedEntity
{
public const int MaxTitleLength = 256;
public const int MaxDescriptionLength = 1024;
public string Title { get; set; }
public string NormalizedTitle { get; set; }
public string Description { get; set; }
public TaskState State { get; set; } = TaskState.Todo;
public byte[] RowVersion { get; set; }
public string Number { get; set; }
}
با خروجیهای زیر
پ.ن ۱: در برخی از Domainها نیاز به ریست کردن این شمارهها براساس یکسری فیلد موجود در موجودیت مورد نظر نیز مطرح میباشد. به عنوان مثال در یک سیستم انبارداری شاید براساس FiscalYear و در یک سیستم فروش با توجه به نحوه فروش (SaleType)، لازم باشد این ریست برای شمارههای موجودیت «سفارش»، انجام پذیرد. در کل با کمی تغییرات میتوان از این روش مطرح شده در چنین حالاتی نیز به عنوان یک ابزار شماره گذاری خودکار کمک گرفت.
پ.ن ۲: استفاده از امکانات Sequence در Sql Server هم شاید اولین راه حلی باشد که به ذهن میرسد؛ ولی از آنجایی که از تراکنشها پشتیبانی ندارد، مسئله Gap بین شمارهها پابرجاست و همچنین آزادی عملی را به این شکل که در مطلب مطرح شد، نداریم.