KI-unterstützte Integration

Zweck

Diese Anleitung ist der verbindliche Einstiegspunkt für Codex, Claude und andere Coding-Assistenten, die MES Inside in eine bestehende Anwendung integrieren. Der Produktname lautet MES Inside, nicht MES Insight.

Maschinenlesbare Einstiegspunkte der jeweiligen Installation:

/llms.txt
/ai-integration.md

Die kurze Promptvorlage steht unter Drei-Zeilen-Prompt, die verbindliche Prüfung unter Abnahmecheckliste.

Auftrag an den Coding-Assistenten

Der Assistent soll eine kleine, additive Pilotintegration erstellen:

  1. Ziel-Framework und Webmodell erkennen.
  2. passende MES-Inside-Clientbibliotheken einbinden;
  3. mesinside.json ohne Secret anlegen;
  4. Client im Anwendungslifecycle starten und stoppen;
  5. einen fachlich geeigneten Vorgang messen;
  6. Fehler an einer zentralen Fehlergrenze zusätzlich melden;
  7. vorhandenes Logging und Fehlerverhalten unverändert lassen;
  8. Build und vorhandene Tests ausführen;
  9. manuelle Server- und Credential-Schritte dokumentieren.

Der Assistent darf keine bestehenden Logger entfernen und keine umfassende Instrumentierung ohne ausdrücklichen Auftrag durchführen.

Benötigte Angaben

Vor Beginn werden folgende Werte benötigt:

Wert Beispiel Geheim?
MES-Inside-API-URL https://inside.example.com/api/v1 nein
Tenant Example nein
Projekt CustomerPortal nein
Anwendung CustomerPortal.Web nein
Umgebung Test oder Production nein
Credential-Referenz customer-portal-test nein
API-Key wird außerhalb des Codes gesetzt ja

Der API-Key darf weder im Prompt noch in Quellcode, JSON, Git, Logausgabe, Screenshot oder Testfixture erscheinen.

Offizielle Pakete beziehen

Der Coding-Assistent verwendet ausschließlich den dokumentierten Feed:

https://git.mes.wien/api/packages/MES-Public/nuget/index.json

Aktuelle Pilotversion:

0.4.0-preview.3

Der Feed muss durch einen Administrator auf dem Entwicklungsrechner eingerichtet sein. Der Assistent fragt nicht nach einem Gitea-Token und verändert keine globalen Credentials. Er ermittelt mit dotnet nuget list source den lokalen Namen der Quelle mit dieser URL und verwendet ausschließlich diese Quelle für MES.Inside.*. Details stehen unter NuGet-Pakete.

Framework erkennen

ASP.NET Core / .NET 8 oder neuer

Erkennbar an Microsoft.NET.Sdk.Web, Program.cs, WebApplication.CreateBuilder und Dependency Injection.

Bevorzugte Installation:

dotnet add package MES.Inside.Client.AspNetCore `
  --version 0.4.0-preview.3 `
  --source MES-Public-Gitea

Dieses Einstiegspaket installiert automatisch:

  • MES.Inside.Contracts
  • MES.Inside.Configuration
  • MES.Inside.Client
  • MES.Inside.Client.AspNetCore
  • deren veröffentlichte Abhängigkeiten, insbesondere Newtonsoft.Json

Registrierung:

using MES.Inside.Client.AspNetCore;

builder.Services.AddMesInside(
    Path.Combine(builder.Environment.ContentRootPath,
        "App_Data", "MESInside", "mesinside.json"));

InsideClient kann anschließend über Dependency Injection bezogen werden. Der ASP.NET-Core-Adapter beendet und leert den Client beim kontrollierten Anwendungsstopp.

Für eine ASP.NET-Core-Anwendung ergänze nach dem Build der App und vor einer vorhandenen zentralen Exception-Middleware:

app.UseMesInsideExceptionLogging();
app.UseMesInsideRequestMonitoring();

Entferne oder ersetze dabei keinen vorhandenen Logger. Die MES-Inside- Exception-Middleware erfasst die Exception zusätzlich mit Trace-ID, wirft sie unverändert weiter und darf nicht hinter UseExceptionHandler platziert werden, wenn dort die Exception bereits vollständig behandelt wird.

