Power Pages Favoriten mit Batch-GUIDs und Server Logic

Inhalt

• Warum eine Favoritenseite keine Einzelrequests pro GUID braucht
• Wie post() drei Power Pages Operationen trennt
• Wie TypeScript den dritten Request Vertrag abbildet
• Wie Server Logic einen GUID Batch prüft
• Wie gültige GUIDs normalisiert und dedupliziert werden
• Warum ein Batch nur Center oder Flächen enthält
• Wie eine OData Abfrage mehrere GUIDs lädt
• Wie Einzelabruf und Batch dieselbe DTO Auflösung nutzen
• Wie results notFoundIds und invalidIds getrennt bleiben
• Welche Reihenfolge die Favoritenseite erhält
• Wie Liquid und HTTP denselben Kern verwenden
• Power Pages Favoriten im Enterprise-Projekt

Warum eine Favoritenseite keine Einzelrequests pro GUID braucht

Eine Favoritenseite besitzt bereits die IDs ihrer Einträge. Sie braucht keine vollständige Freitextsuche.

Ein Request pro GUID wäre trotzdem die falsche Grenze. Jeder Aufruf müsste Sprache, Autorisierung, Dataverse Zugriff, Mapping und Fehlerbehandlung erneut durchlaufen.

Meine Server Logic akzeptiert deshalb einen Batch mit bis zu 50 GUIDs. Der Aufrufer wählt vorher, ob der Batch Center oder Flächen enthält.

Wie post() drei Power Pages Operationen trennt

Der gemeinsame HTTP Endpunkt verwendet einen Discriminator. post() prüft zuerst die Operation und delegiert danach an den passenden Handler.

function post() {
  const payload = readBrowserPayload();

  if (payload.operation === OPERATIONS.SEARCH) {
    return postSearch(payload);
  }
  if (payload.operation === OPERATIONS.SUGGEST) {
    return postSuggest(payload);
  }
  return postPortalCatalogDetails(payload);
}

Der gemeinsame HTTP-Endpunkt besitzt damit drei Anwendungsfälle. search verarbeitet Filter. suggest liefert kleine Vorschlagslisten. getPortalCatalogDetails lädt bekannte IDs für Detail- oder Favoritenansichten.

Der Discriminator bestimmt den Vertrag vor jeder fachlichen Verarbeitung. Ein großer Request-Typ mit optionalen Such-, Suggest- und Detailfeldern würde ungültige Kombinationen zulassen.

Wie TypeScript den dritten Request Vertrag abbildet

Der vollständige TypeScript Vertrag bildet die drei HTTP POST Operationen als Union ab.

interface PortalCatalogDetailsServerLogicRequest {
  readonly operation: 'getPortalCatalogDetails';
  readonly entityType: 'center' | 'area';
  readonly ids: readonly string[];
  readonly languageCode: 'de' | 'de-DE' | 'en' | 'en-US' | 'en-GB';
}

type ServerLogicRequest = SearchServerLogicRequest | SuggestServerLogicRequest | PortalCatalogDetailsServerLogicRequest;

Der Typ beschreibt den Browservertrag. Er ersetzt keine Laufzeitprüfung.

ids bleibt ein String-Array, weil TypeScript kein geprüftes GUID Format aus Netzwerkdaten erzeugt. Server Logic prüft jedes Mitglied erneut.

Wie Server Logic einen GUID Batch prüft

Der HTTP Request benennt Operation, Entitätstyp, IDs und Sprache ausdrücklich.

{
  "operation": "getPortalCatalogDetails",
  "entityType": "center",
  "ids": ["20a6ceef-3e97-e911-a81b-000d3ab2de70", "674f37ec-5494-ea11-a811-000d3abae3d9"],
  "languageCode": "de-DE"
}

Server Logic prüft den Batch vor dem Custom API Aufruf.

1. Nur operation, entityType, ids und languageCode sind erlaubt.
2. entityType akzeptiert nur center oder area.
3. ids muss ein Array mit 1 bis 50 Mitgliedern sein.
4. Jedes Mitglied muss ein String sein.
5. Nicht unterstützte Sprachcodes beenden den Request.
6. Unbekannte Felder beenden den Batch vor dem Custom API Aufruf.

Search-Filter und Batch-Details besitzen bewusst unterschiedliche Fehlermodelle. Unbekannte optionale Suchfilter bleiben wirkungslos. Ein Batch mit unbekannten Vertragsfeldern wird abgelehnt.

Bei Favoriten darf ein Tippfehler nicht still wie eine leere Auswahl aussehen.

Wie gültige GUIDs normalisiert und dedupliziert werden

Jede Eingabe wird dekodiert, getrimmt und als GUID geprüft. Ungültige Werte bleiben sichtbar, damit die Favoritenseite ihren lokalen Zustand bereinigen kann.

for (const originalId of payload.ids) {
  const decodedId = decodeURIComponent(originalId).trim();

  if (!isGuid(decodedId)) {
    invalidIds.push(originalId);
    continue;
  }

  const normalizedId = decodedId.toLowerCase();
  if (!ids.includes(normalizedId)) {
    ids.push(normalizedId);
  }
}

