Power Pages Detailsuche mit GUID, Server Logic und Liquid

Inhalt

• Warum eine GUID den Detailtyp nicht beschreibt
• Wie der Browser die GUID an Liquid übergibt
• Wie Microsoft Server Logic aus Liquid aufruft
• Wie Server Logic den Einzelabruf prüft
• Wie Center und Fläche unterschiedliche OData Filter erhalten
• Warum die Dataverse Antwort noch kein Liquid Vertrag ist
• Wie Server Logic den Dataverse Antwortgraphen auflöst
• Welche Form Center und Area DTOs besitzen
• Wie Liquid drei Ergebniszustände trennt
• Warum aufgelöste DTOs Web Templates vereinfachen
• Power Pages Detailsuche im Enterprise-Projekt

Warum eine GUID den Detailtyp nicht beschreibt

Eine Ergebnisliste liefert eine GUID. Eine Detailseite braucht zusätzlich die Information, ob diese GUID ein Center oder eine Fläche bezeichnet.

{
  "entityType": "area",
  "id": "674f37ec-5494-ea11-a811-000d3abae3d9",
  "languageCode": "de-DE"
}

Eine GUID benennt den Datensatz. Sie beschreibt nicht, in welcher Ergebnisliste die Custom API suchen soll.

Meine Server Logic verlangt deshalb zusätzlich entityType. Der Wert center erzeugt einen Filter für Objekte. Der Wert area erzeugt einen Filter für Flächen.

Diese Trennung ist fachlich notwendig. Dieselbe technische GUID Form kann in unterschiedlichen Dataverse Tabellen vorkommen. Der Browser darf den Typ nicht aus einem zufälligen Treffer ableiten.

Wie der Browser die GUID an Liquid übergibt

Der Browser liefert nur den Query-Parameter id. Das Web Template besitzt den Seitenkontext und ergänzt area oder center. Die aktive Power Pages Sprache wird ebenfalls serverseitig gelesen.

{% assign detail_id = request.params['id'] | url_escape %}
{% assign detail_language = website.selected_language.code %}
{% capture detail_input -%}
{"entityType":"area","id":"{{ detail_id }}","languageCode":"{{ detail_language }}"}
{%- endcapture %}

{% serverlogic name: 'server-logic-query', operation: 'getPortalCatalogDetail', input: detail_input, output: detail_result %}

url_escape hält den Query-Wert in einem kontrollierten JSON String. Server Logic dekodiert den Wert erneut und prüft ihn erst danach als GUID.

Das Center Web Template verwendet denselben Vertrag. Es setzt lediglich entityType auf center. Die beiden Templates bleiben damit fachlich klar getrennt.

Wie Microsoft Server Logic aus Liquid aufruft

Microsoft dokumentiert den Liquid serverlogic Tag mit name, operation, optionalem input und output. Das Ergebnis besitzt unter anderem success, status_code, data und raw_result.

Der Aufruf von Server Logic aus Liquid benötigt keinen clientseitigen HTTP Request und keinen CSRF Token. Er läuft während des serverseitigen Renderings. Lange Dataverse Aufrufe verlängern deshalb direkt die Antwortzeit der Seite.

Diese Ausführung unterscheidet sich vom React Suchwidget. React ruft den gemeinsamen HTTP Endpunkt mit einem CSRF geschützten POST auf. Liquid ruft eine benannte Server Logic Funktion während der Seitengenerierung auf.

Wie Server Logic den Einzelabruf prüft

Server Logic liest den Liquid Input als JSON String. Danach dekodiert sie die Werte, prüft Entitätstyp und Sprache und normalisiert eine gültige GUID.

function parseDetailRequest(input) {
  const payload = JSON.parse(input);
  const entityType = decodeDetailInputValue(payload.entityType, 'entityType');
  const languageCode = decodeDetailInputValue(payload.languageCode, 'languageCode').toLowerCase();
  const id = decodeDetailInputValue(payload.id ?? '', 'id');

  if (entityType !== 'area' && entityType !== 'center') {
    throw new Error('Detail entityType must be "area" or "center".');
  }

  return {
    entityType,
    lcid: DETAIL_LANGUAGE_LCIDS[languageCode],
    ...(isGuid(id) ? { id: id.toLowerCase() } : {}),
  };
}

Ein falscher Entitätstyp oder eine nicht unterstützte Sprache beendet den Aufruf als Fehler. Eine syntaktisch ungültige GUID wird beim Einzelabruf dagegen wie ein nicht gefundener Datensatz behandelt.

Server Logic ruft die Custom API in diesem Fall nicht auf. Das Web Template erhält { found: false, entityType }.

Wie Center und Fläche unterschiedliche OData Filter erhalten

Die Custom API erwartet für Objekte und Flächen unterschiedliche Filterfelder. Server Logic setzt nur das Feld, das zum geprüften Entitätstyp gehört.

if (request.entityType === 'center') {
  apiPayload.objectfilter = '$filter=(id eq ' + request.id + ')';
}

if (request.entityType === 'area') {
  apiPayload.areafilter = '$filter=(id eq ' + request.id + ')';
}

Warum die Dataverse Antwort noch kein Liquid Vertrag ist

Die Custom API liefert getrennte Listen für Objekte, Flächen, Ebenen und Merkmale. Diese Form ist für Datentransport geeignet. Für Liquid wäre sie unnötig aufwendig.

