Mit dem Erstellen von Bibliotheken beginnen

Es gibt zwei Möglichkeiten, einen neuen Construction Kit zu erstellen: mit einer .NET-Projektvorlage oder mit dem Compiler.

Mit Projektvorlage erstellen

Neue Construction Kits können mit der Projektvorlage erstellt werden. Die Vorlage kann von NuGet installiert werden:

dotnet new install Meshmakers.Octo.ConstructionKit.Templates

Um eine bestimmte Version der Vorlage zu installieren, verwenden Sie den folgenden Befehl:

dotnet new install Meshmakers.Octo.ConstructionKit.Templates::0.0.2312.12001

Erstellen Sie ein neues Projekt mit Ihrer bevorzugten Entwicklungsumgebung; die Vorlage sollte als OctoMesh Construction Kit Library verfügbar sein, alternativ können Sie den folgenden Befehl verwenden:

dotnet new ConstructionKit -n <name of project>

Bauen Sie das Projekt; ein neuer Construction Kit wird im Ordner ConstructionKit im Projektstammverzeichnis erstellt.

Mit dem Compiler erstellen

Den Compiler installieren

Der Compiler kann von NuGet installiert werden:

dotnet tool install meshmakers.Octo.ConstructionKit.Compiler --global # global available
dotnet tool install meshmakers.Octo.ConstructionKit.Compiler --local --create-manifest-if-needed # local available

Sie können auch eine bestimmte Version des Compilers installieren:

dotnet tool install meshmakers.Octo.ConstructionKit.Compiler --global --version 0.0.2312.12001 # global available
dotnet tool install meshmakers.Octo.ConstructionKit.Compiler --local --version 0.0.2312.12001 --create-manifest-if-needed # local available

Global wird das Werkzeug als octo-ckc verfügbar, lokal als dotnet octo-ckc.

Erstellen Sie einen neuen Construction Kit mit dem folgenden Befehl:

octo-ckc -c new -p '<path of directory for construction kit>'

Eine Construction-Kit-Bibliothek bearbeiten

Beim Erstellen einer neuen Construction-Kit-Bibliothek mit der Projektvorlage wird automatisch eine kompilierbare Beispielstruktur generiert. Die Construction-Kit-Dateien befinden sich im Ordner ConstructionKit im Projektstammverzeichnis.

Verzeichnisstruktur

Das generierte Beispiel folgt dieser Struktur:

ConstructionKit/
├── ckModel.yaml           # Model definition with ID and dependencies
├── attributes/            # Attribute definitions
│   ├── sampleAttribute1.yaml
│   ├── sampleAttribute2.yaml
│   └── sampleAttribute3.yaml
├── associations/          # Association definitions
│   └── sampleAssociation1.yaml
├── enums/                 # Enum definitions
│   └── sampleEnum1.yaml
├── records/               # Record definitions
│   └── sampleRecord1.yaml
└── types/                 # Type definitions
    └── sampleType1.yaml

