SolidWorks Add-in Geliştirme: C# ile Eklenti Yazmaya Giriş

Eklenti, SolidWorks süreci içinde çalışan bir .NET sınıf kütüphanesidir (.dll). Makro dış bir dosya olarak çağrılıp biter; bağımsız uygulama SolidWorks'ü dışarıdan sürer ve kendi penceresinde yaşar. Eklenti ise ikisinin arasında değil, tamamen başka bir yerde durur: SolidWorks onu başlangıçta yükler, arayüzüne yerleşmesine izin verir ve kapanana kadar bellekte tutar. Kabiliyet farkı değil, ömür ve sahiplik farkı budur — hangi belirtilerin bu geçişi gerektirdiğini makro ile eklenti karşılaştırmasında tablo halinde ele almıştım.

Bir sınıfın SolidWorks tarafından eklenti olarak tanınması için ISwAddin arayüzünü uygulaması gerekir. Bu arayüzün iki üyesi vardır ve eklentinin tüm hikâyesi bu ikisinin arasında geçer:

• `ConnectToSW` — SolidWorks eklentiyi yüklediğinde çağrılır. Uygulama nesnesi ve bir cookie (eklenti kimliği) verilir. Menüler, sekmeler ve olay abonelikleri burada kurulur.
• `DisconnectFromSW` — SolidWorks kapanırken veya kullanıcı eklentiyi devre dışı bıraktığında çağrılır. ConnectToSW içinde kurulan her şey burada geri alınır: komut grupları kaldırılır, olay abonelikleri sökülür, tutulan referanslar bırakılır.

Bağlanma anında sırayla üç şey yapılır. Önce SolidWorks'ün size verdiği uygulama nesnesi ve çerez (cookie) değeri saklanır — çerez, eklentinizin kimliğidir ve buton geri çağrılarının size ulaşması için şarttır. Ardından bu çerezle birlikte kendinizi geri çağrı hedefi olarak kaydettirirsiniz; bu adımı atlarsanız butonlarınız görünür ama tıklandığında hiçbir şey olmaz — sahada en çok vakit kaybettiren sessiz hatalardan biri.

Sonra komut arayüzünü kurarsınız: CommandManager sekmesi ve butonlar. En sonda olay aboneliklerini bağlarsınız.

Ve bu fonksiyonun dönüş değeri önemli: başarılı bir bağlanma olumlu bir sonuç döndürmelidir. Olumsuz dönerseniz SolidWorks eklentiyi hiç yüklemez — üstelik bunu kullanıcıya açıkça söylemez.

İki ayrıntı sık atlanır. Birincisi, ConnectToSW içinden false dönmek eklentiyi sessizce yüklenmemiş hale getirir; hatayı yutarsanız kullanıcı yalnızca "sekme gelmedi" der. İkincisi, cookie'yi saklamazsanız buton geri çağrıları (callback) hiçbir zaman size ulaşmaz.

SolidWorks API'si COM tabanlıdır; eklentiniz .NET ile yazılmış olsa bile SolidWorks onu bir COM bileşeni olarak görür. Bu yüzden derlenmiş .dll dosyasını bir klasöre koymak yetmez — iki ayrı tanıtım gerekir:

1. COM kaydı. Sınıf ComVisible olarak işaretlenir ve sabit bir Guid alır. Kayıt işlemi .NET Framework ile gelen regasm aracıyla yapılır; derlemeyi GAC'a koymuyorsanız /codebase anahtarı gerekir, çünkü SolidWorks DLL'i diskte nerede bulacağını bilmelidir.

2. SolidWorks kaydı. SolidWorks, yükleyeceği eklentileri kendi registry dalında tutar. Uygulama düzeyindeki eklenti listesi HKEY_LOCAL_MACHINE altında, kullanıcının o eklentiyi açık mı kapalı mı bıraktığı bilgisi ise HKEY_CURRENT_USER altında saklanır. Bu ayrım pratikte şu anlama gelir: eklentiyi kurmak, kullanıcıda otomatik açık gelmesini garanti etmez. Anahtar adları ve tam yollar SolidWorks sürümüne göre değişebilir; kurulum betiğinizi yazmadan önce hedeflediğiniz sürümün resmî dokümantasyonundan doğrulayın.

