VeloxMapper 5.1.0

VeloxMapper

VeloxMapper, modern .NET platformları (.NET 8.0, .NET 9.0 ve .NET 10.0) için tasarlanmış; performans, tip güvenliği ve gözlemlenebilirliği (observability) önceliklendiren, deterministik ve fail-fast (erken hata) tabanlı hibrit bir nesne eşleştirme (object mapping) kütüphanesidir.

🎯 Mottolarımız & Temel Hedefimiz

• Minimum Efor, Sıfır Zahmet: .NET projelerinde geliştiricilerin en az eforla AutoMapper'dan VeloxMapper'a geçmesini sağlamak.
• Kusursuz Geliştirici Deneyimi: Sürpriz çalışma zamanı hatalarına son veren, başlangıçta (startup) doğrulanan ve yüksek performanslı eşleştirme deneyimi.

🚀 1. Proje Tanıtımı

Hangi Problemi Çözer?

Geleneksel nesne eşleştiriciler (Object Mappers), çalışma zamanındaki belirsiz davranışları ve konfigürasyon hatalarını ancak ilgili kod satırı çalıştığında (genellikle üretim ortamında bir kullanıcı isteği sırasında) fırlatır. Bu durum, gözden kaçan eksik eşleşmelerin production hatalarına dönüşmesine yol açar. Ayrıca yoğun reflection kullanımı yüksek bellek tüketimi (allocation) ve JIT derleme yükü oluşturur.

VeloxMapper bu sorunları üç temel sütunla çözer:

1. Deterministik ve Fail-Fast: Tüm eşleştirme kuralları uygulama başlangıcında doğrulanır. Eşleşmeyen tek bir property bile varsa uygulama başlamaz.
2. Hibrit Çift Katmanlı Motor: Statik kod üretimi (Source Generator) ile çalışma zamanı (Expression Tree) fall-back mekanizmasını birleştirir.
3. Gözlemlenebilirlik (Observability): Eşleştirme planlarını JSON veya metin tabanlı raporlara dönüştürerek CI/CD süreçlerinde şema değişikliklerini SHA-256 hash'leri ile doğrulamanızı sağlar.

AutoMapper'dan Temel Farkları

📦 2. Kurulum (Installation)

Geliştirici kafa karışıklığını önlemek adına VeloxMapper.Core ve VeloxMapper tek bir NuGet paketinde birleştirilmiştir. Yalnızca VeloxMapper paketini kurmanız yeterlidir.

NuGet CLI ile Kurulum

dotnet add package VeloxMapper

Paket Yöneticisi Konsolu

Install-Package VeloxMapper

⚡ 3. Hızlı Başlangıç (Quick Start)

VeloxMapper'ı en basit haliyle kullanmak için bir konfigürasyon oluşturup doğrulamak ve Mapper sınıfını başlatmak yeterlidir.

Adım 1: Sınıfları Tanımlayın

public class UserSource
{
    public string Name { get; set; } = "";
    public int Age { get; set; }
}

public class UserDest
{
    public string Name { get; set; } = "";
    public int Age { get; set; }
}

Adım 2: Yapılandırın ve Haritalayın

using VeloxMapper;
using VeloxMapper.Configuration;

// 1. Konfigürasyonu tanımlayın
var config = new MapperConfiguration(cfg =>
{
    cfg.CreateMap<UserSource, UserDest>();
});

// 2. Konfigürasyon kurallarını başlangıçta doğrulayın (Önemli!)
config.AssertConfigurationIsValid();

// 3. Mapper örneğini oluşturun
var mapper = new Mapper(config);

// 4. Eşleştirmeyi gerçekleştirin
var source = new UserSource { Name = "Deniz", Age = 30 };
UserDest result = mapper.Map<UserSource, UserDest>(source);

Console.WriteLine($"{result.Name} ({result.Age})"); // Çıktı: Deniz (30)

🧩 4. Temel Kavramlar

Mapper (IVeloxMapper)

Eşleştirme işlemlerini yürüten ana thread-safe bileşendir. Uygulama yaşam döngüsü boyunca Singleton olarak kaydedilmesi önerilir. İçerisinde önbelleğe alınmış delege ve expression yapılarını barındırır.

Configuration (MapperConfiguration) & Profil Yapısı (VeloxProfile)

Haritalama kurallarının kaydedildiği yerdir. Büyük projelerde kuralları modüler parçalara ayırmak için VeloxProfile sınıfı kullanılır:

