BaseKit 0.3.0

BaseKit

مجموعه‌ای از Extension methodها، Attributeها و ابزارهای کمکی که برای استفاده‌ی مشترک بین پروژه‌های مختلف (از .NET Framework 4.6.1 تا .NET 10) ساخته شده. تمرکز اصلی روی نیازهای پروژه‌های فارسی/ایرانی (تاریخ شمسی، اعتبارسنجی کد ملی/موبایل/شبا، اعداد فارسی) به‌همراه ابزارهای عمومی (Guard clauses، Result pattern، صفحه‌بندی، کش ساده و ...).

نصب

dotnet add package BaseKit

Target frameworks: netstandard2.0 (سازگار با .NET Framework 4.6.1+ و .NET Core/5+) و net6.0 (برای قابلیت‌هایی مثل تشخیص nullable بودن reference typeها که فقط در .NET 6+ در دسترسن؛ پروژه‌های .NET 7 تا 10 هم به‌صورت خودکار از build مخصوص net6.0 استفاده می‌کنن).

فهرست

• String Extensions
• Numeric Extensions
• Date Extensions (تاریخ شمسی)
• Validation Extensions
• Fuzzy Matching (شباهت متن)
• Enum Extensions
• Collection Extensions
• Object / Reflection Extensions
• Exception Extensions
• Task Extensions
• File Extensions
• Debug / Logging Extensions
• IP Extensions
• Common: Money
• Common: Result<T>
• Common: PagedResult<T>
• Common: Validator (Fluent)
• Common: SimpleCache
• Guard Clauses
• Data Annotation Attributes
• Exceptions

String Extensions

"".IsEmpty();                          // true — null/خالی/فقط‌whitespace
"value".IsNotEmpty();                  // true

"1,234".ToInt();                       // 1234 (پشتیبانی از جداکننده‌ی کاما)
"1,234.5".ToDecimal();                 // 1234.5m
"1,234.5".ToDouble();                  // 1234.5
"123456789012".ToLong();               // 123456789012
"192.168.1.1".ToIp();                  // IPAddress
"https://example.com".ToUri();         // Uri (باید با http/https شروع بشه)
"1".ToBool();                          // true (1/0، true/false، yes/no، بله/خیر)

"123".ToPersianDigits();               // "۱۲۳"
"۱۲۳".ToEnglishDigits();                // "123" (فارسی و عربی هر دو پشتیبانی می‌شن)
"كتاب".NormalizeArabicChars();          // "کتاب" (ي/ك عربی → ی/ک فارسی)

"09123456789".Mask();                  // "0912***6789"
"یک متن طولانی است".Truncate(10);       // با حفظ کلمه‌ی کامل + "..."

Numeric Extensions

1234567.ToSeparatedString();           // "1,234,567"
1234567L.ToPersianCurrency();          // "۱,۲۳۴,۵۶۷ ریال"
1234567L.ToPersianWords();             // "یک میلیون و دویست و سی و چهار هزار و پانصد و شصت و هفت"
500m.ToMoney("IRR");                   // Money

Date Extensions (تاریخ شمسی)

DateTime.Now.ToShamsi();               // "1402/01/01"
DateTime.Now.ToClock();                // "13:05:09"
"1402/01/01".ToGregorian();            // DateTime
"1402/01/01".IsValidShamsiDate();      // true
"1402/02/01".IsGreaterThan("1402/01/01"); // مقایسه‌ی رشته‌ای تاریخ‌ها

// روزهای کاری (پنج‌شنبه + جمعه به‌عنوان تعطیل، قابل تنظیم)
DateTime.Today.IsWeekend();
DateTime.Today.NextWorkingDay();
DateTime.Today.AddWorkingDays(5);

Validation Extensions

"0499370899".IsValidNationalCode();     // اعتبارسنجی کد ملی با الگوریتم چک‌دیجیت
"09123456789".IsValidMobileNumber();    // شماره موبایل ایران
"test@example.com".IsValidEmail();
"DE89370400440532013000".IsValidIban(); // شبا/IBAN با الگوریتم استاندارد mod-97

Fuzzy Matching (شباهت متن)

"خراسان جنوبی".LevenshteinDistance("خوراسان جنوبی"); // 1
"خراسان جنوبی".SimilarityTo("خوراسان جنوبی");         // 0.923
"خراسان جنوبی".IsSimilarTo("خوراسان جنوبی", 0.8);      // true

var cities = new[] { "خراسان جنوبی", "خراسان رضوی", "تهران" };
cities.FindBestMatch("خوراسان جنوبی");                  // "خراسان جنوبی"
cities.FindSimilar("خوراسان جنوبی", threshold: 0.8);    // [("خراسان جنوبی", 0.923)]

Enum Extensions

MyEnum.Value.Humanize();               // از [Description] یا نام enum
MyEnum.Value.ToInt();
MyEnum.Value.GetAllNames();
MyEnum.Value.GetDetails(withAll: true); // List<EnumDetail> برای dropdown
"Value".ToEnum<MyEnum>();              // پارس امن با پیام خطای فارسی
2.ToEnum<MyEnum>();

Collection Extensions

list.IsEmpty();
list.ForEach(x => Console.WriteLine(x));
items.ChunkBy(3);                      // تقسیم به دسته‌های ۳تایی (هم‌نام با Chunk نت 6+ نیست، بدون تداخل)
items.DistinctByKey(x => x.Id);        // (هم‌نام با DistinctBy نت 6+ نیست)
items.Page(pageNumber: 2, pageSize: 20);
items.ToPagedResult(pageNumber: 2, pageSize: 20); // PagedResult<T> با TotalPages/HasNextPage/...
oldList.HasChanges(newList);

