System Konfiguration

Konfiguration

Die Konfiguration erfolgt in der Datei appsettings.json. Die nachfolgenden Unterkapitel beschreiben jeweils einen Toplevel-Eintrag.

Hinweis: Pfadangaben müssen mit doppelte Backslashes geschrieben werden.

Konfiguration
Serilog
X-Forwarded Header
Api-Config
Mandant (Tenant)

Serilog

Die Serilog-Konfiguration. Serilog wird insbesondere für das File-Logging gebraucht. Dokumentation zu Serie-Log finden sie unter: https://serilog.net/

"Serilog": {
    "Using": [
      "Serilog.Sinks.Console",
      "Serilog.Sinks.File"
    ],
    "MinimumLevel": {
      "Default": "Information",
      "Override": {
        "CMI": "Information",
        "System": "Warning",
        "Microsoft": "Warning",
        "Microsoft.Hosting.Lifetime": "Information",
        "Microsoft.AspNetCore.Authentication": "Information"
      }
    },
    "WriteTo": [
      {
        "Name": "Console",
        "Args": {
          "theme": "Serilog.Sinks.SystemConsole.Themes.AnsiConsoleTheme::Code, Serilog.Sinks.Console",
          "outputTemplate": "[{Timestamp:HH:mm:ss} {Level}] <{ThreadId}> {SourceContext}{NewLine}{Message:lj}{NewLine}{Exception}{NewLine}"
        }
      },
      {
        "Name": "File",
        "Args": {
          "outputTemplate": "[{Timestamp:HH:mm:ss} {Level} <{ThreadId}> {SourceContext}] [t:{Tenant}] {Message:lj}{NewLine}{Exception}",
          "rollingInterval": "Day",
          "rollOnFileSizeLimit": true,
          "fileSizeLimitBytes": 1000000,
          "path": "..\\logs\\cmi-api-.log"
        }
      }
    ],
    "Enrich": [
      "FromLogContext",
      "WithMachineName",
      "WithThreadId"
    ],
    "Properties": {
      "Application": "CMI.API"
    }
  }

MinimumLevel.Default

Folgende Log-Levels werden unterstützt und die von uns empfohlen Werte sind bereits im Beispiel vorgegeben: Verbose Das Verbose Log-Level ist das Log-Level ist für die Fehleranalyse der Entwickler. Verbose log-Einträge beinhalten die Position im Code oder Dinge wie SQL Queries, Werte von Variablen, Längen von Listen und so weiter. Verbose als Log-Level wird sehr selten angezeigt.

Debug Debug ist das Log-Level für technische Informationen. Standardmäßig werden Log-Messages von diesem Log-Level auch nicht angezeigt. Hier werden zum Beispiel vorher/nachher Werte geloggt, welche relevant sein können beim Fehler finden.

Information Hier werden fachliche Informationen geloggt, beispielsweise wenn ein Dokument editiert wurde oder sonstige Dinge in diese Richtung, keine technischen Daten.

Warning Dinge, die im normalen Betrieb der Applikation nicht auftreten sollten. Dabei sollte die Bearbeitung nicht abbrechen. Beispiele: wenn ein bestimmter konfigurierter Wert nicht gesetzt werden konnte und deswegen der Default als Fallback verwendet werden musste.

Error Fehler die einen Abbruch der Aktion zur Folge haben, im Normalfall kein Benutzerfehler, sondern ein Applikationsfehler.

Fatal Fatale Ereignisse erfordern sofortige Aufmerksamkeit. Heisst in der Regel die Applikation kann nicht mehr genutzt werden.

WriteTo.Args.Path

Hier wird der Pfad zum Log-File gesetzt. Dabei kann der Pfad: ..\\logs\\cmi-api-.log überschireben werden Bsp.: C:\\temp\logs-cmi-api\cmi-api-.log Output: "C:\temp\logs-cmi-api\cmi-api-20220222.log"

Weitere Konfigurationen

Weitere Konfigurationsmöglichkeiten siehe https://github.com/serilog/serilog-settings-configuration.

X-Forwarded Header

Viele Proxies senden zusätzliche http-Header um die Herkunft einer Anfrage dem Zielsystem mitzuteilen:

Der Service kann konfiguriert werden, diese Header anstatt der Verbindungsinformationen des Proxies zu verwenden. Wenn keine Konfiguration vorgenommen wird, werden die Header nicht verwendet.