public class PaymentProfile : VeloxProfile
{
    public PaymentProfile()
    {
        CreateMap<PaymentSource, PaymentDest>();
    }
}

Convention (Otomatik Eşleşme) vs Explicit Mapping (Açık Kurallar)

• Otomatik Eşleşme: Kaynak ve hedef sınıf özellik isimleri (case-insensitive) birebir eşleşiyorsa ek kural yazılmasına gerek yoktur.
• Açık Kurallar: İsimleri veya tipleri uyuşmayan alanlar .ForMember() veya .ConvertUsing() gibi metotlarla açıkça konfigüre edilir. Startup doğrulaması, kuralı yazılmamış tüm uyuşmazlıkları raporlar.

🛡️ 5. Proxy ve Null Propagation Yetenekleri (v5.1.0+ Yenilikleri)

Özellikle ORM (Entity Framework Core veya NHibernate) kullanılan projelerde AutoMapper'dan geçişi tamamen sorunsuz hale getirmek amacıyla iki önemli özellik çekirdek motora dahil edilmiştir:

A. Otomatik Proxy Çözümleme (Proxy Unwrapping)

Entity Framework Core ve NHibernate, ilişkili verileri (Navigation Properties) gecikmeli yüklemek (Lazy Loading) için çalışma zamanında dinamik proxy alt sınıfları üretir (örneğin Castle DynamicProxy). Bu tipler doğrudan eşleştirilmek istendiğinde, kütüphane bu isimsiz proxy sınıfları için eşleme kuralı bulamayarak hata verir.

VeloxMapper v5.1.0, çalışma zamanında gelen kaynak nesnelerin tiplerini analiz eder:

• Castle.Proxies. veya System.Data.Entity.DynamicProxies gibi dynamic proxy namespace ve kalıplarını otomatik algılar.
• Proxy sınıfını sarmalayan gerçek ata sınıfı (POCO entity) dinamik olarak tespit eder.
• Haritalama kurallarını ve derlenmiş delegeleri doğrudan bu ata sınıf üzerinden çalıştırarak eşleşme hatalarını tamamen ortadan kaldırır.

B. Otomatik Null Güvenliği (Automatic Null Propagation)

Derin nesne grafiklerinde (zincirleme üye erişimlerinde) ara nesnelerin null gelmesi durumunda NullReferenceException (NRE) oluşmasını engeller. Örneğin:

CreateMap<User, UserDto>()
    .ForMember(d => d.City, opt => opt.MapFrom(s => s.Address.City));

Eğer s.Address null ise, normal expression derleyicileri s.Address.City ifadesini çalıştırırken NRE fırlatır. AutoMapper ise bunu otomatik olarak null-safe hale getirir.

VeloxMapper v5.1.0 expression motoru, tüm üye erişim yollarını analiz ederek otomatik olarak null-propagation ifadeleri üretir:

• Referans Tiplerinde: s.Address == null ? null : s.Address.City
• Değer Tiplerinde: s.Address == null ? 0 : s.Address.ZipCode (default değer otomatik atanır)
• Nullable Değer Tiplerinde: s.Address == null ? null : s.Address.ExtraCode
• Karmaşık Alt Nesnelerde: Eğer s.Address null ise, AddressDto hedefine yeni nesne oluşturulup boş atılması yerine doğrudan null set edilir.

🌐 6. AutoMapper API Uyumluluğu (Null ve Koleksiyon Yönetimi)

VeloxMapper, AutoMapper'dan geçiş yapan geliştiricilerin kodlarında hiçbir değişiklik yapmaması için varsayılan olarak şu API davranışlarını sergiler:

• Null Kaynak Yönetimi: Eşleme yapılacak kaynak (source) nesnesi null olduğunda, ArgumentNullException fırlatılmaz. Bunun yerine:
  • Hedef tip bir koleksiyon ise (List, Array, HashSet vb.) ve AllowNullCollections ayarı false (varsayılan) ise boş bir koleksiyon örneği döner.
  • Hedef tip normal bir referans tipi ise null döner.
  • Hedef tip bir değer tipi ise default(TDestination) (örneğin int için 0) döner.
• Koleksiyon Eşleme Tipi Uyumlaması: _mapper.Map<List<CategoryDto>>(cate) çağrılarında, AutoMapper'da olduğu gibi doğrudan List<CategoryDto> döner. Herhangi bir tip çakışması veya List<List<CategoryDto>> gibi hatalı çift katmanlı koleksiyon yapılarının oluşması engellenmiştir.

🛠️ 7. İleri Düzey Mapping Senaryoları (Faz 4 Özellikleri)