Bu ikinci adımı elle yapmak yerine ComRegisterFunction ve ComUnregisterFunction ile işaretlenmiş metotlara bırakmak yaygın yaklaşımdır: regasm çalıştığında bu metotlar tetiklenir ve registry girdilerini kod yazar. Böylece kurulum ve kaldırma tek yerden yönetilir.

HKEY_LOCAL_MACHINE'e yazmak yönetici hakkı gerektirir. Bu, dağıtım bölümünde tekrar karşımıza çıkacak.

Eklentinin görünen yüzü üç ana bileşene dayanır. Seçim estetik değil, etkileşimin süresine göre yapılır.

CommandManager eklentinin kimliğidir. Kendi sekmenizi ve buton grubunuzu ekler, her butona bir geri çağrı metodu ve isteğe bağlı olarak bir "etkin mi" metodu bağlarsınız. İkincisi önemlidir: aktif belge bir teknik resim değilken teknik resim butonu gri görünmelidir. Bu küçük ayrıntı, kullanıcının eklentiye güvenip güvenmemesini belirler.

TaskPane, SolidWorks'ün sağ panelinde yaşayan bir görünümdür. İçine kendi WinForms/WPF kontrolünüzü yerleştirirsiniz. Bir işi başlatmak için değil, durumu göstermek için uygundur.

PropertyManagerPage, SolidWorks'ün kendi komutlarının kullandığı sol paneldir. Kendi diyalog pencerenizi açmak yerine bunu kullanmanın iki avantajı vardır: kullanıcı zaten bu etkileşim biçimini biliyor ve model üzerinden seçim yapmaya (yüzey, kenar, bileşen) doğal olarak izin verir. Sayfa oluşturma ve olaylarını karşılayan işleyici (handler) arayüzünün sürüm numaralı birden fazla varyantı vardır; hangi sürümü uygulayacağınızı hedef SolidWorks sürümünün API dokümantasyonundan seçin.

Pratik bir sıralama: önce CommandManager ile tek buton, sonra iş büyüdükçe PropertyManagerPage, gerçekten sürekli görünür bir şey gerekiyorsa TaskPane. Ters sırada başlamak, kullanılmayan arayüz üretir.

Eklentiyi makrodan ayıran asıl yetenek olay yakalamadır (event handling): belge açıldığında kontrol etmek, kaydetmeden önce doğrulamak, aktif belge değiştiğinde arayüzü güncellemek.

Olaylar iki seviyede gelir. Uygulama seviyesindeki olaylar SldWorks nesnesinden gelir — belge açılması, aktif belgenin değişmesi gibi. Belge seviyesindeki olaylar ise belge türüne özel arayüzlerden gelir: parça, montaj ve teknik resim için ayrı olay kümeleri vardır. Yani "kaydetmeden önce doğrula" davranışını üç belge türü için de istiyorsanız, üç ayrı aboneliği yönetmeniz gerekir.

Olaylar iki seviyede yaşar. Uygulama seviyesindeki olaylar SolidWorks'ün kendisiyle ilgilidir: yeni bir belge açılması, aktif belgenin değişmesi. Belge seviyesindeki olaylar ise tek bir belgeye aittir: kaydedilmeden önce, yeniden kurulduktan sonra, bir özellik değiştiğinde.

Buradaki en sinsi tuzak şu: bir belge açıldığında o belgeye özel bir olay dinleyicisi oluşturursunuz — ve o nesneye başka hiçbir yerde referans tutmazsanız, .NET çöp toplayıcısı onu bir süre sonra temizler. Olaylar sessizce gelmemeye başlar. Hata yoktur, mesaj yoktur; sadece eklentiniz bir gün "bazen çalışmıyor" olur.

