Extrahieren einer Shared-Parameter-GUID aus einer InternalDefinition

Einführung

Wenn Sie Revit-Add-ins entwickeln und mit Shared Parameters arbeiten, haben Sie sich vielleicht schon gefragt: Wie lässt sich die GUID eines Shared Parameters direkt aus dem Modell auslesen – ganz ohne Shared-Parameter-Datei und ohne tausende Elemente zu durchsuchen?

Die gute Nachricht: Mit der InternalDefinition-API und ForgeTypeId können Sie die GUID effizient und zuverlässig ermitteln. In diesem Beitrag erfahren Sie:

• Wie Sie alle nicht eingebauten Parameterdefinitionen aus dem Dokument sammeln
• Wie Sie die GUID aus dem ForgeTypeId extrahieren
• Wie Sie Shared und Projektparameter unterscheiden
• Warum dieser Ansatz schnell und skalierbar ist

Warum ExternalDefinition nicht ausreicht

Shared Parameters werden in einer Shared-Parameter-Datei definiert, die an Revit angehängt werden kann. Jede Definition in dieser Datei enthält unter anderem den Parameternamen und eine GUID. Das Auslesen dieser GUID ist einfach – wenn Sie Zugriff auf die ExternalDefinition-Instanzen aus der aktuell angehängten Datei haben.

In der Praxis ist dieser Ansatz jedoch fehleranfällig:

• Unterschiedliche Teams oder Projektphasen verwenden verschiedene Parameterdateien.
• Die korrekte Datei ist zur Laufzeit möglicherweise nicht angehängt.
• Manche Projekte nutzen kundenspezifische Parameterdateien.
• In automatisierten Umgebungen ist der Dateizugriff oft eingeschränkt.

Daher ist die Abhängigkeit von der Shared-Parameter-Datei keine zuverlässige Lösung.

Warum nicht alle Elemente durchsuchen?

Eine andere Idee ist, alle Elemente im Projekt zu durchlaufen, deren Parameter zu sammeln und die GUIDs auszulesen. Das funktioniert bei kleinen Modellen, wird aber schnell zum Performance-Problem:

• Große Projekte enthalten hunderttausende Elemente und Millionen Parameter.
• Das Durchsuchen aller Elemente erhöht Speicherbedarf und Rechenzeit.
• Möglicherweise gibt es kein Element, das den gesuchten Shared Parameter verwendet.

Wir benötigen einen schnellen, dokumentbasierten Ansatz, der nicht von Elementinstanzen oder der Parameterdatei abhängt.

Der effiziente Ansatz: InternalDefinition aus ParameterBindings lesen

Revit verwaltet im Document eine ParameterBindings-Map, die Definition-Objekte mit ihren Bindungen verknüpft. Diese Map kann durchlaufen werden, um alle nicht eingebauten Parameterdefinitionen zu sammeln:

var definitions = new HashSet<InternalDefinition>();

var bindings = document.ParameterBindings;
var iterator = bindings.ForwardIterator();
iterator.Reset();
while (iterator.MoveNext())
{
    if (iterator.Key is not InternalDefinition definition)
    {
        continue;
    }

    if (definition.BuiltInParameter == BuiltInParameter.INVALID)
    {
        definitions.Add(definition);
    }
}

ForgeTypeId: GUID extrahieren

Revit stellt für InternalDefinition die Methode GetTypeId() bereit. Der zurückgegebene TypeId-String enthält sowohl den Ursprung als auch die Kennung des Parameters. Beispiele:

• Shared Parameter: revit.local.shared:15a75d930ff84e9484f3cb1c7af1d1e3-1.0.0
• Projektparameter: revit.local.project:8b2d1a2b1b9c4d8e9f0a1b2c3d4e5f6a-1.0.0

Das 32-stellige Segment nach dem letzten Doppelpunkt ist die GUID.

public static Guid? ExtractGuid(this InternalDefinition definition)
{
    const int guidLength = 32;

    var forgeTypeId = definition.GetTypeId();
    if (forgeTypeId.Empty())
    {
        return null;
    }

    var typeId = forgeTypeId.TypeId;
    var position = typeId.LastIndexOf(':');
    if (position < 0)
    {
        return null;
    }

    return Guid.TryParseExact(typeId.Substring(position + 1, guidLength), "N", out var guid)
        ? guid
        : null;
}

Shared vs. Projektparameter unterscheiden

Da sowohl Shared als auch Projektparameter eine GUID im ForgeTypeId enthalten, muss zur Unterscheidung der Präfix geprüft werden:

• revit.local.shared → Shared Parameter
• revit.local.project → Projektparameter

public static bool IsShared(this InternalDefinition definition)
{
    var ftid = definition.GetTypeId();
    return !ftid.Empty()
        && ftid.TypeId.StartsWith("revit.local.shared", StringComparison.OrdinalIgnoreCase);
}

public static bool IsProject(this InternalDefinition definition)
{
    var ftid = definition.GetTypeId();
    return !ftid.Empty()
        && ftid.TypeId.StartsWith("revit.local.project", StringComparison.OrdinalIgnoreCase);
}

Zusammenführen: Alle Shared-Parameter-GUIDs ermitteln

public static Dictionary<string, Guid> Build(Document document)
{
    var defs = ParameterDefinitionCollector.GetNonBuiltInDefinitions(document);

    var sharedDefs = defs.Where(d => d.IsShared());

    var result = new Dictionary<string, Guid>(StringComparer.OrdinalIgnoreCase);
    foreach (var d in sharedDefs)
    {
        var guid = d.ExtractGuid();
        if (guid.HasValue)
        {
            result[d.Name] = guid.Value;
        }
    }

    return result;
}

Performance-Hinweise

• Das Durchlaufen von Document.ParameterBindings skaliert mit der Anzahl der Definitionen, nicht mit der Anzahl der Elemente.
• Es werden keine Parameter-Objekte für jedes Element erzeugt.
• Schnell und ressourcenschonend im Vergleich zur vollständigen Modellsuche.

Verfügbarkeit und Aktualisierungsstrategie

ParameterBindings sind dokumentbezogen. Die GUID-Liste kann nicht einmal beim Start erstellt und global wiederverwendet werden.

• Erstellen Sie die Liste beim Öffnen eines Dokuments oder bei Bedarf.
• Bindungen können sich ändern, wenn Parameter hinzugefügt oder entfernt werden.
• Erstellen Sie die Liste bei jeder Verwendung neu oder implementieren Sie einen Cache mit Aktualisierung.

Fehlerquellen und Sonderfälle

• Prüfen Sie forgeTypeId.Empty() und behandeln Sie fehlerhafte Strings.
• Eingebaute Parameter haben keine Shared GUIDs.
• Definition.Name ist nicht eindeutig garantiert.

Fazit

Sie benötigen weder die Shared-Parameter-Datei noch eine langsame Modellsuche, um GUIDs von Shared Parameters zu ermitteln. Durch das Durchlaufen von Document.ParameterBindings, das Filtern auf InternalDefinition und das Parsen des ForgeTypeId:

• Sammeln Sie alle benutzerdefinierten Parameterdefinitionen.
• Unterscheiden Sie Shared und Projektparameter anhand des Präfixes.
• Extrahieren Sie die GUID für Mapping, Analyse oder Interoperabilität.

Dieser Ansatz ist schnell, robust und dateiunabhängig – ideal für produktive Add-ins mit der Revit API.