C4IT-F4SD-M42WebApi/docs/matrix42-26-1-extension-migration.md

Matrix42 26.1 Legacy Extension Migration

Diese Notizen dokumentieren die bisherigen Learnings aus der Migration einer alten Matrix42 Extension inklusive Custom Web Service auf eine Matrix42 26.1 Sandboxed Extension.

Die Anleitung ist bewusst als wiederverwendbare Checkliste fuer weitere Legacy-Pakete formuliert. Sie trennt zwischen belastbaren Ergebnissen, verworfenen Zwischenansaetzen und Punkten, die bei jeder Extension erneut geprueft werden muessen.

Zielbild

• Extension als .NET 8 Library mit Matrix42.WebApi.Contracts.
• Webservice-Controller von Matrix42.WebApi.Contracts.ApiController ableiten.
• Controller ueber Matrix42.Hosting.Contracts.IDependencyResolver konstruieren.
• Matrix42-Fachservices nur dort lazy aufloesen, wo sie wirklich gebraucht werden.
• Host-Konfig mit minimalen Modulen starten und gezielt erweitern.
• Paketbau in MSBuild/Visual Studio integrieren.
• Paketversion aus AssemblyVersion ableiten.
• Signing nur fuer eine eigene signed Build-Konfiguration aktivieren.
• Postman-Collection als Regressionstest fuer alte Client-URLs pflegen.

Ausgangspunkt

Bei einer Portierung eines alten Produktstands muss der Zielstand klar sein. Fuer diesen Branch war der relevante alte Stand 26eac54f94, nicht der spaetere neue Codezweig.

Wichtiges Learning: Bei einem 26.1-Kompatibilitaetsport keine neuen fachlichen Methoden, Obsolete-Markierungen oder Verhaltensaenderungen aus einem anderen Codezweig uebernehmen. Erst die alte Funktionalitaet lauffaehig machen, dann separate fachliche Aenderungen behandeln.

Basisprojekt

Bewaehrte Projekt-Eigenschaften:

<TargetFramework>net8.0</TargetFramework>
<OutputType>Library</OutputType>
<RuntimeIdentifiers>win-x64;linux-x64</RuntimeIdentifiers>
<AppendRuntimeIdentifierToOutputPath>true</AppendRuntimeIdentifierToOutputPath>
<Nullable>disable</Nullable>
<ImplicitUsings>disable</ImplicitUsings>
<GenerateAssemblyInfo>false</GenerateAssemblyInfo>
<EnableDefaultCompileItems>false</EnableDefaultCompileItems>
<M42ExtensionId>...</M42ExtensionId>
<M42AssemblyPattern>...</M42AssemblyPattern>
<M42BuildPackage>true</M42BuildPackage>

Referenzen auf Matrix42-DLLs sollen gegen die 26.1 Libraries zeigen und normalerweise Private=false haben, damit keine unnoetigen Matrix42-Plattform-DLLs ins Paket kopiert werden.

Die Host-Konfig muss exakt zum Assembly-Namen passen:

<AssemblyName>.dll.host.config

Paketbau

Das Paket wird ueber M42SandboxedExtension.targets gebaut.

Aktuelle Regeln in diesem Repo:

• Debug baut Debug-DLLs und ein Debug-Paket.
• Release baut ein unsigniertes Release-Paket.
• Release_signed baut ein Release-Paket und aktiviert M42SignAssemblies=true.
• Artefakte liegen getrennt nach Konfiguration unter artifacts/<Configuration>/.
• Die Package-Version wird aus der AssemblyVersion der gebauten WebApi-Assembly gelesen.
• M42PackageVersion wurde entfernt und soll nicht wieder eingefuehrt werden.

Die zentrale Version liegt in SharedAssemblyInfo.cs.

Beispiele:

dotnet build "C:\Workspace\C4IT FASD\F4SD_M42WebApi\C4IT - F4SD - M42WebApi.sln" -c Debug
dotnet build "C:\Workspace\C4IT FASD\F4SD_M42WebApi\C4IT - F4SD - M42WebApi.sln" -c Release
dotnet build "C:\Workspace\C4IT FASD\F4SD_M42WebApi\C4IT - F4SD - M42WebApi.sln" -c Release_signed

Visual Studio:

• Debug: Debugging und Testpakete.
• Release: Release ohne Signierung.
• Release_signed: Release mit Signierung.

