YS.TaskFramework 1.0.0

🚀 TaskFramework

TaskFramework, .NET uygulamaları için gelişmiş, esnek ve güçlü bir görev planlama kütüphanesidir. CRON ifadeleri kullanarak görevleri zamanlamanıza, programatik olarak görev eklemenize ve görev sonuçlarını takip etmenize olanak sağlar.

✨ Özellikler

🕐 Gelişmiş CRON Tabanlı Zamanlama

• Standart CRON (5 parça): * * * * * (dakika saat gün ay gün)
• Saniye Desteği (6 parça): * * * * * * (saniye dakika saat gün ay gün)
• Quartz Desteği: Ek CRON operatörleri (L, W, #, vb.)
• Hibrit Parser: Cronos + Quartz ile maksimum uyumluluk
• Zaman Dilimi Desteği: Türkiye saati, UTC ve diğer tüm zaman dilimleri
• Otomatik Format Algılama: 5/6 parça otomatik algılama

🔧 Görev Tanımlama Yöntemleri

• Attribute Tabanlı: [JobSchedule("*/5 * * * *")] ile sınıf üzerinde
• Programatik: AddTask<T>() ile sınıf tabanlı görevler
• Action/Lambda: AddTask(action, cron) ile anlık görevler

📊 Gelişmiş İzleme ve İstatistikler

• Görev İstatistikleri: Çalışma sayısı, başarı/hata oranları
• Performans Metrikleri: Çalışma süresi, son çalışma zamanı
• Gerçek Zamanlı Takip: Görev durumu ve sonraki çalışma zamanı

🔄 Retry Mekanizması

• Otomatik Yeniden Deneme: Başarısız görevler için
• Yapılandırılabilir: Deneme sayısı ve aralığı
• Akıllı Hata Yönetimi: Exception handling ve loglama

👂 Subscriber Sistemi

• Görev Tamamlanma Bildirimleri: Tüm görevler veya belirli görevler
• Otomatik Tarama: Assembly'lerde subscriber'ları bulma
• Manuel Kayıt: Programatik subscriber ekleme

🏗️ Modern .NET Mimarisi

• Dependency Injection: Microsoft.Extensions.DependencyInjection
• Hosted Service: BackgroundService tabanlı çalışma
• Logging: Microsoft.Extensions.Logging entegrasyonu
• .NET 9: En son .NET sürümü desteği

🚀 Hızlı Başlangıç

📦 NuGet Paketi Kurulumu

dotnet add package TaskFramework

🔧 Temel Kullanım

using TaskFramework.Extensions;
using TaskFramework.Abstractions;
using TaskFramework.Attributes;

// 1. Attribute ile görev tanımlama
[JobSchedule("*/30 * * * * *", includeSeconds: true)]
public class MyTask : IJober
{
    public Task Execute(CancellationToken cancellationToken)
    {
        Console.WriteLine("Görev çalışıyor!");
        return Task.CompletedTask;
    }
}

// 2. Programatik görev ekleme
services.AddJobScheduler(options =>
{
    // Sınıf tabanlı görev
    options.AddTask<MyTask>("*/1 * * * *");
    
    // Action tabanlı görev
    options.AddTask(async (serviceProvider, cancellationToken) =>
    {
        var logger = serviceProvider.GetRequiredService<ILogger<Program>>();
        logger.LogInformation("Action görevi çalışıyor!");
    }, "*/2 * * * *");
    
    // Saat dilimi ayarı
    options.TimeZone = TimeZoneInfo.FindSystemTimeZoneById("Turkey Standard Time");
    
    // Retry ayarları
    options.DefaultRetryCount = 3;
    options.RetryDelayMs = 2000;
});

📋 Gelişmiş CRON Format Desteği

🕐 Standart Format (5 Parça)

┌───────────── dakika (0 - 59)
│ ┌───────────── saat (0 - 23)
│ │ ┌───────────── gün (1 - 31)
│ │ │ ┌───────────── ay (1 - 12)
│ │ │ │ ┌───────────── haftanın günü (0 - 6) (Pazar = 0)
│ │ │ │ │
* * * * *

Temel Örnekler:

• */5 * * * * - Her 5 dakikada bir
• 0 2 * * * - Her gün saat 02:00'de
• 0 9 * * 1 - Her Pazartesi saat 09:00'da
• 30 14 * * 1-5 - Hafta içi her gün saat 14:30'da

⏱️ Saniye Desteği (6 Parça)

┌───────────── saniye (0 - 59)
│ ┌───────────── dakika (0 - 59)
│ │ ┌───────────── saat (0 - 23)
│ │ │ ┌───────────── gün (1 - 31)
│ │ │ │ ┌───────────── ay (1 - 12)
│ │ │ │ │ ┌───────────── haftanın günü (0 - 6)
│ │ │ │ │ │
* * * * * *

Saniye Örnekleri:

• */30 * * * * * - Her 30 saniyede bir
• 0 */2 * * * * - Her 2 dakikada bir (saniye 0'da)
• 15 0 * * * * - Her gün saat 00:00:15'te

🎯 7 Parça CRON Desteği (Quartz Formatı)

┌───────────── saniye (0 - 59)
│ ┌───────────── dakika (0 - 59)
│ │ ┌───────────── saat (0 - 23)
│ │ │ ┌───────────── gün (1 - 31)
│ │ │ │ ┌───────────── ay (1 - 12)
│ │ │ │ │ ┌───────────── haftanın günü (0 - 6)
│ │ │ │ │ │ ┌───────────── yıl (opsiyonel)
│ │ │ │ │ │ │
* * * ? * * *

7 Parça Örnekleri:

• * * * ? * * * - Her saniye
• */30 * * ? * * * - Her 30 saniyede bir
• 0 0 9 * * ? * - Her gün saat 09:00'da
• 0 0 * ? * MON-FRI * - Hafta içi her saat başı
• 0 0 0 L * ? * - Her ayın son günü

🔥 Gelişmiş Operatörler (Quartz Desteği)

Son Gün Operatörü (L)

• 0 0 L * * - Her ayın son günü
• 0 9 * * 5L - Her ayın son Cuma'sı

En Yakın İş Günü (W)

• 0 9 15W * * - 15. güne en yakın iş günü
• 0 9 1W * * - 1. güne en yakın iş günü

Belirli Hafta (#)

• 0 9 * * 1#2 - Her ayın 2. Pazartesi'si
• 0 9 * * 3#4 - Her ayın 4. Çarşamba'sı

Karmaşık Aralıklar

• 0 8-18 * * 1-5 - Hafta içi 08:00-18:00 arası her saat
• 0 0 1,15 * * - Her ayın 1. ve 15. günü
• 0 10 * * 6,7 - Hafta sonları 10:00'da

Gelişmiş Adım Operatörleri

• 0 */3 * * 1-5 - Hafta içi her 3 saatte bir
• 0 0 1 */3 * - Her 3 ayda bir
• 0 0 1 1,4,7,10 * - Her çeyrek yılın başında

🏗️ Mimari ve Bileşenler

📁 Proje Yapısı

TaskFramework/
├── Abstractions/          # Temel arayüzler
│   └── ITask.cs          # Görev arayüzü
├── Attributes/            # Dekoratif özellikler
│   └── TaskScheduleAttribute.cs
├── Extensions/            # DI genişletmeleri
│   └── ServiceCollectionExtensions.cs
├── Interfaces/            # Ek arayüzler
│   └── ITaskSubscriber.cs
├── Models/                # Veri modelleri
│   ├── TaskInfo.cs       # Görev bilgileri
│   └── TaskResult.cs     # Görev sonuçları
└── Services/              # Ana servisler
    ├── TaskSchedulerService.cs
    └── AdvancedCronParser.cs

🔄 Çalışma Prensibi

1. Başlatma: Assembly'lerde [JobSchedule] attribute'ları taranır
2. Planlama: CRON ifadeleri parse edilir ve sonraki çalışma zamanları hesaplanır
3. Çalıştırma: Zamanı gelen görevler paralel olarak çalıştırılır
4. İzleme: Sonuçlar kaydedilir ve subscriber'lara bildirilir
5. Yeniden Planlama: Bir sonraki çalışma zamanı hesaplanır

📊 Görev İzleme ve İstatistikler

📈 TaskInfo Modeli

public class TaskInfo
{
    public string Id { get; set; }
    public string Name { get; set; }
    public string CronExpression { get; set; }
    public bool IsActive { get; set; }
    public DateTime? LastRunTime { get; set; }
    public DateTime? NextRunTime { get; set; }
    public int ExecutionCount { get; set; }
    public int SuccessCount { get; set; }
    public int FailureCount { get; set; }
    public TaskResult? LastResult { get; set; }
}

📊 TaskResult Modeli

public class TaskResult
{
    public bool IsSuccess { get; set; }
    public string Message { get; set; }
    public object? Data { get; set; }
    public long ExecutionTimeMs { get; set; }
    public DateTime ExecutionTime { get; set; }
    public string? ErrorMessage { get; set; }
    public string? ErrorDetails { get; set; }
}

👂 Subscriber Sistemi

🔔 ITaskSubscriber Arayüzü

public interface ITaskSubscriber
{
    string Id { get; }
    string Name { get; }
    IEnumerable<string> TaskIds { get; } // Boş ise tüm görevleri dinler
    
    Task<bool> OnTaskCompletedAsync(string taskId, string taskName, TaskResult result);
}

📝 Subscriber Örneği

public class MySubscriber : ITaskSubscriber
{
    public string Id => "my-subscriber";
    public string Name => "My Task Subscriber";
    public IEnumerable<string> TaskIds => new string[] { }; // Tüm görevleri dinle
    
    public async Task<bool> OnTaskCompletedAsync(string taskId, string taskName, TaskResult result)
    {
        if (result.IsSuccess)
        {
            Console.WriteLine($"✅ {taskName} başarıyla tamamlandı!");
        }
        else
        {
            Console.WriteLine($"❌ {taskName} başarısız: {result.ErrorMessage}");
        }
        
        return true;
    }
}

⚙️ Yapılandırma Seçenekleri

🔧 TaskSchedulerOptions

services.AddJobScheduler(options =>
{
    // Saat dilimi
    options.TimeZone = TimeZoneInfo.FindSystemTimeZoneById("Turkey Standard Time");
    
    // Retry ayarları
    options.DefaultRetryCount = 3;
    options.RetryDelayMs = 2000;
    
    // Subscriber ayarları
    options.AutoScanSubscribers = true;
    
    // Manuel subscriber ekleme
    options.AddSubscriber(new MySubscriber());
    
    // Programatik görev ekleme
    options.AddTask<MyTask>("*/5 * * * *");
    options.AddTask(async (sp, ct) => 
    {
        // Görev kodu
    }, "*/10 * * * *");
});

🎯 Kullanım Senaryoları

📧 Email Gönderimi

[JobSchedule("0 9 * * 1-5")] // Hafta içi her gün saat 09:00'da
public class DailyEmailJob : IJober
{
    private readonly IEmailService _emailService;
    
    public DailyEmailJob(IEmailService emailService)
    {
        _emailService = emailService;
    }
    
    public async Task Execute(CancellationToken cancellationToken)
    {
        await _emailService.SendDailyReportAsync();
    }
}

💾 Veritabanı Yedekleme

[JobSchedule("0 2 * * *")] // Her gün saat 02:00'de
public class DatabaseBackupJob : IJober
{
    public async Task Execute(CancellationToken cancellationToken)
    {
        // Yedekleme işlemleri
        await BackupDatabaseAsync();
    }
}

📊 Rapor Oluşturma

services.AddJobScheduler(options =>
{
    options.AddTask(async (serviceProvider, cancellationToken) =>
    {
        var reportService = serviceProvider.GetRequiredService<IReportService>();
        var logger = serviceProvider.GetRequiredService<ILogger<Program>>();
        
        logger.LogInformation("Rapor oluşturuluyor...");
        await reportService.GenerateMonthlyReportAsync();
        logger.LogInformation("Rapor tamamlandı!");
    }, "0 1 1 * *"); // Her ayın 1'i saat 01:00'de
});

🧪 Test ve Debug

🔍 Görev Bilgilerini Görüntüleme

// JobSchedulerService'i inject edin
public class TaskController : ControllerBase
{
    private readonly JobSchedulerService _jobScheduler;
    
    [HttpGet("tasks")]
    public ActionResult<IEnumerable<TaskInfo>> GetAllTasks()
    {
        return Ok(_jobScheduler.GetAllTaskInfos());
    }
    
    [HttpGet("tasks/{taskId}")]
    public ActionResult<TaskInfo> GetTask(string taskId)
    {
        var task = _jobScheduler.GetTaskInfo(taskId);
        if (task == null) return NotFound();
        return Ok(task);
    }
}

📝 Loglama

services.AddJobScheduler(options =>
{
    // Loglama zaten otomatik olarak yapılır
    // ILogger kullanarak görevlerinizde log yazabilirsiniz
});

🚀 Performans ve Ölçeklenebilirlik

⚡ Performans Özellikleri

• Asenkron Çalışma: Görevler ana thread'i bloklamaz
• Paralel İşleme: Birden fazla görev aynı anda çalışabilir
• Hafıza Optimizasyonu: Minimal memory footprint
• Hızlı CRON Parsing: Cronos kütüphanesi ile optimize edilmiş

📈 Ölçeklenebilirlik

• Mikroservis Uyumlu: Her servis kendi görevlerini yönetebilir
• Distributed Çalışma: Birden fazla instance'da çalışabilir
• Load Balancing: Görevler farklı sunucularda dağıtılabilir

🔒 Güvenlik ve Hata Yönetimi

🛡️ Güvenlik Özellikleri

• Exception Handling: Görev hataları yakalanır ve loglanır
• Cancellation Token: Görevler güvenli şekilde iptal edilebilir
• Resource Management: Memory leak'leri önlenir

❌ Hata Yönetimi

public async Task Execute(CancellationToken cancellationToken)
{
    try
    {
        // Görev kodu
        await DoSomethingAsync();
    }
    catch (Exception ex)
    {
        // Hata loglanır ve TaskResult'a kaydedilir
        throw; // Framework otomatik olarak yakalar
    }
}

📚 Örnek Projeler

Bu repository'de 3 farklı örnek proje bulunmaktadır:

🖥️ ConsoleApp

• Temel kullanım örnekleri
• Attribute ve programatik görev tanımlama
• Subscriber sistemi

🖼️ WinFormsApp

• Windows Forms entegrasyonu
• UI thread güvenliği
• Gerçek zamanlı görev izleme

🌐 WebApi

• REST API entegrasyonu
• Görev istatistikleri endpoint'leri
• Swagger dokümantasyonu

🤝 Katkıda Bulunma

🔧 Geliştirme Ortamı Kurulumu

# Repository'yi klonlayın
git clone https://github.com/yourusername/TaskFramework.git

# Projeyi açın
cd TaskFramework

# Bağımlılıkları yükleyin
dotnet restore

# Projeyi build edin
dotnet build

# Testleri çalıştırın
dotnet test

📝 Kod Standartları

• C# Coding Conventions: Microsoft C# coding conventions
• XML Documentation: Tüm public API'lar için XML docs
• Error Handling: Proper exception handling
• Logging: Structured logging with ILogger

📄 Lisans

Bu proje MIT lisansı altında lisanslanmıştır. Detaylar için LICENSE dosyasına bakın.

📞 İletişim

• GitHub Issues: GitHub Issues
• Email: your.email@example.com
• Discord: Discord Server

🙏 Teşekkürler

• Cronos: CRON parsing için
• Microsoft: .NET platformu için
• Community: Geri bildirim ve öneriler için

TaskFramework ile görevlerinizi kolayca planlayın, izleyin ve yönetin! 🎯✨