Skip to content

Entwicklerdokumentation

Dieser Artikel richtet sich ausschliesslich an Entwickler der CMI API.

Neuer Prozess-Layer

Jeder Prozess-Layer ist ein eigenes Projekt in der Solution CMI.API:

  1. Neues .NET Class Library Projekt erstellen. Name muss mit CMI.API.Process beginnen.
    • Wichtig dabei ist, dass das Projekt im Solutionordner "ProcessLayers" erstellt wird und sich das Projekt im Verzeichnis src\ProcessLayers\ befindet. Neues Projekt
  2. Im neu erstelltem .csproj folgendes anpassen:
    • Sdk zu Microsoft.NET.Sdk ändern
    • Die einzige PropertyGroup löschen (Framework, Nullable, etc. wird global gesteuert)
    • Projektreferenz zu CMI.API.Process.Contract hinzufügen
  3. Neue Klasse mit dem Namen [Prozesslayer-Name]ProcessLayer (Bsp. DummyProcessLayer) erstellen und von der abstrakten Klasse ProcessLayer erben
    • Methode AddServices: Hier können eigene Typen vom Prozess-Layer im IOC registiert werden
    • Property RouteName: Steuert wie die API Route aufgebaut wird für den Prozess-Layer. Bei "Dummy" ist die Route /Process/Dummy/...
    • Property FriendlyName: DisplayName welcher in der Config-UI angezeigt wird
    • Property IsKpfLayer: Muss auf true gesetzt werden, wenn der Prozess-Layer auf ein KPF Modell aufbaut Dokumentation.

Wurden die drei Schritte gemacht, so ist alles richtig konfiguriert. Der Prozess-Layer kann nun in der ConfigUI ausgewählt werden.

Regeln

  • Grundätzlich dürfen alle Nuget-Packages, welche sich im Directory.Packages.props befinden, verwendet werden. Neue Nuget-Packages dürfen ohne Absprache nicht verwendet werden.
  • Die einzige Projekt-Referenz darf nur zu CMI.API.Application und CMI.API.Domain existieren
  • Es dürfen keine Config-Erweiterungen (z.B. in appsettings.json) gemacht werden
  • Werden KPF-Felder in einem Prozess-Layer verwendet, so muss IsKpfLayer auf true gesetzt werden

Controller erstellen

Die Controller müssen von der abstrakten Klasse ProcessController ableiten. Der Inhalt des Controllers kann beliebig gestaltet werden.

Dabei müssen alle Endpunkte entsprechend dokumentiert sein. Ein Beispiel kann im Dummy-Projekt gefunden werden oder hier:

/// <summary>
/// Sucht nach Stammdatenobjekten und gibt diese zurueck.
/// </summary>
/// <param name="stammdatenType">Typ des Stammdatenobjekts</param>
/// <param name="take">Maximale Anzahl die gesucht werden soll</param>
/// <param name="tentaQl">TentaQL Query</param>
/// <response code="200">Objekte gefunden</response>
/// <response code="400">Ein Fehler bei der Abfrage ist aufgetreten</response>
/// <response code="401">Das Bearer-Token ist ungueltig</response>
/// <response code="404">Das Objekt mit der GUID wurde nicht gefunden</response>
/// <response code="500">Ein unerwarteter Fehler ist aufgetreten</response>
[HttpGet]
[ProducesResponseType((int)HttpStatusCode.OK)]
[ProducesResponseType(typeof(ApiErrorResponse), (int)HttpStatusCode.BadRequest)]
[ProducesResponseType(typeof(ApiErrorResponse), (int)HttpStatusCode.NotFound)]
[ProducesResponseType(typeof(ApiErrorResponse), (int)HttpStatusCode.InternalServerError)]
public async Task<IActionResult> Methode....

Die Swagger-Dokumentation wird automatisch erstellt.

Services / Typen im IOC

Eigene Typen können im IOC registriert werden. Dafür muss man diese in der Methode AddServices erfassen. Es wird Scoped, Transient und Singleton unterstützt.

GraphQL

Alle GraphQL-Queries (auch die generierten) basieren auf GraphQL-Version 2.

Wichtige Services

Es gibt bereits ein Set an Services die verwendet werden können (Diese befinden sich im CMI.API.Application.Common-Namespace):

  1. ICmiCUDRepository → Objekte in Metatool speichern, erstellen und löschen
  2. IObjectStoreItemRepository → Object-Store-Item erstellen, welches für das Speichern der Objekte benötigt wird
  3. ICmiDokumentRepository → Dokumentoperationen
  4. ICmiObjectReadRepository → GraphQL Service
  5. ICmiMenuRepository → Menüs abfragen / ausführen
  6. ICmiTemplateRepository → Objektvorlage auflösen

Model für IObjectStoreItemRepository / ICmiCUDRepository

Der IObjectStoreItemRepository braucht ein spezielles Model bzw. es müssen gewisse Attribute bei den Properties gesetzt sein, damit ein Object-Store-Item erstellt werden kann. Dies sind die Regeln:

  • Die Properties müssen gleich wie die Felder oder Assocs im Modell heissen
  • Das Property public long Version { get; set; } muss vorhanden sein und immer die aktuellste Objekt-Version haben
  • Das Property public Guid GUID { get; set; } muss vorhanden sein. Handelt es sich dabei um ein neues Objekt, so muss es mit Guid.Empty befüllt werden
    • Das Attribut [JsonConverter(typeof(JsonGuidConverter))] muss gesetzt sein
  • Die Property-Typen sind wie folgt zu setzten:
    • Zeitraum → string
    • Text → string
    • Numeric → float
    • Boolean → bool
    • ReferenzNummer → string
    • Document → EDokument (Dokumentoperationen müssen über ICmiDokumentService gemacht werden)
    • Enum → string
  • Felder vom Typ Zeitraum, Numeric, Enum müssen das Attribut FieldTypeAttribute mit dem entsprechenden FieldType enthalten
  • Handelt es sich bei dem Property um ein EDokument (z.B. Foto auf Kontakt), so muss das Attribut FieldIdAttribut mit der FieldID gesetzt sein (Dokumentoperationen müssen über ICmiDokumentService gemacht werden)
  • Assoziationen müssen vom Typ SimpleObject oder SimpleObject[] sein
    • Das Attribut [JsonConverter(typeof(ItemsConverter<SimpleObject>)] muss bei SimpleObject[] gesetzt sein

Ein Beispiel ist im Dummy-Projekt im Controller KontaktExampleController

Unit Tests

Unit-Tests müssen im Projekt CMI.API.Tests in einem eigenen Unterverzeichnis erstellt werden.

Dummy Prozess Layer

Das Projekt CMI.API.Process.Dummy dient als Beispielprojekt mit ein paar Beispielen.