‫مدیریت قطعی زمان در NET.: چرا باید استفاده از DateTime.UtcNow را ممنوع کنیم؟

public bool IsTokenExpired(DateTime issuedAt, TimeSpan validity) 
{ 
    return DateTime.UtcNow > issuedAt + validity; 
}

• وابستگی به زمان واقعی: ساخت توکنی که ۱۵ دقیقه قبل صادر شده و انتظار برای گذر زمان واقعی در محیط تست (ایجاد تست‌های شکننده یا Flaky Tests).
• استفاده از Delegateها: تزریق یک پارامتر به صورت Func و پاس دادن () => DateTime.UtcNow در محیط عملیات (یک راه‌حل موقت و غیراستاندارد).
• ساخت اینترفیس‌های شخصی: ایجاد اینترفیسی مانند IClock یا ISystemClock (اختراع دوباره چرخ در هر پروژه).
• رها کردن تست: عدم نوشتن تست و امید به عملکرد صحیح در محیط Production (رایج‌ترین و خطرناک‌ترین رویکرد).

public interface IClock 
{ 
    DateTime UtcNow { get; } 
}

public abstract class TimeProvider 
{ 
    public static TimeProvider System { get; } 
 
    public virtual DateTimeOffset GetUtcNow(); 
    public virtual DateTimeOffset GetLocalNow(); 
    public virtual TimeZoneInfo LocalTimeZone { get; } 
    public virtual long GetTimestamp(); 
    public virtual long TimestampFrequency { get; } 
    public virtual ITimer CreateTimer(TimerCallback callback, object? state, TimeSpan dueTime, TimeSpan period); 
}

نکته برای پروژه‌های قدیمی‌تر: کلاس TimeProvider به صورت بومی از .NET 8 در دسترس است. با این حال، اگر پروژه‌ای روی .NET 6 یا .NET 7 دارید، نیازی به بازنویسی ساختار ندارید؛ می‌توانید با نصب پکیج NuGet رسمی Microsoft.Bcl.TimeProvider دقیقاً از همین قابلیت‌ها بهره‌مند شوید.

public class TokenValidator 
{ 
    private readonly TimeProvider _time; 
 
    public TokenValidator(TimeProvider time) 
    { 
        _time = time; 
    } 
 
    public bool IsTokenExpired(DateTimeOffset issuedAt, TimeSpan validity) 
    { 
        return _time.GetUtcNow() > issuedAt + validity; 
    } 
}

services.AddSingleton(TimeProvider.System);

var fakeTime = new FakeTimeProvider(); 
fakeTime.SetUtcNow(new DateTimeOffset(2026, 6, 9, 12, 0, 0, TimeSpan.Zero)); 
 
var validator = new TokenValidator(fakeTime); 
var issuedAt = fakeTime.GetUtcNow().AddMinutes(-16); 
 
// به طور قطعی مشخص است که توکن منقضی شده است
Assert.True(validator.IsTokenExpired(issuedAt, TimeSpan.FromMinutes(15)));

fakeTime.Advance(TimeSpan.FromMinutes(30));

public async Task RetryAsync(Func<Task> operation, TimeProvider time) 
{ 
    for (int attempt = 0; attempt < 3; attempt++) 
    { 
        try 
        { 
            await operation(); 
            return; 
        } 
        catch 
        { 
            var delay = TimeSpan.FromSeconds(Math.Pow(2, attempt)); 
            // ایجاد توکن لغو مبتنی بر زمان از طریق واگذاری به سرویس ارائه‌دهنده زمان
            await Task.Delay(delay, time.CreateCancellationTokenSource(delay).Token); 
        } 
    } 
}

var fakeTime = new FakeTimeProvider(); 
var retryTask = RetryAsync(failingOperation, fakeTime); 
 
fakeTime.Advance(TimeSpan.FromSeconds(1));  // شبیه‌سازی و تحریک تلاش مجدد اول 
fakeTime.Advance(TimeSpan.FromSeconds(2));  // شبیه‌سازی و تحریک تلاش مجدد دوم 
fakeTime.Advance(TimeSpan.FromSeconds(4));  // شبیه‌سازی و تحریک تلاش مجدد سوم 
 
await retryTask;

T:System.DateTime;استفاده مستقیم از ساختار زمان به دلیل ایجاد وابستگی مخفی ممنوع است. از TimeProvider استفاده کنید.
P:System.DateTime.UtcNow;دسترسی مستقیم به ساعت جهانی ممنوع است. لطفاً TimeProvider را تزریق کنید.
P:System.DateTime.Now;دسترسی مستقیم به ساعت محلی ممنوع است. لطفاً TimeProvider را تزریق کنید.
P:System.DateTimeOffset.UtcNow;دسترسی مستقیم به ساعت جهانی ممنوع است. لطفاً TimeProvider را تزریق کنید.
P:System.DateTimeOffset.Now;دسترسی مستقیم به ساعت محلی ممنوع است. لطفاً TimeProvider را تزریق کنید.
T:Microsoft.AspNetCore.Authentication.ISystemClock;این اینترفیس قدیمی و منسوخ شده است. به جای آن از TimeProvider استفاده کنید.
T:Microsoft.Extensions.Internal.ISystemClock;این اینترفیس قدیمی و منسوخ شده است. به جای آن از TimeProvider استفاده کنید.

<ItemGroup>
  <PackageReference Include="Microsoft.CodeAnalysis.BannedApiAnalyzers" Version="3.3.4" PrivateAssets="all" IncludeAssets="runtime; build; native; contentfiles; analyzers; buildtransitive" />
</ItemGroup>

<ItemGroup>
  <AdditionalFiles Include="$(MSBuildThisFileDirectory)BannedSymbols.txt" Link="Properties/BannedSymbols.txt" />
</ItemGroup>

public static class TimeContext 
{ 
    [ThreadStatic] 
    private static TimeProvider? _current; 
 
    public static TimeProvider Current 
    { 
        get => _current ?? TimeProvider.System; 
        set => _current = value; 
    } 
}