VeloxMapper ile birlikte AutoMapper uyumluluğunu en üst düzeye çıkaran ileri düzey yapılandırma API'leri sunulmaktadır:

A. UseDestinationValue() — Mevcut Değerleri Koruma ve Koleksiyon Birleştirme

Eşleme sırasında hedef nesnedeki mevcut referansların (özellikle nested class nesneleri veya generic koleksiyonlar) ezilmesini önler ve üzerine patch/update işlemi uygular.

• Koleksiyonlarda: Hedef koleksiyon referansı korunur, içi Clear() edilip kaynak elemanlar tek tek Add() yöntemiyle eklenir.
• Sınıflarda (Nested): Hedef nesnenin referansı korunur ve Mapper.Map(source, destination, context) metodu ile patch uygulanır.

CreateMap<UseDestValueSrc, UseDestValueDest>()
    .ForMember(dest => dest.Nested, opt => opt.UseDestinationValue())
    .ForMember(dest => dest.Ints, opt => opt.UseDestinationValue());

B. As<TDestinationRedirect>() — Hedef Yönlendirme Desteği

Eşleştirme sonucunu farklı bir türetilmiş hedef tipe yönlendirmek amacıyla kullanılır. AutoMapper'ın .As<T>() API'siyle birebir uyumludur.

CreateMap<AsSource, BaseDest>()
    .As<DerivedDest>(); // AsSource map edildiğinde çıktı aslında DerivedDest olacaktır

C. SetMappingOrder() — Özellik Eşleme Sırasını Belirleme

Özelliklerin (properties) atanma sırasını belirleme imkanı sağlar. Sıralı atama veya birbirine bağımlı property setter kuralları için idealdir.

CreateMap<OrderSource, OrderDest>()
    .ForMember(dest => dest.Prop1, opt => {
        opt.MapFrom(src => src.Prop1);
        opt.SetMappingOrder(2); // En son atama yapılır
    })
    .ForMember(dest => dest.Prop2, opt => {
        opt.MapFrom(src => src.Prop2);
        opt.SetMappingOrder(1); // İlk atama yapılır
    });

D. IncludeAllDerived() — Polimorfik Haritalama Kolaylığı

Temel sınıf seviyesinde eşleme tanımlandığında, tanımlanmış tüm derived (alt) sınıf haritalamalarını otomatik olarak polimorfik eşleştirmeye dahil eder.

CreateMap<Animal, AnimalDto>()
   .IncludeAllDerived(); // Dog -> DogDto vb. tüm alt sınıf eşleşmelerini otomatik polimorfik yapar

E. Açık Generic (Open Generics) Haritalama

Açık generic sınıfların haritalanması için dinamik çalışma zamanı desteği sunar.

cfg.CreateMap(typeof(GenericSrc<>), typeof(GenericDest<>));

F. ConvertUsing(Func<TSource, TDestination>) Lambda Overload Desteği

Basit tür dönüşümleri veya özel eşleme kurallarını tek satırlık lambda ifadeleriyle tanımlamanızı sağlar.

CreateMap<TransformerSrc, TransformerDest>()
   .ConvertUsing(src => new TransformerDest 
   { 
       Text = src != null ? src.Text + " (Lambda)" : "",
       Value = src != null ? src.Value + 100 : 0
   });

⚡ 8. Gelişmiş Kullanım ve Performans Optimizasyonları

VeloxMapper'ı benzersiz kılan, derleme zamanı ile çalışma zamanını birleştiren hibrit yapısıdır.

