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

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.Process.Contract existieren
  • Es drüfen keine Config-Erweiterungen (zum Bsp. in Appsettings.json) gemacht werden
  • Es dürfen keine KPF-Felder aus einem Prozess-Layer verwendet werden

Controller erstellen

Die Controller müssen von der abstrakte 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>
/// Such 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 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.

Wichtige Services

Es gibt bereits ein Set an Services die verwendet werden können (Diese befinden sich im CMI.API.Process.Contract.Services):

  1. ICmiCUDService => Objekte in Metatool speichern, erstellen und löschen
  2. ICmiDokumentService => Dokumentoperationen
  3. ICmiGraphQlService => GraphQL Service
  4. ICmiMenuService => Menues abfragen / ausführen
  5. ICmiTemplateService => Objektvorlage auflösen

Model für ICmiCudService

Der ICmiCudService braucht ein spezielles Model bzw. es müssen gewisse Attribute bei den Properties gesetzt sein, damit diese über den Service gespeichert werden können. 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 eine Guid.Empty befüllt werden
  • 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 entsprechendem FieldType enthalten
  • Handelt es sich bei dem Property um ein EDokument (Bsp 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

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.