Die Request-Middleware misst die gesamte serverseitige Laufzeit mit stabilen Routenbezeichnungen ohne Query-String. Sampling begrenzt normale Messungen; Fehler und langsame Requests bleiben entsprechend der Konfiguration erhalten.

ASP.NET WebForms / .NET Framework 4.8

Erkennbar an .aspx, Global.asax, System.Web und einem klassischen .NET-Framework-Projekt.

Bevorzugte Installation im Package-Manager-Fenster von Visual Studio:

Install-Package MES.Inside.Client.AspNetFramework `
  -Version 0.4.0-preview.3 `
  -Source MES-Public-Gitea

Dieses Einstiegspaket installiert automatisch:

  • MES.Inside.Contracts
  • MES.Inside.Configuration
  • MES.Inside.Client
  • MES.Inside.Client.AspNetFramework
  • deren veröffentlichte Abhängigkeiten, insbesondere Newtonsoft.Json

Lifecycle in Global.asax:

using System.IO;
using MES.Inside.Client.AspNetFramework;

protected void Application_Start(object sender, EventArgs e)
{
    MesInsideApplication.Start(
        Path.Combine(Server.MapPath("~/"),
            "App_Data", "MESInside", "mesinside.json"));
}

protected void Application_End(object sender, EventArgs e)
{
    MesInsideApplication.Stop();
}

Alternativ kann der WebForms-Adapter vollständig aus Web.config gestartet werden:

<appSettings>
  <add key="MES.Inside:ConfigurationPath" value="~/App_Data/MESInside/mesinside.json" />
  <add key="MES.Inside:ApiKey" value="nur-wenn-kein-Secret-Store-möglich-ist" />
  <add key="MES.Inside:LogEverything" value="true" />
</appSettings>
<system.webServer>
  <modules runAllManagedModulesForAllRequests="true">
    <add name="MesInsideHttpModule"
         type="MES.Inside.Client.AspNetFramework.MesInsideHttpModule, MES.Inside.Client.AspNetFramework" />
  </modules>
</system.webServer>

Dann genügt in Application_Start der Aufruf MesInsideApplication.Start(). LogEverything=true setzt das Trace-Sampling auf 100 Prozent. Das HTTP-Modul zeichnet dynamische Requests einschließlich Heap- und GC-Differenzen auf und schließt übliche statische Ressourcen aus. Der API-Key aus Web.config ist ein bewusst unterstützter Fallback; ein Secret Store oder die bestehende MES_INSIDE_CREDENTIAL_*-Umgebungsvariable bleibt empfohlen.

Die Runtime-Diagnose wird über den metrics-Abschnitt gesteuert:

"metrics": {
  "enabled": true,
  "aggregationIntervalSeconds": 30,
  "collectClrPerformanceCounters": true,
  "collectLargeObjectHeap": true,
  "collectPinnedObjects": true
},
"tracing": {
  "enabled": true,
  "samplingRate": 1.0,
  "excludeStaticResources": true,
  "captureHeapDelta": true,
  "captureSessionHash": true,
  "captureUserHash": false,
  "maximumDistinctPaths": 500
}

Periodische Performancewerte werden als atomarer RuntimeSnapshot übertragen und serverseitig als genau eine Zeile in RuntimeSnapshots gespeichert. Das gilt nicht nur für Webanwendungen: Jeder Prozess, der MES.Inside.Client verwendet, erhält den portablen Collector für Console-Apps, Worker, Windows-Dienste und Desktop-Anwendungen automatisch. Der Anwendungstyp kann in identity benannt werden:

"identity": {
  "applicationType": "Windows Service"
}

ASP.NET Core und der .NET-Framework-Webadapter setzen den Typ automatisch. Werte, die eine Runtime oder ein Betriebssystem nicht zuverlässig anbietet, bleiben im Snapshot leer; zusätzliche plattformspezifische numerische Werte landen begrenzt in additionalMetrics.

