Revit API - nauka kodowania dla efektywnego programowania

Jeżeli używasz Dynamo, to pewnie masz już poczucie, że potrzeba czegoś więcej. Gąszcze węzłów, w których łatwo się zgubić to nic przyjemnego. Chociaż programowanie graficzne jest dziecinnie proste i dość łatwo przychodzi, to czasami po prostu łatwiej by było użyć czystego kodu. Jeżeli nie umiesz programować w języku C# i nie znasz technologii .NET to nic strasznego. Dynamo oparte jest o Revit API, więc wykorzystuje tę samą przestrzeń nazw. Oznacza to, że komendy są dość podobne do tych w Python, różni nam się tylko składnia.

Dlaczego w ogóle mam nauczyć się kodować?

Wydajne rozwiązania wymagają optymalizacji. Chodzi tu zarówno o czas tworzenia funkcji, jak i czas, jaki potrzebny jest na jej wykonanie. Jeżeli przebrniesz przez jakiś tutorial dla początkujących z języka C# na YouTube i zaprogramujesz swoją pierwszą funkcję w Revit API, to zrozumiesz o co chodzi. Kultura pracy nawet niewyrafinowanego algorytmu czy obsługa błędów to całkowicie inna bajka. Dodatkowo platforma .NET otwiera okno na integrację Revit z softwarem firm trzecich. Poza tym znając podstawy będziesz bardziej atrakcyjny na rynku pracy.

Revit API – pierwsze kroki

API to, jak podaje Wikipedia, interfejs programistyczny aplikacji. W zasadzie nie trzeba więcej wyjaśniać tego pojęcia, ponieważ samo rozwinięcie skrótu już je wyjaśnia. Revit, jak prawie każde oprogramowanie dużej firmy, posiada taki interfejs. Programowanie należy rozpocząć od instalacji SDK, czyli pakietu deweloperskiego na swoim komputerze. Aktualne SDK znajdziesz pod linkiem w sekcji „Tools”. Dla leniwych podpowiem, że instalacja SDK nie jest obligatoryjna! Do referencji nowego czystego projektu typu library, należy po prostu dodać pliki RevitAPIUI.dll i RevitAPI.dll z głównego katalogu programu (C:\Program Files\Autodesk\Revit 20xx\*). Jeżeli zainstalowałeś SDK, po prostu zamiast czystego projektu uruchamiasz szablon producenta i programujesz. Autor biblioteki proponuje w ramach szkolenia przerobić sobie krótki projekt. Podaję link do niego tutaj oraz dodatkowo link do biblioteki poradników. Na koniec należy zapamiętać stronę Dokumentacji Revit API, bez niej ani rusz. Na stronie znajdziesz próbki kodu, przykłady i opisy funkcji.

Pierwsza funkcja w Revit API

Po utworzeniu nowego projektu i załadowaniu potrzebnych referencji do projektu (wersja dla leniwych), utwórz klasę np. MyFeature i dodaj potrzebne referencje do klasy.

Tak powinny wyglądać referencję tworzonego obiektu.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using Autodesk.Revit.ApplicationServices;
using Autodesk.Revit.Attributes;
using Autodesk.Revit.DB;
using Autodesk.Revit.UI;
using Autodesk.Revit.UI.Selection;

Klasa powinna dziedziczyć po IExternalCommand. Nad jej nazwą dodaj atrybuty dostępu do bazy i widoku.

[Transaction(TransactionMode.Manual)]
[Regeneration(RegenerationOption.Manual)]
public class MyFeature : IExternalCommand
{
}

Dziedziczenie po interfejsie jak powyżej spowoduje to, że będziemy musieli zaimplementować funkcję Execute, które zwraca Result jej wykonania. Najlepiej ustawić wykonanie jej na Result.Succeeded.

[Transaction(TransactionMode.Manual)]
[Regeneration(RegenerationOption.Manual)]
public class MyFeature : IExternalCommand
{
	public Result Execute(ExternalCommandData commandData, ref string message, ElementSet elements)
    {
    	return Result.Succeeded;
    }
}

