DSO.Core.Evoker

Aile

Evoker çekirdeği tek başına kullanılabilir; ihtiyaç büyüdükçe aile paketleri aynı kurallar üzerine katman ekler.

Neden Evoker?

Çalışma zamanında "isimle bir şey yapmak" için yaygın yaklaşımların her biri bir bedel ödetir:

Sıradan kütüphanelerin genelde düşünmediği şeyler

• Instance-güvenli cache. Derlenmiş delegate'ler instance'ı içinde taşımaz. Aynı tip + metot için farklı nesnelerle çalışan iki builder birbirinin sonucunu asla ezemez.
• Akıllı overload seçimi. Önce birebir ad, sonra büyük/küçük harf duyarsız ad (VB.NET dostu); ardından argüman sayısı, optional parametreler ve tip uyumu. JSON komutlarda ayrıca sayısal tercih (int → long → …) ve params desteği.
• Unload dostu. Her cache'in bir "unut" kapısı var (ForgetType, ForgetAssembly); collectible AssemblyLoadContext'ler gerçekten bellekten atılabilir.
• JSON-native. Herhangi bir sınıf, değişiklik yapmadan JSON komutlarla kullanılabilir. Tanım (describe) ve hazır komut şablonları otomatik üretilir.

Rakamlar

Ölçümler TestKit içindeki PerfBench ile .NET 8, Release derlemesinde alındı. Mutlak değerler makineye göre değişir; oranlar belirleyicidir.

* Çağıranın oluşturduğu object[] dizisi.

Kurulum

Depoyu klonlayıp projenize referans olarak ekleyin:

60 saniyede Evoker

Dört temel yeteneğin her biri tek bir örnekte:

API Rehberi

Bu bölüm her sınıfın public yüzeyini örnekleriyle listeler; kütüphaneyi kullanırken başvuru kaynağı olarak kullanabilirsiniz.

Tek satırlık çağrılar ve isimden tip çözme için.

ResolveType arama sırası