Die Auswertung befindet sich in der Administration unter Speicher. Sie zeigt Runtime-Metriken pro Prozess und Requests mit der größten Heap-Zunahme. Session- und Benutzerwerte verlassen die Anwendung ausschließlich als installationsbezogene SHA-256-Korrelation; Querystrings, Formulardaten, Cookies und Inhalte werden nicht aufgezeichnet.

Für ASP.NET Core auf .NET 8 oder höher steht derselbe Fallback zur Verfügung:

builder.Services.AddMesInsideWithApiKey(
    Path.Combine(builder.Environment.ContentRootPath, "mesinside.json"),
    builder.Configuration["MES.Inside:ApiKey"]!,
    builder.Configuration.GetValue<bool>("MES.Inside:LogEverything"));

Unbehandelte Fehler können in Application_Error zusätzlich protokolliert werden. Server.GetLastError() wird nicht verändert oder gelöscht.

Konfiguration anlegen

Empfohlener Pfad:

App_Data/MESInside/mesinside.json

Minimale Pilotkonfiguration:

{
  "schemaVersion": 1,
  "enabled": true,
  "identity": {
    "tenant": "{{TENANT}}",
    "project": "{{PROJECT}}",
    "application": "{{APPLICATION}}",
    "environment": "{{ENVIRONMENT}}"
  },
  "transport": {
    "mode": "InProcess",
    "apiUrl": "{{API_URL}}",
    "credentialReference": "{{CREDENTIAL_REFERENCE}}",
    "uploadIntervalSeconds": 30,
    "uploadTimeoutSeconds": 10
  },
  "spool": {
    "path": "spool",
    "maximumSizeMegabytes": 100,
    "segmentSizeMegabytes": 2,
    "segmentMaximumAgeSeconds": 30,
    "failedRetentionDays": 14
  },
  "logging": {
    "minimumLevel": "Information",
    "categoryOverrides": {}
  },
  "tracing": {
    "enabled": true,
    "samplingRate": 0.05,
    "slowRequestMilliseconds": 2000,
    "slowDatabaseMilliseconds": 500,
    "slowHttpMilliseconds": 1000,
    "alwaysKeepErrors": true,
    "alwaysKeepSlowOperations": true
  },
  "metrics": {
    "enabled": true,
    "aggregationIntervalSeconds": 30
  },
  "privacy": {
    "allowUserId": false,
    "allowIpAddress": false,
    "allowedProperties": [],
    "blockedPropertyPatterns": [
      "*Password*",
      "*Token*",
      "*Cookie*",
      "*Authorization*",
      "*Username*",
      "*Email*"
    ]
  }
}

Die Konfiguration und Spool müssen beim Deployment erhalten bleiben. Das App-Pool- beziehungsweise Prozesskonto benötigt Änderungsrechte auf App_Data/MESInside/spool, aber keine Rechte auf fremde Webverzeichnisse.

Credential bereitstellen

Aus der Credential-Referenz wird der Name der Umgebungsvariable gebildet:

MES_INSIDE_CREDENTIAL_<NORMALISIERTE_REFERENZ>

Die Referenz wird großgeschrieben; -, ., und : werden zu _.

Beispiel:

credentialReference: customer-portal-test
Umgebungsvariable:   MES_INSIDE_CREDENTIAL_CUSTOMER_PORTAL_TEST

Der Administrator:

  1. erzeugt im MES-Inside-Adminbereich einen API-Zugang für genau Tenant/Projekt/Anwendung/Umgebung;
  2. trägt den nur einmal angezeigten Key in die sichere Serverkonfiguration ein;
  3. startet den zugehörigen Prozess beziehungsweise Application Pool neu.

Der Coding-Assistent setzt oder liest den Klartext-Key nicht.

Unterstützte Erfassung

inside.Log(
    TelemetrySeverity.Information,
    "Order.Completed",
    "Order processing completed.");

inside.LogException(exception, "Order.Failed");

using (inside.Measure("Order.Process"))
{
    await ProcessOrderAsync();
}

inside.Counter("Order.Completed.Count");
inside.Gauge("Order.QueueLength", queueLength);