Çözüm basit ama unutulması kolay: belge işleyicilerini bir sözlükte (dosya adına göre) tutun, belge kapanınca da o kayıttan çıkarın. Bu tek alışkanlık, eklenti geliştirmenin en zor teşhis edilen problemini baştan çözer.

Buradaki _handlers sözlüğü süs değil. COM olaylarında en sık yapılan hata budur: olay aboneliğini kuran nesneye başka hiçbir yerden güçlü referans tutulmazsa, çöp toplayıcı (garbage collector) o nesneyi bir süre sonra toplar ve olaylar sessizce gelmemeye başlar. Hata mesajı yoktur, istisna (exception) fırlamaz, derleme uyarı vermez. Eklenti dakikalarca doğru çalışır, sonra "bazen çalışmıyor" olur.

Bu yüzden kural nettir: her olay işleyici nesnesi, ömrü boyunca eklenti sınıfının tuttuğu bir koleksiyonda yaşar. Belge kapandığında o girdi koleksiyondan çıkarılır ve abonelik sökülür. DisconnectFromSW içinde koleksiyon boşaltılır.

İkinci sık hata, olay işleyicisinin içinde uzun iş yapmaktır. Olay geri çağrıları SolidWorks'ün kendi akışının ortasında çalışır; orada dakikalarca süren bir işlem başlatmak arayüzü kilitler ve kullanıcının SolidWorks'ün çöktüğünü sanmasına yol açar.

Eklenti projelerinin bozulma biçimi hep aynıdır: buton geri çağrısının içine hem SolidWorks API çağrıları, hem iş kuralları, hem de dosya yazma işlemleri girer. İlk sürümde çalışır, üçüncü kuralda okunamaz hale gelir.

Ayrım basit bir soruyla yapılır: bu kod SolidWorks'ü bilmek zorunda mı?

• Eklenti katmanı — ISwAddin, komut kaydı, arayüz. SolidWorks'ü bilir, kural bilmez.
• API erişim katmanı — belgeden özellik okuma, dışa aktarma, geometri sorgulama. SolidWorks'ü bilir, kural bilmez.
• İş mantığı katmanı — adlandırma kuralları, doğrulama, hangi çıktının ne zaman üretileceği. Kuralı bilir, SolidWorks'ü hiç bilmez.

Üçüncü katmanın SolidWorks'ü bilmemesi teorik bir zarafet değil, doğrudan test edilebilirlik demektir: "revizyon numarası bu formata uyuyor mu" sorusunu SolidWorks açmadan, saniyeler içinde test edebilirsiniz. Kuralların çoğu hatası da orada yaşar.

Bu ayrımın genel gerekçesini ve nasıl kurulacağını modüler yazılım mimarisi yazısında ayrıca anlattım; eklenti tarafında en çok işe yarayan yanı, arayüzü değiştirmeden kuralı değiştirebilmektir.

Makroda hata yönetimi opsiyoneldir çünkü hatayı yapan kişi ile onu gören kişi aynıdır: makro patlar, siz görürsünüz, düzeltirsiniz.

Eklentide bu zincir kopar. Kodunuz başka bir bilgisayarda, başka bir SolidWorks sürümünde, sizin hiç görmediğiniz bir montaj üzerinde çalışır ve size ulaşan geri bildirim tek cümledir: "çalışmadı". Log yoksa geriye kalan tahmin oyunudur.

Üç kural yeterli bir başlangıç sağlar:

1. Olay geri çağrılarından ve buton geri çağrılarından dışarı istisna sızdırmayın. COM sınırının ötesine geçen bir istisna, kullanıcıya anlamsız bir hata olarak görünür ya da daha kötüsü SolidWorks'ü kararsız bırakır. Her giriş noktası try/catch ile sarılır, yakalanan hata loglanır.
2. Dönüş değerlerini kontrol edin. SolidWorks API'sinin birçok metodu hata fırlatmaz; null veya false döner. Kontrol edilmeyen bir dönüş, sessizce eksik çıktı üretir — otomasyonun en pahalı hata türü budur ve yapay zeka ile üretilen eklenti kodunda en sık atlanan kontrol de tam olarak budur.
3. Kullanıcı başına dosyaya yazın. Log dosyası, kullanıcının yazma hakkı olan bir dizinde tutulmalı ve sürüm numarası, SolidWorks sürümü, belge adı ve zaman damgası içermelidir.