Ein Web Template müsste IDs über mehrere Listen vergleichen. Fehlerhafte Referenzen würden erst beim Rendern sichtbar. Dieselben Lookups würden auf jeder Detailseite erneut entstehen.

Server Logic übernimmt diese Arbeit einmal. Liquid erhält danach die fachliche Sicht statt des normalisierten Antwortgraphen.

Wie Server Logic den Dataverse Antwortgraphen auflöst

Server Logic baut für alle vier Listen eindeutige, kleingeschriebene IDs. Danach prüft sie jede Beziehung, bevor sie ein DTO an Liquid übergibt.

1. Eindeutige, kleingeschriebene IDs für alle vier Listen.
2. Jede Fläche referenziert eine vorhandene Ebene.
3. Jedes Merkmal gehört zur erwarteten Fläche.
4. Jede Center-Fläche verweist zurück auf dasselbe Center.
5. Eine Area-Detailantwort besitzt ein vorhandenes Parent-Center.
6. Option Sets werden zu { code, name }.
7. Fehlende optionale Werte werden null.
8. Nicht unterstützte URL-Schemas werden verworfen.
9. Das Dataverse Sentinel-Datum 0001-01-01 wird null.

Die Auflösung erfolgt vor dem Liquid Rendering. Das Web Template verarbeitet keine parallelen Dataverse Listen und entscheidet nicht selbst über Beziehungen.

Welche Form Center und Area DTOs besitzen

Die Detailantworten sind fachliche DTOs. Ein Center besitzt seine aufgelösten Flächen. Eine Fläche besitzt ihre Ebene, Merkmale und das zugehörige Parent-Center.

type PortalCatalogDetail =
  | {
      readonly found: true;
      readonly entityType: 'center';
      readonly id: string;
      readonly name: string | null;
      readonly areas: readonly PortalCatalogArea[];
    }
  | {
      readonly found: true;
      readonly entityType: 'area';
      readonly id: string;
      readonly name: string | null;
      readonly level: PortalCatalogLevelDetail;
      readonly characteristics: readonly PortalCatalogCharacteristic[];
      readonly object: PortalCatalogAreaParent;
    };

Diese DTOs sind nicht vollständig flach. Sie besitzen weiterhin fachlich sinnvolle Listen und Objekte.

Aufgelöst bedeutet hier etwas anderes. Liquid muss keine fremden Listen anhand von GUIDs verbinden. detail.areas, detail.characteristics, detail.level und detail.object sind direkt erreichbar.

Wie Liquid drei Ergebniszustände trennt

Das Web Template unterscheidet technischen Fehler, fachlich nicht gefundene Daten und eine gefundene Detailantwort.

{% if detail_result.success == false %}
  <section role="status">
    <h1>{{ snippets['CATALOG DETAIL UNAVAILABLE TITLE'] | escape }}</h1>
  </section>
{% elsif detail_result.data.found != true %}
  <section role="status">
    <h1>{{ snippets['CATALOG DETAIL NOT FOUND TITLE'] | escape }}</h1>
  </section>
{% else %}
  {% assign detail = detail_result.data %}
  <h1>{{ detail.name | escape }}</h1>
{% endif %}

1. success == false bedeutet technischer Server Logic Fehler.
2. found != true bedeutet gültiger Aufruf ohne passenden Datensatz.
3. Nur der dritte Zweig rendert fachliche Detaildaten.

Die Werte aus DTOs und Snippets werden mit escape ausgegeben. Das hält die Darstellung getrennt von der serverseitigen Auflösung.

Warum aufgelöste DTOs Web Templates vereinfachen

Ein Web Template sollte Seitenstruktur und Ausgabe verantworten. Es sollte nicht die Beziehungen zwischen vier Dataverse Listen rekonstruieren.

Der Beitrag zur Power Pages Server Logic Sicherheitsgrenze zeigt, warum Browserwerte erneut geprüft werden. Der Beitrag zu typisierten React und Dataverse Schnittstellen erklärt die getrennten Request- und Response-Verträge.

Aufgelöste DTOs reduzieren damit nicht die fachliche Information. Sie verschieben die Prüf- und Mappingarbeit an die Stelle, an der Dataverse Antwort und Server Logic Vertrag gemeinsam bekannt sind.

Power Pages Detailsuche im Enterprise-Projekt

Ich habe die Detailabfrage bewusst nicht in Liquid nachgebaut. Liquid rendert. Server Logic prüft, lädt und löst Beziehungen auf.

Damit bleiben Center- und Flächenseiten klein. Fehlerzustände sind sichtbar. Die Dataverse Custom API bleibt die fachliche Datenquelle.

Der nächste Serienbeitrag zeigt, wie derselbe Mapper mehrere GUIDs für eine Power Pages Favoritenseite verarbeitet.

Der Deep Dive Power Pages Favoriten mit Batch-GUIDs und Server Logic dokumentiert Validierung, Deduplizierung und Teilfehler.

Die ECE Fallstudie zur Power Pages Enterprise-Suche zeigt den Projektkontext. Hier liegt der Fokus auf der GUID-Prüfung, der DTO-Auflösung und der Ausgabe in Liquid.

Du arbeitest an einer Power Pages Suche mit eigenen Detailseiten und Dataverse Logik? Im Power Pages Pro-Code Bereich zeige ich, wie ich Datenverträge, Sicherheitsgrenzen und Rendering vor der Umsetzung trenne.