Dodajmy do naszej funkcji algorytm zwracania Id elementu po zaznaczeniu obiektu.

[Transaction(TransactionMode.Manual)]
[Regeneration(RegenerationOption.Manual)]
public class MyFeature : IExternalCommand
{
	public Result Execute(ExternalCommandData commandData, ref string message, ElementSet elements)
    {
     	UIApplication uiapp = commandData.Application; //dobieramy się do aplikacji
        Document doc = uiapp.ActiveUIDocument.Document; //dobieramy się do otwartego dokumentu
        
        Selection selection = uiapp.ActiveUIDocument.Selection; //obiekt służy do pobierania elementów z zaznaczenia
        var picked = selection.PickObject(ObjectType.Element, "Zaznacz element"); //wybór procedury zaznaczania przez PickObiejct
        Element elem = doc.GetElement(picked); //Pobierz zaznaczony element
	    TaskDialog.Show("Zaznaczono element o id:", elem.Id.ToString()); //Wyświetla komunikat
        
    	return Result.Succeeded;
    }
}

Uruchomienie swojej funkcji w Revit API

W celu uruchomienia funkcji należy skompilować nasz projekt. Jeżeli korzystasz z SDK, wystarczy kliknąć przycisk „Start”, czyli uruchomić debuggowanie. W trybie SDK, Revit powinien odpalić się automatycznie z załadowaną funkcją.

Uwaga może pojawić się taki komunikat.

Warning There was a mismatch between the processor architecture of the project being built „MSIL” and the processor architecture of the reference „RevitAPI”, „AMD64”. This mismatch may cause runtime failures. Please consider changing the targeted processor architecture of your project through the Configuration Manager so as to align the processor architectures between your project and references, or take a dependency on references with a processor architecture that matches the targeted processor architecture of your project.

Lekarstwem będzie zmiana platformy z x86 na x64.

Kolejnym etapem jest przekopiowanie wkompilowanego pliku *.dll do katalogu (C:\ProgramData\Autodesk\Revit\Addins\20xx). Jeżeli to już zrobimy, w tym samym katalogu trzeba stworzyć nowy plik *.xml np. w notatniku. Nazwa pliku jest obojętna, ale dobre praktyki mówią, żeby była taka sama jak naszego pliku biblioteki (*.dll). Plik powinien zawierać następujący kod:

<?xml version="1.0" encoding="utf-8"?>
<RevitAddIns>
  <AddIn Type="Command">
       <Name>Sample1</Name>
       <FullClassName>Sample1.MyFeature</FullClassName>
       <Text>Sample1</Text> 
       <Description>Example description</Description>
       <VisibilityMode>AlwaysVisible</VisibilityMode>
       <Assembly>Sample1.dll</Assembly>
       <AddInId>b140065c-8bf6-4337-87d7-a84720ce0931</AddInId>
    <VendorId>COMPANY</VendorId>
    <VendorDescription>Example company description</VendorDescription>
  </AddIn>
</RevitAddIns>

Projekt nazwałem „Sample1”, więc FullClassName trzeba ustawić na Sample1.MyFeature a Assembly na Sample1.dll. Teraz uruchamiamy Revit → nowy projekt i przechodzimy do zakładki Add-Ins. W sekcji „External” znajduje się przycisk „External Tools”, klikamy go i wybieramy „Sample1”. Nasza funkcja działa i prosi o zaznaczenie obiektu!

Przycisk External Tools z widoczną funkcją Sample1.

Revit API – co dalej?

Jak mawia klasyk: „Sky is the limit”, w świecie programisty nie ma rzeczy nie możliwych. Ograniczają Cię tylko czas i pieniądze. Mam nadzieję, że artykuł jakoś przekonał Cię do spróbowania swoich sił w środowisku .NET. Postaram się co jakiś czas publikować wartościowe przykłady tworzenia własnych interfejsów, algorytmów i ogólnego tworzenia własnych bibliotek.

Obraz Julián Amé z Pixabay