Ungültige GUID Strings beenden nicht den gesamten Batch. Sie bleiben als invalidIds sichtbar.

Gültige GUIDs werden kleingeschrieben. Doppelte Werte bleiben nur einmal in der Abfrage. Die erste Position bestimmt die spätere Ergebnisreihenfolge.

Warum ein Batch nur Center oder Flächen enthält

Ein Batch mischt keine Center und Flächen.

Diese Grenze hält Filter und Antworttyp eindeutig. Ein Center Batch erzeugt objectfilter. Ein Area Batch erzeugt areafilter. Die Antwort besitzt denselben entityType Discriminator.

Eine Favoritenseite mit beiden Typen führt zwei klare Requests aus. Sie sendet keinen gemischten Vertrag, dessen Ergebnis jedes Element erneut kennzeichnen müsste.

Wie eine OData Abfrage mehrere GUIDs lädt

Server Logic baut aus den eindeutigen GUIDs eine OData Filterliste. Die IDs stammen zu diesem Zeitpunkt bereits aus der Prüfung.

const clauses = ids.map((id) => '(id eq ' + id + ')');
const filter = '$filter=' + clauses.join(' or ');

if (entityType === 'center') {
  apiPayload.objectfilter = filter;
} else {
  apiPayload.areafilter = filter;
}

Der Custom API Aufruf erfolgt einmal für den gesamten Batch. Die Dataverse Antwort wird danach anhand der geprüften IDs indiziert.

Wie Einzelabruf und Batch dieselbe DTO Auflösung nutzen

Der Einzelabruf und der Batch besitzen keine getrennten DTO Mapper. Beide verwenden dieselben Indizes und dieselben Beziehungsprüfungen.

Der vorherige Beitrag zur Power Pages Detailsuche mit GUID und Liquid zeigt diese Auflösung für ein Center und eine Fläche.

Diese Wiederverwendung verhindert zwei ähnliche, aber unterschiedlich strenge Detailverträge.

Wie results notFoundIds und invalidIds getrennt bleiben

Der Batch unterscheidet gefundene DTOs, gültige GUIDs ohne Datensatz und syntaktisch ungültige Eingaben.

type PortalCatalogDetailsData =
  | {
      readonly entityType: 'center';
      readonly results: readonly PortalCatalogCenterDetail[];
      readonly notFoundIds: readonly string[];
      readonly invalidIds: readonly string[];
    }
  | {
      readonly entityType: 'area';
      readonly results: readonly PortalCatalogAreaDetail[];
      readonly notFoundIds: readonly string[];
      readonly invalidIds: readonly string[];
    };

Welche Reihenfolge die Favoritenseite erhält

results folgt der Reihenfolge der eindeutigen gültigen Eingabe-IDs. Nicht gefundene IDs werden ausgelassen und separat in notFoundIds gesammelt.

Die Reihenfolge der Dataverse Listen entscheidet nicht über die Favoritenansicht. Server Logic iteriert über den normalisierten Request und liest die DTOs aus einem ID-Index.

Wenn nach der Prüfung keine gültige GUID verbleibt, erfolgt kein Custom API Aufruf. Die Antwort enthält leere results und notFoundIds sowie die gesammelten invalidIds.

Wie Liquid und HTTP denselben Kern verwenden

Der Browser sendet den Batch mit einem CSRF-geschützten POST. Microsoft zeigt dafür shell.safeAjax in der Dokumentation zum Aufruf von Server Logic aus Client Script.

Liquid kann dieselbe Batch-Funktion über den dokumentierten serverlogic Tag aufrufen. Der Liquid Input enthält kein operation Feld, weil der Funktionsname bereits im Tag steht.

Beide Adapter führen anschließend normalizeBatchDetailRequest und executePortalCatalogDetails aus. Die fachliche Verarbeitung bleibt identisch.

Power Pages Favoriten im Enterprise-Projekt

Der Batch ist kein schnellerer Ersatz für jede Suche. Er löst einen klaren Fall. Die IDs sind bereits bekannt und sollen mit einem kontrollierten Request in aktuelle Detaildaten übersetzt werden.

Durch die dritte POST Operation bleibt dieser Fall vom Freitext und von Auto-Suggest getrennt. Die Antwort macht ungültige, fehlende und gefundene Favoriten einzeln sichtbar.

Die Architekturübersicht der Power Pages Enterprise-Suche ordnet alle drei POST Operationen und die separaten Liquid Aufrufe in den Gesamtfluss ein.

Die ECE Fallstudie zur Power Pages Enterprise-Suche ordnet den Batch in den Projektkontext ein. Der Batch löst bekannte Favoriten-IDs in Detaildaten auf. Das Speichern der Auswahl ist eine separate Aufgabe der Favoritenansicht.

Du baust eine Power Pages Favoritenseite oder einen gespeicherten Suchzustand mit Dataverse Daten? Im Power Pages Pro-Code Bereich zeige ich, wie ich Batch-Verträge, Fehlerzustände und Server Logic Grenzen vor der Entwicklung festlege.