Bir seviyede birden fazla farklı tip eşleşirse (ör. iki plugin'de de Result sınıfı varsa) Evoker tahmin etmez: AmbiguousMatchException ile adayları listeler. Kısmen yüklenebilen assembly'ler (ReflectionTypeLoadException) aramayı düşürmez.

Esnek, genel amaçlı çağırma motoru. object[] argümanlarla çalışır; sıkı döngüler için tipli delegate'ler sunar.

Oluşturma ve instance modu

Çağırma

Metot seçme kuralları (FindMethod)

1. İsim önce birebir aranır, bulunamazsa büyük/küçük harf duyarsız aranır (VB.NET'te add ile Add aynıdır).
2. Parametre sayısı argüman sayısına eşit olan adaylar önceliklidir. Yoksa fazlalık parametrelerinin hepsi optional olan adaylar kullanılır; eksikler metodun kendi varsayılan değerleriyle dolar (C# = değer, VB.NET Optional).
3. Birden fazla aday kalırsa argüman tiplerine bakılır: önce birebir tip, sonra atanabilir tip.
4. Uygun aday yoksa MissingMethodException fırlatılır; mesajda mevcut imzalar listelenir.

Aynı kuralları dışarıdan da kullanabilirsiniz:

Constructor seçimi

Constructor'lar metotlarla aynı kurallarla seçilir: sayı, optional, tip uyumu, sayısal genişletme (ör. int parametreye long). Değerler gerekirse EvokerValueConverter ile dönüştürülür. Tüm parametreleri optional olan bir constructor "parametresiz" sayılır.

Önceden çözülmüş delegate'ler (object[] tabanlı)

Tipli delegate'ler — boxing yok, allocation yok

Sıkı döngüler için en hızlı yol: argüman ve dönüş tipleri derleme zamanında bilinir. Son tip parametresi, .NET'in Func<> kuralındaki gibi dönüş tipidir.

• Overload, T1..Tn tiplerine göre seçilir.
• Tip metodun parametresinden farklıysa (int → long, türetilmiş → taban) dönüşüm derlenir; mümkün değilse InvalidCastException fırlatılır.
• Verilmeyen optional parametreler varsayılanla dolar.
• SetInstance verilmişse nesne delegate'e bağlanır; verilmemişse her çağrıda çözülür.
• Sıfır argümanlı tipli sürüm bilerek yoktur; argümansız metotlarda GetFunc<T>(ad) zaten boxing yapmaz.

Property ve field erişimi EvokerBuilderPropertyExtensions

Event'ler EvokerBuilderEventExtensions

Derleme zamanında delegate tipini bilmeden herhangi bir event'e abone olun. EventHandler, EventHandler<T>, özel delegate'ler ve VB.NET'in ürettiği gizli delegate'lerin hepsi desteklenir.

Static event'ler de desteklenir. Instance event'leri için builder'ın SetInstance ile bağlı olması gerekir.

Cache yönetimi

ORM satır okuma döngüsü gibi sıcak yollar için. Bilinen bir property, bilinen bir tiple, boxing olmadan okunur ve yazılır.

• Property yoksa aynı isimli field'a düşer.
• includeNonPublic: true ile private/protected/internal üyeler de görülür.
• Cache anahtarı struct'tır; cache isabetinde bile string üretilmez.

Gerçek CLR tipleri üretir. Tüm tipler tek, paylaşımlı bir modülde üretilir ve aynı şema ikinci kez istendiğinde IL yeniden üretilmez.

Genişletme parametreleri

Çekirdek bunlara ihtiyaç duymaz; Extend paketi kullanır.

configureType verildiğinde şema cache'i bilinçli olarak devre dışı kalır: aynı şema farklı yapılandırmalarla farklı tipler üretebilir. TypeMembers yapısı emisyonu biten property, metot, generic metot ve event builder'larını verir. InvokeGenericMethodDelegate generic forwarder'ların çağırdığı public yardımcıdır.

Func<>/Action<>'ın ifade edemediği imzalar için (ref/out parametreler, 16'dan fazla parametre) gerçek bir delegate tipi üretir. Aynı imza tekrar istenirse aynı tip döner.

DynamicTypeFactory + DynamicEntityAccessor + EvokerBuilder üçlüsünü tek bir akıcı (fluent) nesnede toplar. Thread-safe build sunar: aynı tanım birden fazla thread'den kurulsa bile tip ve instance yalnızca bir kez üretilir.

Oluşturma

Property'ler ve değerler

Değişiklik kancaları (instance'a özel)

Metotlar

Metot gövdesi bir delegate'tir; istediğiniz an değiştirebilirsiniz.

Generic metotlar (type-erasure)

Event'ler

Gerçek C# += söz dizimiyle abone olmak için tipi bir interface'e bağlayın: Extend → Implement<T>.

Attribute ekleme

Yaşam döngüsü ve genişletme

Herhangi bir sınıfı kodunda hiçbir değişiklik yapmadan JSON ile kullanılabilir hale getirir. Aynı komut biçimi her yerde çalışır: bir tipte (EvokerTarget), bir plugin'de (PluginTarget, sandbox worker'ın içinde bile) ve web üzerinden (DSO.Core.Evoker.Api).

Komut biçimi

Alan adları büyük/küçük harf duyarsızdır. op verilmezse invoke kabul edilir.

Argüman bağlama kuralları

• Sıralı: argüman sayısı ≤ parametre sayısı olmalı; kalan parametreler optional olmalı.
• İsimli: her ad bir parametreye karşılık gelmeli; verilmeyen parametreler optional olmalı.
• Tek parametreli metot: isimli nesne hiçbir adayla eşleşmezse, nesnenin kendisi o tek parametrenin değeri sayılır (SaveCustomer(Customer c)'ye doğrudan { "Code": "C1" }).
• Puanlama: adaylar JSON değer türü uyumuna göre puanlanır. Tam sayı önce int, sonra long ve diğerleri; ondalık önce double, sonra decimal, sonra float. Değer tipe sığmalıdır (300 byte'a gitmez). Metin; string, tarih, Guid veya enum adı olabilir. Nesne, sınıf ya da dictionary olabilir.
• params / ParamArray: argümanlar tek tek de verilebilir (["A", "B"]); hiç verilmezse boş dizi geçer.
• Belirsizlik: eşit puanlı adaylar kalırsa AmbiguousMatch döner ve argTypes ile belirtmeniz istenir.

Komutları koddan üretmek

EvokerTarget ve nesne ömrü

EvokerLifetime, .NET'in DI ömürleriyle aynı mantıkta çalışır:

Özellikler: Type, Lifetime, IncludeNonPublic, Kind ("Type" / "Instance"), TypeFullName, Instance. Kendi hedef türünüzü yazmak için IEvokerTarget arayüzünü (Kind, TypeFullName, ExecuteAsync, DescribeAsync) uygulayın; Plugins paketindeki PluginTarget bu arayüzü kullanır.

EvokerCatalog — Guid anahtarlı hedef listesi

Sonuç ve hata modeli

Komutlar exception fırlatmaz; hatalar sonucun içinde döner. Bu yüzden web'e doğrudan verilebilir.

HTTP karşılığı EvokerErrorCodes.HttpStatus(code) ile alınır.

Tüm katmanların ortak dönüştürücüsü.

ConvertTo, aynı şekle sahip iki farklı tip arasında (ör. plugin'in Point'i ile host'un PointDto'su) dönüşümü dahili, derlenmiş bir kopyalayıcıyla yapar. Bu kopyalayıcı sonucu JSON yoluyla birebir aynı olan şekillerde kullanılır; diğer durumlarda JSON'a düşülür.

Bir tipin tam tanımını ve her üye için hazır JSON komut şablonlarını üretir. Hem çalışan tiplerle hem de DLL'i çalıştırmadan (MetadataLoadContext tipleriyle) çalışır.

Tanım modeli

Örnek imza çıktısı: "Task<int> AddAsync(int a, int b = 5)"

Plugin ve unload dostu tasarım

Collectible AssemblyLoadContext'ler, içlerindeki bir tipe güçlü referans tutan tek bir statik cache yüzünden bile bellekten atılamaz. Evoker'daki her cache'in bu yüzden bir çıkış kapısı vardır:

DSO.Core.Evoker.Plugins bunların hepsini unload sırasında kendisi çağırır. UnloadTest paketi, in-process bir plugin'in Evoker ile defalarca kullanıldıktan sonra gerçekten bellekten atıldığını doğrular.

Testler ve örnekler

Beklenen çıktı: her bölüm TÜM ... TESTLERİ GEÇTİ ✅ ile biter.

Bilinen sınırlar

• Şema ve accessor cache üst sınırları FIFO tahliye kullanır; gerçek LRU değildir.
• ForgetType/ForgetSchema kendi cache'lerimizi temizler. DynamicTypeFactory'nin ürettiği tipler collectible değildir (AssemblyBuilderAccess.Run); metadata'ları process ömrü boyunca kalır.
• EvokerBuilder ile ref/out parametreli metot çağrılmaz; bunun yerine açık bir hata verilir.
• Üretilen tiplerin ToString/Equals/GetHashCode davranışı object'ten gelir.