# 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 parallele Pflege der Legacy- und Sandbox-Varianten sowie der manuelle TFS-Rueckweg sind in `docs/legacy-sandbox-development.md` beschrieben.

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:

```xml
<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:

```text
<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:

```powershell
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.

Bei `Release_signed` werden alle Paket-DLLs in einem einzigen `signtool sign`-Aufruf signiert.
Das vermeidet eine separate Passwortabfrage pro DLL, wenn das Zertifikat interaktiv entsperrt werden muss.

Signierbare MSBuild-Properties:

```powershell
/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/...`
- `uninstall.xml`
- `uninstall/...`
- `uninstall_data.xml`
- `BasePackage/Assemblies` als Build-Ziel fuer Assemblies

### Deinstallation

Eine Sandboxed Extension unterstuetzt die Matrix42-Paketdeinstallation nur, wenn das Paket eigene Uninstall-Skripte mitliefert. Fuer dieses Paket gilt:

- `uninstall.xml` entfernt den WebAPI-Service, alle eigenen Webservice-Operationen, Actions, Data Queries, die F4SD-Navigation, den F4SD-Quick-Call, die F4SD-Rolle und die eigene Lokalisierung.
- Die vier globalen C4IT-Navigationseintraege werden nicht entfernt, weil sie von weiteren C4IT-Paketen gemeinsam verwendet werden koennen.
- Schema, Pickup-Werte, Konfigurationseintrag, Dataset-Views und Previews bleiben als Konfigurationsdaten bestehen. Deshalb ist `uninstall_data.xml` absichtlich leer.
- Der abschliessende Post-Schritt entfernt die `dat`-Eintraege dieses Pakets aus `SchemaScripts`, damit eine spaetere Neuinstallation die Installationsskripte erneut ausfuehren kann.
- Jede `.del`-Datei verwendet nur eine aus dem Installationsobjekt oder einem Matrix42-Herstellerpaket verifizierte Kombination aus `ObjectId` und `TypeId`. Typ-IDs duerfen nicht geraten werden.
- Bei einer migrierten WebAPI koennen bereits vor dem Merge durch "Service synchronisieren" erzeugte Operationen mit neuen IDs existieren. Der Operation-Uninstall muss deshalb sowohl die beibehaltenen Legacy-/Paket-IDs als auch die IDs aus dem synchronisierten Matrix42-Export enthalten.
- Entfernte Legacy-Operationen muessen ebenfalls vor dem Service geloescht werden. Andernfalls verhindert der Fremdschluessel von `PLSLWebServiceOperation.Service` die Deinstallation des WebAPI-Service.

Beim Hinzufuegen eines paket-eigenen Objekts muss immer geprueft werden, ob auch `uninstall.xml`, eine passende `.del`-Datei und `UnregisterInstallScripts_Sobu.post` erweitert werden muessen.

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.
6. Nach der ersten lauffaehigen Version die Webservice-Operationen in Matrix42 synchronisieren, exportieren und die synchronisierten Contracts in die Paketdateien mergen.

Wichtiges finales Learning zu Webservice-Operationen:

- Wenn ein Endpoint nur nach "Service synchronisieren" korrekt funktioniert, sind die `PLSLWebServiceOperation`-Contracts im Paket nicht mehr synchron zum Controller.
- Die synchronisierten Operationen exportieren und mit den bestehenden Paketdateien mergen.
- Bestehende `PLSLWebServiceOperation.ID`s nicht durch Export-IDs ersetzen, sonst entstehen auf Bestandssystemen doppelte Operationen.
- Bestehende `PDRAudienceClass.ID`s ebenfalls erhalten.
- Nur fachliche Operation-Felder uebernehmen: `ResponseContract`, `RequestContract`, `Name`, `RouteTemplate`, `SupportedOperation`, `Type`, `IsPublic`.
- Neue Operationen, die bisher nicht im Paket vorhanden waren, duerfen die exportierten IDs verwenden, wenn sie aus dem Zielsystem stammen, auf dem sie bereits synchronisiert wurden.
- Operation-Dateien nach Operation benennen, z. B. `getticketlist.dat`, `getpickup.dat`, `isalive.dat`. Das erleichtert Reviews und verhindert Verwechslungen mit generischen `02-01-xxxx PLSLWebServiceOperationType.dat`-Dateien.
- Jede Datei aus `PackageTemplate/install/0002_WebServiceOperation` muss in `PackageTemplate/install.xml` referenziert sein.

Validierung:

```powershell
# XML parsebar?
python -c "import pathlib,xml.etree.ElementTree as ET; [ET.parse(p) for p in pathlib.Path('PackageTemplate/install/0002_WebServiceOperation').glob('*.dat')]"

# Debug-Paket bauen und pruefen, ob alle Operation-Dateien im Paket liegen
dotnet build "C:\Workspace\C4IT FASD\F4SD_M42WebApi\C4IT - F4SD - M42WebApi.sln" -c Debug
```

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
<?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:

```xml
<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:

```csharp
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:

```csharp
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:

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

Symptom:

```json
{"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 einem expliziten HTTP-204-Response zurueck.

Healthcheck:

```csharp
[Route("isAlive"), HttpGet]
public IHttpActionResult isAlive()
{
    var response = new HttpResponseMessage(HttpStatusCode.NoContent)
    {
        RequestMessage = Request
    };
    response.Headers.ConnectionClose = true;

    return ResponseMessage(response);
}
```

Nicht verwenden:

```csharp
public void isAlive()
```

Symptom:

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

## Null-Rueckgaben

Matrix42/Pandora behandelt `null` als fehlerhafte Operation-Response.

Symptom:

```text
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

Finales Learning: Fuer Legacy-Kompatibilitaet muessen Route, `PLSLWebServiceOperation.RouteTemplate`, `[FromUri]` und die alten Client-URLs zusammen betrachtet werden.

Bewaehrte Regeln:

- Die Route-Attribute aus der funktionierenden Legacy-Version uebernehmen.
- Query-basierte Legacy-Endpoints bleiben query-basiert, z. B. `[Route("getTicketList")]`.
- Path-basierte Legacy-Endpoints bleiben path-basiert, z. B. `[Route("getPickup/{name}")]`.
- GET-Parameter mit `[FromUri]` markieren.
- Zusaetzlich einen kleinen zentralen Query-Fallback verwenden, weil in 26.1 einzelne optionale Queryparameter trotz `[FromUri]` nicht immer in der Methode ankamen.
- Keine doppelten Controller-Methoden fuer alte und neue URL-Formen bauen.
- Die Postman-Collection testet bewusst die alten Client-URLs.

Beispiel Query-Route:

```csharp
[Route("getDirectLinkCreateTicket"), HttpGet]
public async Task<DirectLink> getDirectLinkCreateTicket(
    [FromUri] string sid = "",
    [FromUri] string assetname = "")
{
    sid = QueryValue(sid, nameof(sid));
    assetname = QueryValue(assetname, nameof(assetname));
    ...
}
```

Beispiel Path-Route mit zusaetzlichen Queryparametern:

```csharp
[Route("getPickup/{name}"), HttpGet]
public async Task<EntityEnumeration> getPickup(
    [FromUri] string name,
    [FromUri] EntityEnumerationVisibilityMode mode = EntityEnumerationVisibilityMode.None,
    [FromUri] int group = -1)
{
    name = QueryValue(name, nameof(name));
    mode = QueryValue(mode, nameof(mode));
    group = QueryValue(group, nameof(group));
    ...
}
```

Der zentrale Query-Fallback ist bewusst klein und verwendet die strukturierte WebAPI-API statt eigenes URL-Parsen:

```csharp
private string GetQueryValue(string name)
{
    return Request?.GetQueryNameValuePairs()
        .FirstOrDefault(pair => string.Equals(pair.Key, name, StringComparison.OrdinalIgnoreCase))
        .Value;
}

private string QueryValue(string value, string name)
{
    return GetQueryValue(name) ?? value ?? string.Empty;
}
```

Betroffene alte Testformate:

```text
getTicketList?sid=...&hours=...&queueoption=...&queues=...
getDirectLinkCreateTicket?sid=...&assetname=...
getDirectLinkF4SD?eoid=...&type=...
getPickup/<name>?mode=...&group=...
```

## Pickups und Enumerations

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

Bewaehrt:

```csharp
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:

```csharp
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:

```text
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`:

```javascript
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

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

Meist direkte Konstruktor-Injection oder fehlendes Host-Modul.

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

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

```text
IApiExplorer is an interface and cannot be constructed
```

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

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

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

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

Void-Endpoint oder falsch behandelte leere Rueckgabe. Fuer NoContent einen `IHttpActionResult` mit HTTP 204 liefern.

```text
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.
- Doppelte Controller-Methoden fuer alte Query-URLs und neue Path-URLs bauen.
- `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. Controller-Routen aus der funktionierenden Legacy-Version uebernehmen.
12. GET-Parameter mit `[FromUri]` versehen und fehlende Querywerte zentral ueber `Request.GetQueryNameValuePairs()` nachziehen.
13. Pickups zuerst ueber schlanke Services loesen.
14. Komplexe Matrix42-Services erst bei Bedarf laden.
15. Bei Unity-Fehlern konkrete Implementierung/Registrator suchen.
16. Webservice-Operationen nach erfolgreicher Installation in Matrix42 synchronisieren.
17. Synchronisierte Operationen exportieren und in die Paketdateien mergen, ohne bestehende IDs zu ersetzen.
18. Operation-Dateien sprechend nach Operation benennen und in `install.xml` referenzieren.
19. Postman-Collection fuer alte Client-Routen aufbauen.
20. Paket installieren, Service synchronisieren und Smoke-Tests ausfuehren.
21. 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.