Object / Reflection Extensions

var clone = myObject.Clone();          // deep clone با JSON serialize/deserialize
var dict = myObject.ToDictionary();    // Dictionary<string, object?> از پراپرتی‌های public

Exception Extensions

exception.GetFullMessage();            // پیام کامل شامل همه‌ی InnerExceptionها

Task Extensions

await someTask.WithTimeout(TimeSpan.FromSeconds(5));   // TimeoutException در صورت تایم‌اوت

Func<Task<int>> operation = () => CallExternalServiceAsync();
await operation.RetryAsync(retryCount: 3, delay: TimeSpan.FromSeconds(1));

File Extensions

@"C:\logs\app".EnsureDirectoryExists();
"report:2024/06.pdf".GetSafeFileName(); // حذف کاراکترهای غیرمجاز

Debug / Logging Extensions

myObject.Dump();                       // JSON خوانا برای دیباگ سریع
myObject.ToJson();
json.FromJson<MyDto>();

IP Extensions

await IPAddress.Parse("8.8.8.8").Ping();

Common: Money

Value object برای مبلغ + واحد پول؛ از جمع/تفریق/مقایسه‌ی دو واحد پول متفاوت به‌صورت type-safe جلوگیری می‌کند.

var a = new Money(100_000, "IRR");
var b = new Money(50_000, "IRR");
var total = a + b;                     // Money(150000, "IRR")
a + new Money(10, "USD");              // InvalidOperationException

Common: Result<T>

جایگزین throw کردن exception برای مسیرهای خطای قابل‌پیش‌بینی.

Result<User> result = userId > 0
    ? Result<User>.Success(user)
    : Result<User>.Failure("کاربر یافت نشد");

if (result.IsSuccess) { /* result.Value */ }

Common: PagedResult<T>

PagedResult<Customer> page = customers.ToPagedResult(pageNumber: 2, pageSize: 20);
// page.Items, page.TotalCount, page.TotalPages, page.HasNextPage, page.HasPreviousPage

Common: Validator (Fluent)

بر خلاف Guard که در اولین خطا throw می‌کند، همه‌ی قوانین را چک کرده و لیست کامل خطاها را برمی‌گرداند — مناسب فرم‌هایی که باید همه‌ی خطاها را یک‌جا نشان دهند.

var result = Validator<UserDto>.For(dto)
    .Rule(x => x.Name.IsNotEmpty(), "نام الزامی است")
    .Rule(x => x.Mobile.IsValidMobileNumber(), "موبایل نامعتبر است")
    .Validate();

if (!result.IsValid) { /* result.Errors */ }

Common: SimpleCache

کش in-memory ساده با پشتیبانی از expiration؛ برای پروژه‌های کوچکی که نیازی به Redis/MemoryCache ندارند.

var cache = new SimpleCache<string, User>();
cache.Set("user:1", user, TimeSpan.FromMinutes(5));
cache.TryGet("user:1", out var cached);
cache.GetOrAdd("user:1", key => LoadUser(key), TimeSpan.FromMinutes(5));

Guard Clauses

public void Process(string name, int age)
{
    Guard.Against.Empty(name, nameof(name));
    Guard.Against.Negative(age, nameof(age));
    Guard.Against.OutOfRange(age, 0, 150, nameof(age));
    // ...
}

Data Annotation Attributes

public class RegisterDto
{
    [PersianRequired("نام")]
    public string Name { get; set; }

    [PersianMobileNumber]
    public string Mobile { get; set; }

    [PersianNationalCode]
    public string NationalCode { get; set; }

    [IranianIban]
    public string Sheba { get; set; }

    [GreaterThan(0, "سن")]
    public int Age { get; set; }

    [PersianRange(0, 100)]
    public int Score { get; set; }

    [DateRange(nameof(EndDate))]
    public DateTime StartDate { get; set; }
    public DateTime EndDate { get; set; }

    [RequiredIf(nameof(HasDiscount), true)]
    public decimal? DiscountAmount { get; set; }
    public bool HasDiscount { get; set; }

    [AllowedExtensions(".jpg", ".png")]
    [MaxFileSize(2 * 1024 * 1024)]
    public string AvatarFileName { get; set; }

    [CompareTo(nameof(ConfirmPassword), CompareType.Equal)]
    public string Password { get; set; }
    public string ConfirmPassword { get; set; }
}

همه‌ی این attributeها طبق pattern استاندارد ValidationAttribute کار می‌کنن (برگرداندن ValidationResult/bool، نه throw)، پس با Validator.TryValidateObject و کتابخانه‌های مبتنی بر DataAnnotations (ASP.NET Core model binding، EF Core و ...) سازگارن.

متادیتای غیر-اعتبارسنجی هم موجوده: [Note] (مستندسازی متد)، [DisplayOrder]، [AuditIgnore].

Exceptions

• AlertException — پیام قابل‌نمایش مستقیم به کاربر نهایی
• BadRequestException — معمولاً باید به HTTP 400 نگاشت بشه (برای خطاهای اعتبارسنجی ورودی در APIها)

ساختار مخزن

src/BaseKit/            کد اصلی کتابخانه
tests/BaseKit.Tests/    تست‌های واحد (xUnit، Theory-based)
nupkgs/                 خروجی pack شده (git-ignored)
local-feed/             فید لوکال NuGet برای تست مصرف پکیج (git-ignored)

Build & Pack

dotnet build
dotnet pack -c Release

خروجی .nupkg در پوشه‌ی nupkgs/ قرار می‌گیرد.