Revit API ile C# Eklentisi Geliştirmek: Başlangıç Yolu

Ne zaman Revit API ile eklenti yazılır?

Revit'te otomasyon için yaygın yollar şunlardır: Dynamo grafikleri, pyRevit betikleri ve derlenmiş C# eklentileri. Hepsi aynı Revit API'sini kullanır; fark, yazım biçiminde, dağıtımda ve kontrol düzeyindedir.

Bağımsız eklenti genellikle şu durumlarda tercih edilir: arayüzü özel bir pencere gerektiriyorsa, aracın performansı öne çıkıyorsa, ekip dışına ya da müşterilere dağıtım yapılacaksa ya da kod bir yazılım ürününe dönüşecekse. Tek seferlik veya ekip içi küçük otomasyonlarda ise grafik ve betik yaklaşımı çoğu zaman daha hızlıdır ve bakımı kolaydır.

Bu seçimi dürüstçe yapmak gerekir: eklenti geliştirme, bir mühendislik işidir. Kodun sürümlenmesi, test edilmesi ve Revit sürümleriyle uyumlu tutulması gerekir. Basit bir ihtiyaç için bu yükü taşımak gereksizdir.

Bir komutun yapısı

Revit'in dışarıdan çalıştırdığı komut, bir .NET sınıfıdır. Bu sınıf, Revit'in kullanıcı arayüzü ad alanında bulunan IExternalCommand arayüzünü uygular ve Execute adlı yöntemi tanımlar. Revit komutu çalıştırırken yönteme bir ExternalCommandData nesnesi verir; bu nesne, Revit uygulama nesnesine ve etkin görünüme ulaşmanızı sağlar. Yöntem bir Result döndürür: başarı, kullanıcı iptali ve başarısızlık. İptal ya da başarısızlık durumunda komut sırasında yapılan değişiklikler geri alınır.

Bir komut nesnesi, Execute bittiğinde yok edilir; bu yüzden veriyi nesnenin içinde bir sonraki çalıştırmaya taşıyamazsınız. Kalıcı durum gerekiyorsa statik bir alana ya da dosyaya yazmak gerekir.

En küçük komut şuna benzer:

using Autodesk.Revit.DB;

using Autodesk.Revit.UI;

public class HelloCommand : IExternalCommand

{

public Result Execute(ExternalCommandData commandData, ref string message, ElementSet elements)

{

TaskDialog.Show("Revit", "Hello");

return Result.Succeeded;

}

}

Bu komut modele dokunmaz. Önce böyle bir iskeletin yüklenip çalıştığını görmek, sonraki her adım için güvenli bir zemin sağlar.

Revit'e tanıtmak: .addin kayıt dosyası

Derlenen kod tek başına yetmez; Revit'in eklentiyi bulması için bir .addin kayıt dosyası gerekir. Revit, bu dosyaları açılışta belirli klasörlerden okur: tüm kullanıcılara ait ortak uygulama verisi klasöründen ve kullanıcıya özel klasörden. Dosyalar alfabetik sırayla yüklenir.

Bir komut kaydında temel olarak şu alanlar bulunur:

• Assembly: derlenmiş dosyanın tam yolu
• FullClassName: IExternalCommand'ı uygulayan sınıfın ad alanıyla birlikte adı
• AddInId: bu eklentiyi tanımlayan, her eklenti için benzersiz bir GUID
• Text: şeritteki butonun adı (isteğe bağlı)

Bir kayıt dosyasında birden çok komut tanımlanabilir. Dosya yanlış yerdeyse, biçimi bozuksa ya da sınıf adı yanlışsa eklenti yüklenmez; Revit çoğu zaman bir hata mesajı gösterir. Revit'in başka bir sürümü için derlenmiş dosyalar da yüklenmeyebilir ya da hata verebilir; bu yüzden her desteklenen sürüm için eklentiyi o sürümün API dosyalarına karşı derleyip denemek gerekir.