Signierbare MSBuild-Properties:

/p:M42SignAssemblies=true
/p:M42SignTool="C:\Path\To\signtool.exe"
/p:M42SignCertificateThumbprint="<thumbprint>"
/p:M42SignCertificateFile="C:\Path\To\certificate.pfx"
/p:M42SignCertificatePassword="<password>"
/p:M42SignTimestampUrl="http://rfc3161timestamp.globalsign.com/advanced"
/p:M42SignOptions="/a"

Package-Struktur

Das neue Paket basiert auf einem PackageTemplate mit:

• package.json
• install.xml
• install/...
• BasePackage/Assemblies als Build-Ziel fuer Assemblies

Beim Portieren eines Legacy-Pakets:

1. Altes Paket entpacken.
2. WebAPI-Service (PLSLServiceTypeWebAPI) und Operationen (PLSLWebServiceOperation) identifizieren.
3. Extension-/Assembly-ID beibehalten, wenn ein Update statt einer Neuinstallation gewollt ist.
4. Operation-IDs nur dann aendern, wenn bewusst neue Operationen entstehen sollen.
5. Obsolete oder entfernte Schema-Attribute aus 26.1 entfernen.

Konkretes 26.1-Learning:

• UsedInTypeSPSActivityTypeAlert gibt es in 26.1 nicht mehr und muss aus dem Paket entfernt werden.

Host-Konfig und Module

Mit so wenig Modulen wie moeglich starten. Jedes zusaetzliche Modul kann transitive Unity-Registrierungen erzwingen, die bereits beim Controller- oder Service-Aufbau scheitern.

Minimaler Startpunkt fuer einfache Endpoints:

<?xml version="1.0" encoding="utf-8" ?>
<host xmlns="urn:m42/host.config">
  <modules>
    <module assembly="Matrix42.DataLayer.Persistence" />
  </modules>
  <sections></sections>
</host>

Der aktuelle Stand dieser Extension benoetigt fuer alle Funktionen mehr Module, insbesondere wegen Journal, Storage, Pandora, Teams Notification, ServiceConnection, Auth und Aurora Search. Aktuelle Host-Konfig:

<modules>
  <module assembly="C4ITF4SDM42WebApi" />
  <module assembly="Matrix42.DataLayer.Persistence" />
  <module assembly="Matrix42.Services.WebApi" />
  <module assembly="Matrix42.ServiceRepository.BizLogic" />
  <module assembly="Matrix42.Pandora.ServiceStore" />
  <module assembly="Matrix42.Pandora.Persistence" />
  <module assembly="Matrix42.Pandora.BizLogic" />
  <module assembly="Matrix42.Pandora.Services" />
  <module assembly="Matrix42.Distributed.Redis.Cache" />
  <module assembly="Matrix42.StorageService.BizLogic" />
  <module assembly="Matrix42.MsTeamsNotification.BizLogic" />
  <module assembly="Matrix42.ServiceConnection.Persistence" />
  <module assembly="Matrix42.Auth.BizLogic" />
  <module assembly="Matrix42.ServiceConnection.BizLogic" />
  <module assembly="Matrix42.Integration.Aurora.General" />
  <module assembly="Matrix42.Integration.Aurora.Search.BizLogic" />
  <module assembly="update4u.SPS.ComplianceRules.BizLogic" />
  <module assembly="update4u.SPS.Security" />
  <module assembly="Matrix42.BizLogic.Journal" />
  <module assembly="Matrix42.ServiceManager.BizLogic" />
</modules>

Regel: Wenn ein weiteres Interface nicht aufgeloest werden kann, nicht raten. In den Matrix42-DLLs nach dem Registrator/der Implementierung fuer genau dieses Interface suchen und nur das passende Modul laden.

Controller-Konstruktion

Nicht so:

public MyController(IEntityDataService entityDataService, IJournalService journalService, IPandoraUserProfile userProfile)

Das zwingt Unity, alle Services schon beim Erzeugen des Controllers aufzuloesen. Dadurch kann bereits isAlive scheitern, obwohl der Endpoint selbst keinen dieser Services braucht.

Bewaehrt:

private readonly IDependencyResolver _resolver;

public MyController(IDependencyResolver resolver, IEnumerationProvider enumerationProvider)
{
    _resolver = resolver ?? throw new ArgumentNullException(nameof(resolver));
    _enumerationProvider = enumerationProvider ?? throw new ArgumentNullException(nameof(enumerationProvider));
}