Regeln:

  • stabile, technische Ereignisnamen verwenden;
  • keine Benutzernamen, E-Mail-Adressen oder IPs in Eventnamen oder Metriknamen;
  • keine Passwörter, Tokens, Cookies, Authorization-Header, vollständigen Formulare oder Sessions übertragen;
  • Exceptions zusätzlich melden und anschließend bestehendes Fehlerverhalten beibehalten;
  • Measure um einen aussagekräftigen fachlichen Vorgang legen;
  • hochkardinale Werte nicht als Metriknamen verwenden.

Minimaler Pilot

Für die erste Änderung genügt:

  • ein erfolgreicher fachlicher Vorgang;
  • ein erwarteter Fehlerpfad oder eine zentrale Exception-Grenze;
  • eine Zeitmessung;
  • optional ein stabiler Counter.

Beispiel Login:

using (inside.Measure("Authentication.Login"))
{
    try
    {
        var result = await ExistingLoginAsync();
        inside.Log(
            result.Succeeded ? TelemetrySeverity.Information : TelemetrySeverity.Warning,
            result.Succeeded
                ? "Authentication.LoginSucceeded"
                : "Authentication.LoginFailed",
            result.Succeeded
                ? "Login completed successfully."
                : "Login was rejected.");
        inside.Counter(result.Succeeded
            ? "Authentication.LoginSucceeded.Count"
            : "Authentication.LoginFailed.Count");
        return result;
    }
    catch (Exception exception)
    {
        inside.LogException(exception, "Authentication.LoginException");
        throw;
    }
}

Keine Benutzerkennung und kein Kennwort werden dabei an MES Inside übergeben.

Verbindliche Nicht-Ziele

Der Coding-Assistent darf ohne gesonderten Auftrag nicht:

  • bestehendes Logging ersetzen oder entfernen;
  • Datenbanktabellen der Fachanwendung verändern;
  • MES Inside direkt mit der Fachanwendungsdatenbank verbinden;
  • synchron im Request an die MES-Inside-API senden;
  • Secrets in appsettings.json, web.config oder mesinside.json schreiben;
  • IP-Erfassung aktivieren;
  • vollständige Request-, Formular- oder Sessiondaten protokollieren;
  • geplante APIs für automatische Trace-Korrelation oder zentrale Clientverwaltung erfinden.

Technische Prüfung

Der Coding-Assistent führt mindestens aus:

  1. bestehende Solution vollständig bauen;
  2. vorhandene Tests ausführen;
  3. prüfen, dass alle MES-Inside-Abhängigkeiten im Publish-Ausgabeverzeichnis vorhanden sind;
  4. mesinside.json gegen das mitgelieferte Schema beziehungsweise Konfigurationswerkzeug validieren;
  5. sicherstellen, dass kein API-Key in Git oder Ausgabe enthalten ist;
  6. geänderte Dateien und verbleibende manuelle Serverarbeiten auflisten.

Laufzeitabnahme

Nach Deployment:

  1. Anwendung starten und Pilotvorgang auslösen.
  2. JSONL-Datei unter spool/ready beziehungsweise kurzzeitig sending beobachten.
  3. Prüfen, dass die Datei nach erfolgreicher Übertragung verschwindet.
  4. Ereignis, Counter und Dauer in /Admin/Events suchen.
  5. MES-Inside-API stoppen, weiteren Vorgang auslösen und sicherstellen, dass die Fachanwendung weiterläuft und der Batch lokal bleibt.
  6. API wieder starten und genau einmalige nachträgliche Übertragung prüfen.

Ergebnisbericht des Coding-Assistenten

Der Assistent berichtet:

  • erkanntes Framework und gewählten Adapter;
  • hinzugefügte Referenzen und Dateien;
  • instrumentierte Vorgänge und Ereignisnamen;
  • Build- und Testergebnis;
  • Pfad von Konfiguration und Spool;
  • Name der benötigten Umgebungsvariable, niemals deren Wert;
  • erforderliche IIS-, Linux- oder Container-Schritte;
  • bekannte Grenzen der Pilotintegration.