Kayıt bilgilerinin ve klasör konumlarının tam biçimi için kendi Revit sürümünüzün geliştirici kılavuzundaki eklenti kaydı bölümünü referans alın; konumlar sürüme göre değişebilir.

Modeli değiştirmek: işlem mantığı

Revit, model değişikliklerinin bir işlem içinde yapılmasını ister. İşlem, bir değişiklik grubunu tek bir bütün olarak uygulayan ve gerektiğinde geri alınabilir kılan çerçevedir. Kod bir işlem açar, elemanları değiştirir ve işlemi onaylar; bir hata olursa işlem iptal edilir ve model eski haline döner.

Bir komut sınıfı için işlem modu da belirlenir; Autodesk'in örneklerinde sınıfa, işlemleri kodun kendisinin yöneteceğini bildiren bir öznitelik eklenir. Bu detay, sürümler arasında dikkat gerektirdiği için kendi sürümünüzün belgesindeki örnekleri esas alın.

İşlem yönetiminde alışkanlık kazanılması gereken noktalar: Değişiklikleri küçük ve anlamlı gruplar hâlinde yapmak, işlem adlarını geri al listesinde anlaşılır yazmak ve hata durumlarında modeli yarım bırakmamak. Çok sayıda eleman değiştiren bir komutun tek işlemde toplanması hem hızlıdır hem de kullanıcı için tek bir geri alma adımı olarak görünür.

Geliştirme döngüsü

Eklenti geliştirme, yazma, derleme, kayıt ve deneme adımlarının tekrarıdır. Revit açıkken derlenen dosya kilitli olabilir; bu yüzden birçok geliştirici Revit'i kapatıp açarak deneme yapar. Hata ayıklayıcıyı çalışan Revit sürecine bağlayarak adım adım ilerlemek, karmaşık sorunları çözmenin en etkili yoludur.

Deneme hiçbir zaman gerçek proje dosyasında yapılmaz. Küçük bir deneme modeli ve kopya dosyalar kullanın; özellikle model değiştiren komutlar için. Kod bir sürüm kontrol sisteminde tutulur ve kayıt dosyası ile birlikte tek bir kurulum paketine dönüştürülür.

Öğrenme yolu ve sık hatalar

Revit API öğrenmek için önce Revit'i iyi bilmek gerekir; eleman kategorileri, ailelerin yapısı ve parametre mantığı API'nin kendisidir. Ardından C# ve .NET temelleri gelir. Sonra salt okunur komutlar yazılır: elemanları toplamak, parametrelerini okumak, sonuç listelemek. Modeli değiştirmek daha sonra, işlem mantığıyla birlikte öğrenilir. Son aşamada özel pencereler, olaylar ve eklentinin dağıtımı ele alınır.

En sık hatalar şunlardır: kayıt dosyasında yol ya da sınıf adının yanlış yazılması, farklı sürüm için derlenen dosyanın yüklenmesi, işlem açmadan model değiştirmeye çalışmak ve tüm elemanları gereksiz yere dolaşan ağır sorgular yazmak. Ayrıca, hata durumunu kullanıcıya açıklamadan komutu sessizce bitirmek, eklentiye güveni azaltır.

API, sürümden sürüme değişir; bu yüzden eski bir eğitim videosundaki ya da forumdaki kodu doğrudan kopyalamak yerine kendi sürümünüzün belgelerine bakın.

Bu beceriyi Mindset programlarında nerede çalışırsınız

Revit'te Dynamo ile Otomasyon Eğitimi, Özel Araç ve Script Geliştirme modülüyle Revit içinde otomasyonun mantığını kurar; bağımsız eklentiye geçmeden önce ihtiyacın Dynamo ile çözülüp çözülemeyeceğini görmek için uygun bir basamaktır. BIM ve Autodesk Revit Uzmanlaşma Eğitimi ise eklenti yazmak için gereken Revit eleman ve veri modelini temel düzeyde kurar.