Buton geri çağrılarının iskeleti her zaman aynı olmalı ve üç kuralı taşımalı.

Bir: aktif belgeyi al ve yokluğunu kontrol et. Belge yoksa kullanıcıya anlaşılır bir şey söyle ve çık.

İki: asıl işi geri çağrının içine yazma. Geri çağrı yalnızca bir tetikleyicidir; iş mantığı ayrı bir serviste dursun. Bu ayrım, eklentinizin test edilebilir kalmasının tek yolu.

Üç: her şeyi bir hata yakalayıcıyla sar. Bu, eklenti geliştirmenin en kritik kuralı: hiçbir istisna COM sınırını geçmemeli. Geri çağrıdan dışarı sızan bir hata, SolidWorks'ün kendisini kararsız hale getirebilir ya da doğrudan çökertir. Hatayı yakalayın, günlüğe yazın, kullanıcıya sade bir mesaj gösterin — ve akışı orada bitirin.

Eklentiyi yazmak işin yarısı; on kişinin bilgisayarında aynı sürümün çalıştığından emin olmak diğer yarısı.

Kurulum paketi. Dosya kopyalama yetmez, çünkü COM kaydı ve registry girdileri gerekiyor ve bunlar yönetici hakkı isteyebiliyor. Bir MSI ya da eşdeğeri kurulum paketi, kurulum ve kaldırmayı tek adıma indirir. Kaldırma senaryosunu baştan test edin: geride kalan registry girdisi, SolidWorks açılışında var olmayan bir DLL'i yüklemeye çalışmasına yol açar.

Sürüm yönetimi. Eklentinin sürüm numarasını hem derlemeye gömün hem de arayüzde görünür bir yerde gösterin (About butonu ya da TaskPane alt bilgisi). Log satırlarına da yazın. "Hangi sürümü kullanıyorsunuz" sorusunun cevabını kullanıcıya sormak zorunda kalmamak, destek süresini belirgin biçimde kısaltır. Guid değerini sürümler arasında sabit tutun — değiştirmek, kullanıcının eklentiyi tekrar elle etkinleştirmesini gerektirir.

Mimari ve çalışma zamanı uyumu. Eklenti SolidWorks süreci içinde yüklendiği için işlemci mimarisi uyuşmak zorundadır; güncel SolidWorks sürümleri 64 bit çalışır ve 32 bit derlenmiş bir eklenti yüklenmez. Aynı şekilde eklentinizin hedeflediği .NET çalışma zamanı da SolidWorks'ün desteklediği aralıkta olmalıdır. Desteklenen .NET sürümü SolidWorks sürümüne göre değişir; hedef sürümü seçmeden önce resmî sistem gereksinimlerinden doğrulayın.

Geriye dönük uyum. API metotlarının sürüm numaralı varyantları vardır ve eski adlar zamanla kullanımdan kaldırılabilir. Birden fazla SolidWorks sürümünü desteklemeniz gerekiyorsa, desteklediğiniz en eski sürümün interop derlemesine karşı derlemek yaygın bir yaklaşımdır — ama her sürümde test edilmeden bu bir varsayımdır.