graph TD
    A[Haritalama Talebi: Map] --> B{Precompiled Registry'de delege var mı?}
    B -- Evet (Layer 1 - AOT) --> C[Statik / Precompiled metodu doğrudan çağır]
    B -- Hayır --> D{Cache'te compiled delege var mı?}
    D -- Evet (Layer 2 - JIT) --> E[Önbellekteki strongly-typed delegeyi çalıştır]
    D -- Hayır --> F[Expression Tree oluştur, JIT derle, Cache'e ekle ve çalıştır]

Layer 1: Source Generator ([VeloxMap])

Sınıflarınızı [VeloxMap] özniteliğiyle işaretlediğinizde, Roslyn derleyicisi derleme zamanında NativeAOT uyumlu, reflection içermeyen, allocation-free uzantı metotları (extension methods) üretir. Base class'lardan kalıtılan tüm property'ler de rekürsif olarak taranarak kod üretimine dahil edilir.

using VeloxMapper.Attributes;

[VeloxMap(typeof(User), typeof(UserDto))]
public class User { public string Name { get; set; } = ""; }

Kullanımı:

using VeloxMapper.Generated; // Metotların görünmesi için zorunlu!

var dto = user.MapToMyProjectDtosUserDto(); // Sıfır reflection, en yüksek hız.

Layer 2: RequiresContext Bağımlılık ve Context Optimizasyonu

Çalışma zamanında üretilen dinamik delege motoru, gereksiz bellek tahsisini (allocation) önlemek için optimize edilmiştir:

• Bağımlılık Grafiği Çözümleme (OptimizeRequiresContext): MapperConfiguration derlenirken, dairesel referans korumalı DFS algoritması ile tüm kayıtlar taranır. Eğer alt nesnelerde veya eşleme kurallarında BeforeMap, AfterMap, MaxDepth, PreserveReferences ya da karmaşık MapFrom ifadeleri bulunmuyorsa, haritalama işlemi simpleFunc (sıfır-context, sıfır-allocation) olarak derlenir.
• IsSimplePropertyAccess Analizi: ForMember içerisindeki MapFrom ifadeleri analiz edilir. Sadece basit property erişimleri (örn. s => s.Address.City) context gerektirmezken, özel mantık içerenler hata sarmalama ve CurrentMember konum tespiti amacıyla context gerektirir olarak işaretlenir.
• Context Pooling ve Gecikmeli Yükleme: ThreadStatic bir havuz yapısı kullanılarak reentrancy-safe (iç içe çağrılara güvenli) bir context yönetimi sağlanır. Context sıfırlanırken (Reset), sadece içi dolu olan nesneler temizlenerek CPU döngüleri korunur.

🤖 9. AutoMapper'dan VeloxMapper'a Geçiş AI Promptu

Projelerinizdeki mevcut AutoMapper yapılandırmalarını (Profiles, Custom Resolvers vb.) en az eforla ve tamamen otomatik olarak VeloxMapper API'sine dönüştürmek için aşağıdaki AI promptunu ChatGPT, Claude veya GitHub Copilot gibi araçlara verebilirsiniz:

Aşağıda verilen AutoMapper kodunu VeloxMapper (v5.1.0+) API'sine dönüştür. Dönüşüm sırasında şu kurallara kesinlikle uymalısın:

1. `Profile` sınıfı yerine `VeloxProfile` miras alınmalıdır.
2. `_mapper.Map<List<Dest>>(sources)` ve `_mapper.Map<Dest>(source)` kullanımları VeloxMapper'da da birebir aynıdır, değiştirme.
3. `.ForMember(dest => dest.Foo, opt => opt.MapFrom(src => src.Bar))` ve `.ForMember(dest => dest.Foo, opt => opt.Ignore())` kuralları VeloxMapper'da da aynıdır, değiştirme.
4. AutoMapper'daki `opt.Condition(src => src.IsActive)` ifadesini VeloxMapper'ın 3 parametreli condition yapısına dönüştür: `opt.Condition((src, dest, val) => src.IsActive)` veya `opt.Condition((src, dest, val) => val != null)`.
5. AutoMapper'daki `.UseDestinationValue()` çağrısını VeloxMapper'daki `.ForMember(dest => dest.Prop, opt => opt.UseDestinationValue())` formatına uyarla.
6. AutoMapper'daki `.IncludeAllDerived()` çağrısını VeloxMapper'daki karşılığı olan `.IncludeAllDerived()` şeklinde koru.
7. AutoMapper'daki `.As<T>()` çağrılarını VeloxMapper'daki `.As<T>()` şeklinde koru.
8. AutoMapper'daki `.ConstructUsing(src => ...)` ve `.ConvertUsing(src => ...)` metotlarını VeloxMapper'daki lambda overload karşılıklarına dönüştür.
9. VeloxMapper v5.1.0+ ile gelen otomatik Proxy Unwrapping ve otomatik Null Propagation (üye erişimlerinde null kontrolleri) kütüphane motoru düzeyinde otomatik yapıldığından, kodda ek null kontrolü veya proxy çözme (EF/DynamicProxy için) ekleme, bunları çekirdek motor kendi halledecektir.
10. XML summary açıklamalarını ve koda eklenmiş Türkçe yorum satırlarını aynen koru.

[AutoMapper Kodunu Buraya Yapıştırın]

📄 Lisans

Bu proje MIT Lisansı altında yayınlanmıştır. Ticari ve kurumsal projelerde ücretsiz olarak güvenle kullanılabilir.