CkModel (ckModel.yaml): Definiert die Modell-ID und die Abhängigkeiten zu anderen Construction-Kit-Bibliotheken
CkAttributes (attributes/*.yaml): Definieren wiederverwendbare Attribute mit Datentypen (Zeichenketten, Zahlen, boolesche Werte usw.)
CkAssociations (associations/*.yaml): Definieren Beziehungen zwischen Typen mit Kardinalität
CkEnums (enums/*.yaml): Definieren Aufzählungstypen mit ihren möglichen Werten
CkRecords (records/*.yaml): Definieren komplexe Datenstrukturen mit zugewiesenen Attributen
CkTypes (types/*.yaml): Definieren die Haupt-Entitätstypen, die Attribute und Assoziationen kombinieren

hinweis

Attribute können demselben Typ nicht mehrfach zugewiesen werden, da jedes Attribut seine eigenen Metadaten und Semantik trägt. Beispiel: GrossPrice und NetPrice müssen als zwei getrennte Attribute definiert werden, nicht als ein einzelnes Price-Attribut, das zweimal mit unterschiedlichen Namen zugewiesen wird.

Dateiorganisation

Die Vorlage erstellt eine Best-Practice-Struktur mit:

Getrennten Verzeichnissen für jeden Elementtyp (attributes, associations, enums, records, types)
Individuellen YAML-Dateien für jede Definition, was das Modell modular und wartbar macht
Beispieldefinitionen, die die korrekte Syntax demonstrieren und sofort kompilierbar sind

Ein Objektmodell entwickeln

Der erste Schritt besteht darin, die Modell-ID anzupassen und die Abhängigkeiten in der Datei ckModel.yaml zu definieren. Es gibt bereits mehrere vorhandene Construction-Kit-Bibliotheken, auf denen Sie aufbauen können, anstatt alles von Grund auf neu zu erfinden. Diese Bibliotheken sind im Abschnitt Bibliotheken dokumentiert.

Entwurf von Entitäten

Beginnen Sie damit, die Entitäten (Typen) in Ihrer Domäne zu identifizieren. Jede Entität repräsentiert ein Geschäftsobjekt mit eigenem Lebenszyklus und eigener Identität. Definieren Sie diese als separate Typdateien im Verzeichnis types/.

Beziehungen und Assoziationen

Definieren Sie, wie Entitäten über Assoziationen miteinander in Beziehung stehen:

Erstellen Sie Assoziationsdefinitionen im Verzeichnis associations/
Geben Sie die Kardinalität (1:1, 1:n, n:m) und Navigationseigenschaften an
Verwenden Sie für hierarchische Strukturen die eingebaute Assoziation System/ParentChild für Eltern-Kind-Beziehungen

Semantische Werte mit Enums

Enums verleihen Wertebereichen semantische Bedeutung. Anstatt einfache Zeichenketten oder Zahlen zu verwenden, bieten Enums:

Kontrollierte Vokabulare mit definierten möglichen Werten
Typsicherheit und Validierung
Klare Geschäftssemantik

Beispiel: Definieren Sie ein Status-Enum mit Werten wie Active, Pending, Completed, statt beliebige Zeichenketten zu verwenden.

Eingebettete Dokumente mit Records

Records repräsentieren eingebettete Dokumente, die strukturierte Informationen enthalten, die keine eigene Identität benötigen. Verwenden Sie Records für komplexe Attribute wie:

Adresse: Kombination von Straße, Postleitzahl und Ort
Kontaktinformationen: Gruppierung von Telefon, E-Mail und Social-Media-Kennungen
Messwerte: Bündelung von Wert, Einheit und Genauigkeit

Records werden im Verzeichnis records/ definiert und können über mehrere Typen hinweg als komplexe Attributtypen wiederverwendet werden.

Schema-Validierung

Alle YAML-Dateien folgen JSON-Schemas, die unter https://schemas.meshmakers.cloud/ verfügbar sind. Zum Beispiel:

Schema für Construction-Kit-Elemente: https://schemas.meshmakers.cloud/construction-kit-elements.schema.json

Diese Schemas gewährleisten die Konsistenz und Gültigkeit Ihrer Construction-Kit-Definitionen während der Kompilierung.

Einen Construction Kit kompilieren

Bei Verwendung der Projektvorlage wird der Construction Kit automatisch kompiliert, wenn das Projekt gebaut wird.

Bei Verwendung des Compilers kann der Construction Kit mit dem folgenden Befehl kompiliert werden:

octo-ckc -c compile -p '<path of directory for construction kit>'

Der Compiler prüft die Konformität der Construction-Kit-Dateien mit den JSON-Schemadateien sowie die Konsistenz des Modells zu den Abhängigkeiten und innerhalb des Modells. Wenn die Construction-Kit-Dateien ungültig sind, wirft der Compiler einen Fehler.

Im Ordner ConstructionKit wird eine neue Datei mit dem Namen der Modell-ID erstellt.

Import nach OctoMesh

OctoMesh kann Construction Kits importieren. Der Import kann mit dem Werkzeug octo-cli durchgeführt werden. octo-cli ist ein Kommandozeilen-Werkzeug zur Verwaltung von OctoMesh als Administrator.

Um das Werkzeug zu installieren, verwenden Sie chocolatey oder den Windows Package Manager mit dem folgenden Befehl:

winget install -e --id meshmakers.octo-cli
# or
choco install octo-cli

octo-cli kann auch vom Download Center heruntergeladen werden.

Abhängig von der Installationsmethode von OctoMesh muss das Werkzeug so konfiguriert werden, dass es die korrekten Endpunkte verwendet. Der folgende Befehl konfiguriert das Werkzeug so, dass es die Standard-Endpunkte von OctoMesh verwendet:

octo-cli -c Config -asu "https://localhost:5001/" -isu "https://localhost:5003/" -bsu "https://localhost:5009/" -csu "https://localhost:5015" -tid "meshtest"

Hinweis: Der Parameter -tid definiert den verwendeten Tenant.

Als Nächstes muss das Werkzeug bei OctoMesh angemeldet werden. Der folgende Befehl meldet sich mit einem Administratorkonto bei OctoMesh an:

octo-cli -c Login -i

Optional: Erstellen Sie einen neuen Tenant in OctoMesh:

octo-cli -c Create -tid meshtest -db meshtest

Hinweis: Um Tenants zu löschen, verwenden Sie den folgenden Befehl:

octo-cli -c delete -tid meshtest

Nachdem der Tenant erstellt wurde, kann die API des Asset Repository genutzt werden, um auf die Daten des Tenants zuzugreifen. https://localhost:5001/tenants/meshtest/graphql/playground

Um einen Construction Kit zu importieren, verwenden Sie den folgenden Befehl:

octo-cli -c importck -f ./ck-sample2.yaml -w

Hinweis: Der Parameter -f definiert den Pfad zur Construction-Kit-Datei, die vom octo-ckc-Compiler erstellt wurde.