1. Olay işleyicilerine güçlü referans tutmamak. En sinsi hata. Olaylar bir süre çalışır, sonra sessizce kesilir. Belirti: "bazen çalışıyor bazen çalışmıyor".
2. `DisconnectFromSW` içini boş bırakmak. Komut grupları kaldırılmaz, abonelikler sökülmez, referanslar bırakılmaz. Sonuç: SolidWorks kapanırken takılır veya arka planda süreç kalır.
3. COM sınırını geçen istisnalar. Geri çağrılardan dışarı sızan bir istisna, kullanıcıya anlamsız görünür ve oturumu kararsız bırakabilir.
4. Dönüş değerlerini kontrol etmemek. Fırlatmayan ama null/false dönen çağrılar, sessizce eksik çıktı üretir.
5. Her şeyi buton geri çağrısına yazmak. İş mantığı arayüz koduna karışınca test imkânsızlaşır, kural değişikliği her seferinde arayüze dokunmayı gerektirir.
6. Uzun işi olay içinde çalıştırmak. Arayüz kilitlenir, kullanıcı SolidWorks'ün çöktüğünü sanır.
7. Sürüm bilgisini kaydetmemek. Sahadan gelen hata raporu, hangi sürüme ait olduğu bilinmediğinde işe yaramaz.
8. `Guid`'i sürümler arasında değiştirmek. Kullanıcı tarafında eklenti "kaybolur", yeniden etkinleştirilmesi gerekir.

SolidWorks eklentisi hangi dillerle yazılır? En yaygın olarak C# ve VB.NET; C++ ile de yazılabilir. Ortak koşul, bileşenin COM üzerinden SolidWorks tarafından yüklenebilmesidir.

Eklenti geliştirmek için hangi lisans gerekir? API, SolidWorks lisansının parçasıdır; eklenti geliştirmek için ayrı bir ürün satın alınmaz. Erişebildiğiniz yetenekler kullandığınız sürüme göre değişir.

Eklentim neden eklenti listesinde görünmüyor? Genellikle üç nedenden biri: COM kaydı yapılmamıştır (regasm, gerekiyorsa /codebase ile), SolidWorks registry girdisi eksiktir, ya da mimari uyuşmuyordur (32/64 bit veya desteklenmeyen .NET sürümü).

Olaylarım bir süre sonra neden gelmiyor? Neredeyse her zaman olay işleyici nesnesine güçlü referans tutulmamasındandır; çöp toplayıcı nesneyi topladığında abonelik sessizce düşer. İşleyicileri eklenti sınıfında bir koleksiyonda saklayın.

Kendi diyalog penceremi mi açmalıyım, PropertyManagerPage mi kullanmalıyım? Model üzerinden seçim alınacaksa veya akış SolidWorks komutları gibi hissettirilecekse PropertyManagerPage. Bağımsız, karmaşık ve nadiren açılan bir yapılandırma ekranı için ayrı pencere de makuldür.

Mevcut VBA makromu doğrudan C# eklentiye çevirebilir miyim? Çağrıların çoğu bire bir karşılık bulur, ama doğrudan çeviri genellikle yeterli olmaz: makro tek seferlik bir akış varsayar, eklenti ise durum, yaşam döngüsü ve hata yönetimi ister. Çeviriyi başlangıç noktası olarak kullanın, mimariyi baştan kurun.

Birden fazla SolidWorks sürümünü tek eklentiyle destekleyebilir miyim? Genellikle evet — yaygın yaklaşım desteklenen en eski sürümün interop derlemesine karşı derlemektir. Ancak sürüme bağlı davranış farkları olabileceği için her hedef sürümde test edilmesi gerekir.

Eklenti geliştirmede zorlanılan yer API'nin genişliği değil, eklentinin SolidWorks ile aynı ömrü paylaşıyor olmasıdır. Bu yüzden ilk günden itibaren üç şeyi doğru kurmak, sonradan gelen her şeyi kolaylaştırır:

• ConnectToSW ile DisconnectFromSW arasında tam simetri
• Olay işleyicilerine güçlü referans, uzun işe olay içinde yer yok
• İş mantığı, SolidWorks'ü hiç bilmeyen ayrı bir katmanda

Arayüz bileşenini etkileşimin süresine göre seçin, hatayı loglayın, sürümü görünür kılın ve kurulumu paketleyin. Gerisi büyük ölçüde tekrar eden iskelet koddur.

Bu mimarinin makro seviyesinden nasıl büyüdüğünü görmek isterseniz SolidWorks CAD otomasyonu vaka çalışmasına bakabilirsiniz. Kendi sürecinizde eklenti eşiğine gelip gelmediğinizi birlikte değerlendirmek isterseniz iletişim bölümünden yazabilirsiniz.