Das Verhalten zu den Forward-Headern wird in der Sektion ForwardedHeaders konfiguriert. Es stehen alle Optionen der Klasse ForwardedHeadersOptions zur Verfügung.

In diesem Abschnitt wird die Dokumentation der Klasse ForwardedHeadersOptions von Microsoft nicht wiederholt, es werden nur Konfigurationshinweise zu einigen Optionen dokumentiert.

ForwardedHeaders: Wenn mehrere Optionen dieses Flags verwendet werden sollen, können die Flags kommagetrennt aufgeführt werden. All aktiviert alle Optionen.
KnownProxies: Bekannte Proxies können als Array von Ip-Adressen angegeben werden.
KnownNetworks: Bekannte Netzwerke können als Array in der CIDR-Notation 0.0.0.0/0 / 0:0:0:0:0:0:0:0/0 angegeben werden.

{
  "ForwardedHeaders": {
    "ForwardedHeaders": "XForwardedFor, XForwardedHost, XForwardedProto",
    "KnownProxies": ["10.0.0.6", "10.0.0.7"],
    "KnownNetworks": [ "10.0.0.0/8", "::1/128"]
  }
}

Api-Config

{
  "ApiConfig": {
    "AutoRebootOnConfigChangeEnabled": true,
    "WebHookOnConfigChange": {
      "Uri": null,
      "HttpMethod": "Get"
    },
    "EnableMonitoring": true,
    "ClearMonitoringDataAfterXMinutes": 60
  }
}

AutoRebootOnConfigChangeEnabled

Mit der Einstellung AutoRebootOnConfigChangeEnabled lässt sich steuern, ob die API nach einer Änderung in irgendeinem Tenant automatisch neu gestartet werden soll. Wird bei einem Tenant etwas geändert, so startet die komplette API automatisch neu.

Diese Einstellung ist standardmässig true.

WebHookOnConfigChange

Mit der Einstellung WebHookOnConfigChange lässt sich steuern, ob die API nach einer Änderung in irgendeinem Tenant, einen Web Hook an die konfigurierte URL sendet (wenn WebHookOnConfigChange.Uri ungleich null).

WebHookOnConfigChange.Uri: URL des Web Hooks
WebHookOnConfigChange.HttpMethod: Http-Request-Methode, der Standardwert ist Get

Es wird ein Http-Response Status Code von >=200 und <=299 erwartet. Ist der Http-Request nicht erfolgreich, wird dem Benutzer gemeldet, dass das Speichern der Konfiguration nicht erfolgreich war. Die Änderungen wurden zwar persistiert, jedoch konnten externe Systeme nicht über die Änderung informiert werden.

EnableMonitoring

Mit der Einstellung EnableMonitoring lässt sich das Monitoring ein- und ausschalten.

ClearMonitoringDataAfterXMinutes

Mit der Einstellung ClearMonitoringDataAfterXMinutes lässt sich einstellen, wie lange die Monitoring-Daten gespeichert bleiben.

Mandant (Tenant)

"Tenants": {
    "dev": {
      "CmiStsUri": "[STS-URL]",
      "CmiStsClientId": "[STS-Client-ID]",
      "CmiPrivateUri": "[PROTOKOLL]://[DOMAIN]:[OWIN-PRIVATE-PORT]",
      "PathApiConfig": "[PATH]"
    },
    "test": {
      "CmiStsUri": "[STS-URL]",
      "CmiStsClientId": "[STS-Client-ID]",
      "CmiStsTenantId": "[STS-Tenant-ID]",
      "CmiPrivateUri": "[PROTOKOLL]://[DOMAIN]:[OWIN-PRIVATE-PORT]",
      "PathApiConfig": "[PATH]"
    }
  }

CmiStsUri

Url zum STS. Bei STS 3.0 inkl. Mandant angeben. Beispiel.: https://sts.cloud.ch/<MANDANT>/identity

CmiStsClientId

STS-3: ClientID für OpenId Connect flow. Der Client muss den Grant-Type "authorization_code" unterstützen.

CmiPrivateUri

Url zur Metatool API. Die Url muss auf dem Owin-Privateport gerichtet sein. Beispiel.: https://mandant.cmicloud.ch:10004

PathApiConfig

Path zum Kofigurationsfile der CMI API. Das File muss nicht existieren. Es muss jedoch sichergestellt werden, dass genügend Rechte vorhanden sind damit die API das File selbst erstellen kann. Beispiel.: C:\\CMI-API\\Mandant\\apiconfig.txt"