private T GetRequiredService<T>() where T : class
{
    var service = _resolver.TryGet<T>();
    if (service != null)
        return service;

    throw new InvalidOperationException($"Required Matrix42 service is not registered: {typeof(T).FullName}");
}

Fachservices im jeweiligen Endpoint oder Helper lazy aufloesen.

Dependency-Registrator

Die Extension kann eigene Sandbox-Registrierungen bereitstellen, wenn der Matrix42-Sandbox-Host eine Plattform-Instanz nicht selbst registriert.

Konkretes Learning:

• Fuer den Journal-Pfad fehlte System.Web.Http.Description.IApiExplorer.
• Die Extension registriert eine konkrete ApiExplorer-Instanz ueber IDependencyRegistrator.
• Das eigene Assembly muss dafuer als Host-Modul geladen werden.

Das ist kein Workaround im fachlichen Code, sondern eine Host-Registrierung fuer eine fehlende Infrastruktur-Dependency.

WebAPI-Rueckgaben

Matrix42 serialisiert HttpResponseMessage in dieser Runtime nicht wie klassische ASP.NET Web API, sondern als Nutzdatenobjekt.

Nicht fuer normale Datenendpoints verwenden:

Task<HttpResponseMessage>
HttpResponseExtensions.CreateResponse(...)

Symptom:

{"Version":"1.1","Content":{...},"StatusCode":200}

Bewaehrt:

• Datenendpoints geben direkte Nutzdaten zurueck, z. B. Task<List<T>>, Task<object> oder Task<EntityEnumeration>.
• Leere Listen duerfen nicht null sein.
• isAlive gibt IHttpActionResult mit StatusCodeResult(HttpStatusCode.NoContent) zurueck.

Healthcheck:

[Route("isAlive"), HttpGet]
public IHttpActionResult isAlive()
{
    return new StatusCodeResult(HttpStatusCode.NoContent);
}

Nicht verwenden:

public void isAlive()

Symptom:

{"result":null,"parameters":{}}

Null-Rueckgaben

Matrix42/Pandora behandelt null als fehlerhafte Operation-Response.

Symptom:

Method getTicketList returned null

Regel:

• Listenendpoints geben bei "nichts gefunden" new List<T>() zurueck.
• Objekte geben ein leeres DTO oder 204 zurueck, aber nicht unbewusst null.
• Strings koennen bei Bedarf string.Empty statt null liefern.

Routen und Parameterbindung

Wichtiges spaetes Learning: Der Matrix42 m42Services-Gateway kann Query-Parameter auch dann an die Methode binden, wenn die Controller-Route path-basierte Platzhalter hat.

Beispiel im Code:

[Route("getDirectLinkF4SD/{eoid}/{type}"), HttpGet]
public async Task<string> getDirectLinkF4SD(Guid eoid, string type)

Funktionierende Legacy-URL:

/m42Services/api/c4itf4sdwebapi/getdirectlinkf4sd/?eoid=<guid>&type=user

Daraus folgt fuer diese Migration:

• Controller nicht doppeln.
• Keine Query-Helper einbauen.
• Kein [FromUri] als Rettungsversuch verwenden, wenn das Matrix42-Binding ohnehin funktioniert.
• Die Postman-Collection testet bewusst die alten Query-Routen, damit Client-Kompatibilitaet erhalten bleibt.
• PLSLWebServiceOperation.RouteTemplate darf path-basiert sein, die alten Query-Aufrufe muessen trotzdem getestet werden.

Betroffene alte Testformate:

getTicketList?sid=...&hours=...&queueoption=...&queues=...
getDirectLinkCreateTicket?sid=...&assetname=...
getDirectLinkF4SD?eoid=...&type=...

Pickups und Enumerations

IEntityDataService.GetEnumeration(...) ist bequem, zieht aber Pandora-Services herein. Das war fuer reine Pickups zu schwer.

Bewaehrt:

Matrix42.Persistence.Contracts.IEnumerationProvider

Dieser Service kommt ueber Matrix42.DataLayer.Persistence und liefert eine DataTable. Wenn der alte API-Vertrag EntityEnumeration bleiben soll, muss die DataTable selbst gemappt werden.

Gepruefte Alternativen:

• Matrix42.Pandora.Contracts.IEntityDataService: liefert direkt EntityEnumeration, benoetigt aber Pandora-Module.
• update4u.SPS.DataLayer.Contracts.IPickupDataService: liefert ebenfalls DataTable, ohne klaren Vorteil gegenueber IEnumerationProvider.

Empfehlung:

• Fuer reine Pickup-Lesefunktionen IEnumerationProvider verwenden.
• Pandora nur laden, wenn ein Endpoint es wirklich benoetigt.

Aktueller Benutzer

IPandoraUserProfile nicht im Controller injizieren.

Fuer getMyRoleMemberships reicht der Matrix42 Principal:

var principal = Thread.CurrentPrincipal as IM42Principal;
var userId = principal?.InteractivePrincipal?.M42Identity?.UserFragmentID
    ?? principal?.M42Identity?.UserFragmentID
    ?? Guid.Empty;

Danach kann der vorhandene ASQL-/Helper-Code mit der Guid weiterarbeiten.

Ticket-Historie und Journal

Ziel: den Matrix42-Service nutzen, nicht eigene Journal-Logik nachbauen.

Finaler Ansatz:

• IJournalService ueber den Matrix42-Resolver laden.
• Keine direkte Konstruktion von JournalService.
• Keine eigenen DispatchProxy-/NoOp-Services.
• Keine HTTP-Weiterleitung an interne Admin-APIs.
• Keine Storage-Fallback-Journal-Implementierung als finaler Pfad.
• GetJournalList per Reflection gegen die zur Laufzeit vorhandene Signatur aufrufen, weil sich die Signatur zwischen 26.1 Patch-Leveln unterscheiden kann.

Warum Reflection hier akzeptiert wurde:

• Der alte direkte Compile-Time-MethodRef brach mit MissingMethodException.
• Die geladene Runtime-DLL hatte eine andere IJournalService.GetJournalList-Signatur.
• Die Reflection sucht kompatible Journal-Reader-Methoden und liefert klare Diagnose, wenn keine passende Signatur existiert.

Typische Fehler auf dem Weg:

Method not found: IJournalService.GetJournalList(...)
IJournalService could not be resolved
IExternalAuthService is an interface and cannot be constructed
IOAuth2AuthorizeService is an interface and cannot be constructed
IApiExplorer is an interface and cannot be constructed
IRequestPropertiesProvider is an interface and cannot be constructed
IExternalSearchService is an interface and cannot be constructed

Learning: Bei diesen Fehlern nicht weiter im Endpoint herumprobieren, sondern die fehlende Host-Registrierung bzw. das passende Matrix42-Modul identifizieren.

Overview-Endpoints

getTicketOverviewCounts liefert Counts fuer mehrere Keys.

getTicketOverviewRelations nimmt genau einen key und ein count.

Postman-Learning:

• getTicketOverviewCounts personal und getTicketOverviewCounts role leiten scope, overviewKey und overviewRelationExpectedCount ab.
• getTicketOverviewRelations nutzt diese Variablen.
• Der Relations-Test erwartet, dass response.length dem vorher abgeleiteten Count entspricht.
• Im normalen Collection-Lauf ueberschreibt role die Werte von personal, weil role nach personal ausgefuehrt wird.

Direct Link

Fuer F4SD Direct Links ist der Typ in der alten Integration nicht der Matrix42 ActivityType, sondern der F4SD-Typ.

Postman setzt deshalb nach getTicketList:

pm.collectionVariables.set("type", "ticket");

objectType bleibt separat auf ticket.ActivityType, falls der technische Matrix42-Typ fuer andere Tests gebraucht wird.

Postman-Collection

Die Collection ist Teil der Migration und Regression.

Regeln:

• Basic Auth ueber Variablen basicUsername und basicPassword.
• baseUrl enthaelt /m42Services.
• Legacy-Query-Routen testen, nicht nur neue path-basierte Formen.
• getTicketList zieht eoid und ticketObjectId aus TicketObjectId.
• type fuer Direct Link bleibt ticket.
• isAlive erwartet 204 und keinen Body.
• Allgemeiner Test erkennt versehentlich serialisierte HttpResponseMessage-Objekte.

Smoke-Test-Reihenfolge

Nach jeder Paketinstallation:

1. GET /m42Services/api/<prefix>/isalive Erwartung: HTTP 204 No Content.
2. GET /m42Services/api/<prefix>/getpickup/<PickupName> Erwartung: JSON-Nutzdaten, keine HttpResponseMessage-Huelle.
3. GET /m42Services/api/<prefix>/getMyRoleMemberships Erwartung: aktueller Benutzer und Rollen, kein IPandoraUserProfile-Fehler.
4. GET /m42Services/api/<prefix>/getTicketList?... Erwartung: leere Liste oder Tickets, aber kein returned null.
5. Direct Links mit Legacy-Query-Routen.
6. Overview Counts und Relations.
7. Journal-/History-Endpoints zuletzt, weil hier die meisten Matrix42-Services transitiv benoetigt werden.

Typische Fehlersymptome

Cannot create instance of <Controller>: The current type, <Interface>, is an interface and cannot be constructed.

Meist direkte Konstruktor-Injection oder fehlendes Host-Modul.

Could not load type 'System.Web.Routing.RouteTable'

Ungeeignetes altes System.Web-/WebApi-Modul in der Sandbox. Ursache entfernen, nicht weitere Alt-Abhaengigkeiten nachladen.

IApiExplorer is an interface and cannot be constructed

Sandbox-Host stellt diese WebApi-Explorer-Instanz nicht automatisch bereit. Ueber eigenen IDependencyRegistrator registrieren.

{"Version":"1.1","Content":{...},"StatusCode":200}

Ein HttpResponseMessage wurde als DTO serialisiert. Rueckgabe auf direkten Nutzdatentyp umstellen.

{"result":null,"parameters":{}}

Void-Endpoint oder falsch behandelte leere Rueckgabe. Fuer NoContent StatusCodeResult(HttpStatusCode.NoContent) nutzen.

Method <name> returned null

Endpoint gibt null zurueck. Leeres DTO oder leere Liste zurueckgeben.

Verworfene Zwischenansaetze

Diese Ansaetze haben nicht nachhaltig geholfen und sollen nicht erneut aufgebaut werden:

• Matrix42-Fachinterfaces direkt im Controller-Konstruktor injizieren.
• Immer mehr Module auf Vorrat laden, ohne die konkrete fehlende Registrierung zu kennen.
• HttpResponseMessage als Datenantwort verwenden.
• Query-Parameter per eigenem Helper aus RequestUri lesen.
• [FromUri] pauschal an alle GET-Parameter setzen.
• JournalService direkt konstruieren.
• NoOp-/Proxy-Abhaengigkeiten fuer Journal-Services erzeugen.
• Journal-Historie aus unvollstaendigen Kommentarfeldern nachbauen.
• Interne Matrix42 Admin-Webservices als finalen Journal-Pfad weiterleiten.

Migrationsablauf fuer weitere Extensions

1. Ziel-Commit der Legacy-Funktionalitaet festlegen.
2. Altes Paket entpacken und IDs dokumentieren.
3. Herstellerbeispiel/Scaffolder-Struktur als 26.1-Referenz verwenden.
4. Projekt auf .NET 8 und Matrix42.WebApi.Contracts.ApiController umstellen.
5. Controller-Konstruktor auf minimale Infrastruktur-Services reduzieren.
6. Host-Konfig minimal starten.
7. Package-Build in MSBuild integrieren.
8. AssemblyVersion als einzige Package-Versionsquelle verwenden.
9. WebAPI-Rueckgaben auf direkte DTOs/Listen umstellen.
10. isAlive auf echten 204 umstellen.
11. Pickups zuerst ueber schlanke Services loesen.
12. Komplexe Matrix42-Services erst bei Bedarf laden.
13. Bei Unity-Fehlern konkrete Implementierung/Registrator suchen.
14. Postman-Collection fuer alte Client-Routen aufbauen.
15. Paket installieren, Service synchronisieren und Smoke-Tests ausfuehren.
16. Erst nach erfolgreicher Kompatibilitaet fachliche Weiterentwicklungen einbringen.

Git- und Datei-Hinweise

• Vor Aenderungen git status pruefen.
• Unrelated/untracked Dateien nicht mitcommitten.
• Textdateien in diesem Repo mit CRLF speichern.
• .dat-Dateien behalten ihren UTF-8-BOM.
• Controller-/JSON-Dateien ohne unnoetigen BOM lassen.
• Debug-Build fuer Debugging, Release/Release_signed fuer Auslieferung.
• Postman-Collection nach JSON-Aenderungen immer parsen/validieren.