Verwenden der AEM Cloud-Migrationsfertigkeit using-cloud-migration-skill
Diese Referenz behandelt alle unterstützten Migrationsmuster, die Bereitstellung von BPA-Ergebnissen und die Verwaltung von Sitzungen in einem großen Projekt. Eine Einführung und Einrichtungsanweisungen finden Sie in der Übersicht.
Generieren eines Migrations-Runbook migration-runbook
Beginnen Sie bei einer Gesamtprojektbewertung mit einem Runbook, anstatt ein einzelnes Muster zu benennen. Den Agenten auffordern mit:
Review my code for AEMaaCS migration
Die Qualifikation generiert ein schreibgeschütztesmigration-runbook.md an Ihrem Projektstamm, ohne den Code zu ändern. Das Runbook behandelt alle Muster, die die Migrationsfertigkeit ansprechen kann, und zeichnet für jedes Muster Folgendes auf:
- Die verwendete Erkennungsstrategie (BPA/CAM-Ergebnisse, Analyzer oder heuristischer Content-Scan)
- Die betroffenen Dateien und die Anzahl der Mustersuchvorgänge
- Aufforderung zum Kopieren und Einfügen, um die Migrationssitzung dieses Musters zu starten
Da das Runbook neben dem Markdown auch einen Ergebniscache schreibt, werden die bereits erkannten Ergebnisse bei einer späteren Mustersitzung wiederverwendet - der Agent scannt nicht erneut. Verwenden Sie das Runbook, um zu priorisieren, welche Muster zuerst behandelt werden sollen, und dann Mustersitzungen zu starten, wie unten beschrieben.
Funktionsweise von Sitzungen workflow-overview
Jede Migrationssitzung folgt dieser Reihenfolge:
- Benennen des Musters: Geben Sie ein Muster an (z. B.
scheduler) - Ergebnisse bereitstellen: aus einer BPA-CSV-Datei, CAM über MCP oder bestimmten Dateipfaden
- Agent liest Umwandlungsregeln: Die Qualifikation liest die relevanten Umwandlungsregeln aus der begleitenden
code-assessmentvor, bevor Code-Änderungen vorgenommen werden - Erster Batch von fünf: Der Agent wandelt bis zu fünf Funde um und meldet, was er geändert hat
- Sie überprüfen und fortfahren: Nachdem Sie jeden Batch überprüft haben,
continueSie, um mit dem nächsten fortzufahren
Der Agent verarbeitet jeweils ein Muster und einen Batch. Er wird nicht automatisch fortgesetzt. Für jeden Batch ist eine Bestätigung erforderlich.
Migrationsmuster patterns
Planung scheduler
Targeting von Java-Klassen mit sling.commons.scheduler- oder Scheduler, die mit der statuslosen, containerisierten Laufzeit von AEMaaCS nicht kompatibel sind.
BPA-Muster-ID: scheduler
Der Agent konvertiert Scheduler-injizierte Aufträge mithilfe von @Designate in @Component Implementierungen von Runnable und ersetzt die konstruktorbasierte Scheduler-Registrierung durch @Activate-/@Deactivate-Lebenszyklusmethoden.
ResourceChangeListener resource-change-listener
Targeting ResourceChangeListener oder ResourceChange Listener-Implementierungen, die Aktualisierungen für AEMaaCS erfordern.
BPA-Muster-ID: resourceChangeListener
Replikation replication
Targeting-Klassen, die com.day.cq.replication.Replicator oder zugehörige Replikations-APIs importieren, die in AEMaaCS nicht unterstützt werden. Der Agent ersetzt sie durch ContentDistribution Äquivalente und aktualisiert die entsprechenden OSGi-Service-Verweise.
BPA-Muster-ID: replication
Ereignis-Listener event-listener
Targeting von OSGi-EventListener oder EventHandler, die für die Semantik der AEMaaCS-Ereignisverarbeitung aktualisiert werden müssen.
BPA-Muster-ID: eventListener
Ereignishandler event-handler
Targeting von synchronen OSGi-EventHandler, die für AEMaaCS angepasst werden müssen.
BPA-Muster-ID: eventHandler
Asset-API asset-api
Targeting von Klassen mit veralteten AssetManager, DAMEvent oder nicht unterstützten DAM-APIs. Der Agent ersetzt sie durch die unterstützten AEM Assets-API-Entsprechungen.
BPA-Muster-ID: assetApi
Guava-Cache zu Koffein guava-cache
Targeting von Bundles, die den Cache von Guava verwenden (com.google.common.cache.* wie Cache, CacheBuilder und LoadingCache). Auf AEM as a Cloud Service ist die unterstützte prozessinterne Cache-Bibliothek Coffein sodass der Agent die Maven-Abhängigkeit austauscht, Importe aktualisiert und die betroffenen Aufrufsites anpasst. Da Koffein von demselben Autor geschrieben wurde und seine API absichtlich nahezu identisch ist, ist die Änderung größtenteils mechanisch.
BPA-Muster-ID: guavaCache
BPA meldet dieses Muster mit Bundle-Granularität (Subtyp custom.guava.cache), sodass der Agent das Bundle in die Java-Dateien auflöst, die den Guava-Cache tatsächlich importieren, und diese bearbeitet. Dieses Muster wird nur durch die Migrationskenntnisse bereitgestellt - nicht code-assessment -, da die Guava-Cache-Nutzung nur in Code erfolgt, der von veraltetem AEM übernommen wird, nie in nativem Cloud Service-Code.
guavaCache verlässt sich auf BPA als Quelle der Wahrheit. Wenn keine BPA- oder CAM-Quelle verfügbar ist, durchsucht der Agent Ihre Java-Dateien erneut nach import com.google.common.cache Importen als unbestätigte Kandidaten.Verwendung von InputStream input-stream
Targeting von Java-Code, der von BPA für die java.io.InputStream Verwendung markiert wird (Untertyp java.io.inputstream). Auf AEM as a Cloud Service kann das Streamen großer Binärdateien über JVM den Container-Speicher erschöpfen, sodass Binärdateien direkt über den Cloud Blob Store und das CDN hochgeladen und bereitgestellt werden sollten (siehe Entwicklungsrichtlinien und direkter binärer Upload).
BPA-Muster-ID: inputStream
Der Agent gruppiert die Ergebnisse nach Risiko und geht mit jeder Gruppe anders um:
Binary nicht geschlossenSitzung starten mit:
Fix inputStream findings using BPA CSV at ./reports/bpa.csv
inputStream verlässt sich auf BPA als Quelle der Wahrheit. Wenn keine BPA- oder CAM-Quelle verfügbar ist, scannt der Agent Ihre Java-Dateien. Ergebnisse im Code, der sich nicht in Ihrem Arbeitsbereich befindet, z. B. Produkt- oder Drittanbieter-Bundles, werden nur zu Informationszwecken gemeldet.HTL-Link (data-sly-test) htl-lint
Targeting von HTL-Vorlagen unter ui.apps, die data-sly-test: redundant constant value comparison Lint-Warnungen erzeugen. Der Agent erkennt betroffene Vorlagen, indem er das Inhaltspaket direkt scannt. Für dieses Muster ist keine BPA-CSV- oder CAM-Verbindung erforderlich.
BPA-Muster-ID: htlLint
htlLint Ergebnisse werden nicht in BPA-CSV-Exporten angezeigt. Der Agent erkennt sie durch direkte Dateiüberprüfung, wenn Sie eine Sitzung mit diesem Muster starten.OSGi-Konfigurationen in Cloud Manager osgi-cloud-manager
Konvertiert OSGi-Konfigurationen in ui.config in das Cloud Manager-kompatible .cfg.json-Format mit vollständiger umgebungsspezifischer Handhabung. Dies umfasst mehrere damit zusammenhängende Aufgaben:
Formatkonvertierung konfigurieren
AEMaaCS erfordert, dass OSGi-Konfigurationen als .cfg.json-Dateien gespeichert werden, mit umgebungsspezifischen Konfigurationen in Ordnern, die den Ausführungsmodus betreffen (config.author/, config.publish/, config.dev/ usw.). Der Agent:
- Konvertiert vorhandene OSGi-Konfigurationen im
.config-,.cfg- und XML-Format in.cfg.json - Teilt Konfigurationen, die sowohl autoren- als auch veröffentlichungsspezifische Werte enthalten, in separate Dateien mit Ausführungsmodus-Bereich auf.
- Validiert Eigenschaftstypen anhand der OSGi-Metatypspezifikation (Zeichenfolgen, Ganzzahlen, boolesche Werte, Arrays)
- Kennzeichnet Adobe-eigene PIDs für die manuelle Überprüfung, anstatt sie automatisch zu konvertieren
Geheimnisse und Umgebungsvariablen
Verschiebt Nur-Text-Geheimnisse und umgebungsspezifische Werte aus den bestätigten Konfigurationsdateien und ersetzt sie durch Cloud Manager-Platzhalter:
$[secret:NAME]: für Kennwörter, Token und andere vertrauliche Werte$[env:NAME]: für nicht vertrauliche Werte, die sich je nach Umgebung unterscheiden (z. B. Service-URLs)
Die entsprechenden Variablen und Geheimnisse werden in Cloud Manager angewendet und zur Laufzeit eingefügt. In der Quell-Code-Verwaltung werden keine Werte gespeichert.
Nicht unterstützte Ausführungsmodi (URC)
AEM as a Cloud Service unterstützt einen festen Satz von Ausführungsmodus-IDs. Konfigurationsordner, die einen nicht unterstützten Ausführungsmodus verwenden, haben nach der Bereitstellung keine Wirkung. Der Agent kennzeichnet diese nicht unterstützten Ausführungsmodus-Konfigurationen (URC), einschließlich:
- Unbekannte Ausführungsmodus-Token, z. B.
config.qaoderinstall.local - Ein Stufen-Token, das anstelle des Umgebungs-Tokens folgt, geht dem Umgebungs-Token
config.dev.authoranstelle des gültigenconfig.author.devvoraus - Nicht-Kleinbuchstaben-Token wie
config.Author.devund die reservierteconfig.preview(Vorschau erbt von der Veröffentlichung)
URC-Ergebnisse stammen zuerst aus Best Practices Analyzer (Subtyp unsupported.runmode, Schweregrad CRITICAL). Wenn keine BPA-Quelle sie meldet, scannt der Agent config.* und install.* Ordner lokal als Sicherheitsnetz. Bei jedem Fund werden der Ordnerpfad, der fehlerhafte Ausführungsmodus und die Behebung gemeldet. Es wird geprüft, ob die Konfiguration noch benötigt wird, sie wird in einen unterstützten Ausführungsmodus umbenannt oder entfernt, falls sie veraltet ist. Bei Verstößen auf Bestellbasis, bei denen jedes Token gültig, aber nicht in der richtigen Reihenfolge ist, kann der Agent automatisch eine sichere Neuanordnung anwenden (z. B. Umbenennen von config.dev.author in config.author.dev). Unbekannte Token und andere mehrdeutige Fälle werden gekennzeichnet, damit Sie sie beheben können.
Die Konvertierung des Konfigurationsformats und die Externalisierung geheimer Daten erfordern keine BPA-CSV- oder CAM-Dateien. Bei der URC-Erkennung werden, sofern verfügbar, BPA-Ergebnisse verwendet. Sitzung starten mit:
Scan my config files and create Cloud Manager environment secrets or variables.
Dialogfeld „Migration“ (veraltete Benutzeroberfläche) dialog-migration
Konvertiert Dialogfelder der klassischen Benutzeroberfläche in die Touch-optimierte Benutzeroberfläche. Der Agent verarbeitet zwei Dialogfelduntertypen: ExtJS/Klassische Benutzeroberfläche cq:Dialog Definitionen werden als Coral 3-_cq_dialog neu erstellt, und vorhandene Coral 2-Dialogfelder werden anstelle von Coral 3 aktualisiert. Es übernimmt auch Listener, optionsProvider, namePrefix und Aktualisierungen filter.xml.
BPA-Muster-ID: lui (nur Dialogfeld-Untertypen)
Wenn sowohl Dialogfeld- als auch benutzerdefinierte Widget-Ergebnisse für die gleichen Komponenten vorhanden sind, führen Sie zuerst die Migration benutzerdefinierter Widgets aus, damit alle xtype aufgelöst werden, bevor die Dialogfelder konvertiert werden.
Convert my Classic UI dialogs to Touch UI Coral 3.
Benutzerdefinierte Design-Widgets (veraltete Benutzeroberfläche) custom-design-widgets
Migriert benutzerdefinierte ExtJS-Widgets (cq:Widget mit benutzerdefinierten xtype). Der Agent inventarisiert die Widgets und ordnet dann entweder jede xtype einer bekannten Coral 3-Entsprechung zu oder eine Strukturvorlage für eine Formularkomponente der Granite-Benutzeroberfläche zu, wenn keine direkte Zuordnung vorhanden ist.
BPA-Muster-ID: cdw
Migrate my custom ExtJS widgets (CDW findings) from CAM.
Vorlagenmodernisierung template-modernization
Konvertiert statische Vorlagen in bearbeitbare Vorlagen und generiert die entsprechenden AEM-Modernisierungs-, Neuschreibungsregeln (Struktur-, Komponenten- und Richtlinienregeln). Der Agent wird in drei Phasen ausgeführt: Er erkennt die Vorlagen und erstellt einen Plan pro Vorlage, führt die Planvorlage nach Vorlage aus und validiert die generierten /conf.
Während der Erkennung führt der Agent die Vorlagen in jeder Tiefe unter apps/<appId>/templates/ durch - einschließlich verschachtelter oder gruppierter Vorlagenordner - und klassifiziert jede statische Vorlage basierend auf ihrem Seitenkomponenten-Ressourcentyp als veraltet oder benutzerdefiniert. Diese Klassifizierung gilt auch ohne BPA-Bericht, sodass benutzerdefinierte Vorlagen anders behandelt werden als ältere.
Dieses Muster verwendet keine BPA-Muster-ID. Sitzung starten mit:
Migrate my static templates to editable templates and generate the Modernize Tools rewrite rules.
Dispatcher-Konversion dispatcher-conversion
Konvertiert eine AMS- oder On-Premise-Apache-HTTPD- und -Dispatcher-Konfiguration in die AEM as a Cloud Service-Struktur. Diese Funktion umfasst das von Adobe verwaltete Tool Dispatcher Converter und fügt Erkennung, Konfigurationserstellung, Ausgabeprüfung und Validierung hinzu.
Der Agent arbeitet über einen stufenweisen Fluss:
- Erkennen und Inventar - Bestimmt die Konfiguration Modus und zeichnet eine Baseline-Anzahl von Filter-, Neuschreibungs- und Cache-Regeln auf. Zu den erkannten Modi gehören
standard(AMS),flexible(monolithisch On-Premise),v1(ältere Layouts),already-cloud,not-dispatcherundunknown. Zumalready-cloud,not-dispatcheroderunknownstoppt der Agent und bittet Sie, dies zu bestätigen, bevor Sie fortfahren. - Konfiguration planen und generieren - Erstellt die Konverterkonfiguration und bestätigt den Plan mit Ihnen.
- Convert - Führt den Dispatcher-Konverter von Adobe aus (wird bei der ersten Verwendung automatisch installiert).
- Verify - Prüft die Ausgabe anhand der Baseline. Ein leerer Filtersatz (
filter-acl-loss) ist ein harter Stopp, der vor dem Fortfahren aufgelöst werden muss. - Grenzüberschreitende Übergabe - Leitet Cloud Manager-Umgebungsvariablen an den OSGi-Konfigurationsfluss weiter und kennzeichnet CDN- oder Security-Header-Kandidaten.
- Validate - Führt den Cloud Service Dispatcher-Validator aus und erstellt einen konsolidierten Konversionsbericht.
Runbook-Muster-ID: dispatcherConversion (heuristisch vom Konfigurations-Layout erkannt). Dieses Muster verwendet weder BPA noch CAM. Sitzung starten mit:
Convert my AMS / on-prem Dispatcher config to AEM as a Cloud Service.
standard (AMS)-Konfigurationen sind nahezu automatisiert, während flexible- und v1-Layouts einer genaueren Überprüfung bedürfen.Oak-Indexmigration oak-index
Konvertiert veraltete Oak-Indexdefinitionen unter ui.apps/.../_oak_index/ in AEM as a Cloud Service-kompatible Definitionen. Diese Funktion umschließt das von Adobe verwaltete Index Converter-Tool, anstatt die Konversionsregeln erneut zu implementieren. Es behandelt benutzerdefinierte Lucene-Indizes und vordefinierte Indizes, die direkt geändert wurden.
BPA-Muster-ID: oakIndex (Untertypen index.rule.violation und standard.index.modification)
Der Agent führt den Konverter aus, zeigt Ihnen einen Unterschied mit einer Kompatibilitätsprüfung des Datentyps an, wendet die Änderungen erst an, nachdem Sie sie bestätigt haben, und erstellt dann ui.apps und führt den AEM Analyzer aus.
AEM as a Cloud Service erfordert, dass benutzerdefinierte Indizes ein -custom-<n> Versionssuffix aufweisen, wobei <n> bei jeder Definitionsänderung ansteigt (siehe Indexnamen). Der Agent wählt die nächste freie <n> aus, sodass eine Wiederholungsmigration einen vorhandenen Index nicht überschreibt:
- Vorkonfigurierter Index geändert:
<indexName>-<version>-custom-<n>(z. B.damAssetLucene-8-custom-1) - Neuer benutzerdefinierter Index:
<originalName>-custom-<n> - Bereits konformer Index: unverändert gelassen
Das Muster erzeugt derzeit das klassische _oak_index. Vereinfachtes Indexmanagement als Zielformat ist geplant, wird aber noch nicht unterstützt.
Sitzung starten mit:
Fix oakIndex findings using BPA CSV at ./reports/bpa.csv
oakIndex verlässt sich auf BPA als Quelle der Wahrheit. Indizes außerhalb von _oak_index und nt:base Lucene-Indizes liegen außerhalb des Geltungsbereichs und der Agent aktualisiert keine Abfragen, die von umbenannten Indizes abhängen. Siehe auch Inhaltssuche und -indizierung.Validieren einer Migration validate-migration
Nachdem ein Muster migriert wurde, kann der Agent das Ergebnis auf Ihrem lokalen AEM as a Cloud Service SDK überprüfen. Die Validierung ist für Ihren Code schreibgeschützt: Der Agent bearbeitet Ihre Quelle nie, um einen Pass zu erhalten. Wenn eine Prüfung fehlschlägt, wird die Fehlerbehebung auf das Migrationsmuster zurückgesetzt, zu dem der Code gehört.
Die Validierung unterstützt diese Muster:
scheduler, assetApi, eventListener, eventHandler, resourceChangeListener, replicationlui, cdwAndere Muster, z. B. Dispatcher-Konvertierungs- und OSGi-Konfigurationen, werden von der Validierung nicht abgedeckt.
Starten Sie für die benötigten Muster Cloud SDK (standardmäßig auf http://localhost:4602) und fügen Sie den AEM Quickstart-MCP-Server zu Ihrer IDE hinzu. Der Agent dann:
- Überprüft Setup - Bestätigt, dass die erforderlichen Tools, Instanzen und der MCP-Server verfügbar sind, und bittet Sie, alle fehlenden Elemente zu starten.
- Vorbereitet - Erstellt das Projekt und stellt die geänderten Bundles über das Maven-Installationsprofil Ihres Projekts bereit.
- Diagnosen - Liest den Bundle- und Komponentenstatus aus dem AEM Quickstart-MCP. Offline-Muster (
lui,cdw) überspringen diesen Schritt. - Prüft - Schreibt einen Validierungsbericht in
.validate-migration/Projekt.
Wenn Ihr Projekt mit einem Cloud Acceleration Manager-Projekt verknüpft ist (z. B. über das Migrations-Runbook), zeichnet der Agent auch das Validierungsergebnis in CAM über die Cloud-Migrationsfunktionen des AEM MCP-Servers auf.
Sitzung starten mit:
Validate my scheduler migration on the local Cloud SDK.
BPA-Source-Optionen bpa-source
MCP-Fehlerbehandlung mcp-errors
Wenn die MCP-Verbindung einen Fehler zurückgibt (einschließlich „Projekt nicht gefunden“ oder Authentifizierungsfehler), stoppt der Agent und zeigt den Fehler an. Es wechselt nicht automatisch zu einer anderen Quelle. Vom Status Angehalten aus haben Sie folgende Möglichkeiten:
- Bestätigen Sie das richtige Projekt aus der Liste, die der Agent angezeigt hat
- Geben Sie alternativ einen BPA-CSV-Pfad an.
- Spezifische Java-Dateipfade für eine manuelle Migration angeben
Verwalten von Sitzungen in großen Berichten large-reports
Bei BPA-Berichten mit vielen Ergebnissen ermöglicht der Batch-für-Batch-Ansatz eine inkrementelle Validierung:
- Überprüfen Sie die Unterschiede für jeden Batch
- Übergeben Sie den Batch mit einer Commit-Nachricht im Musterbereich
- Zum Starten des nächsten Batches
continueantworten - Wiederholen Sie den Vorgang, bis der Agent meldet, dass alle Ergebnisse für das Muster abgeschlossen sind
Ein Muster pro Commit sorgt dafür, dass der Git-Verlauf lesbar bleibt, und erleichtert die Wiederherstellung einzelner Mustertransformationen.
Workspace-Umfang workspace-scope
Der Agent sucht und bearbeitet Dateien nur in den geöffneten IDE-Arbeitsbereichordnern. Übergeordnete Verzeichnisse, gleichrangige Ordner oder andere Speicherorte auf der Festplatte werden nicht überprüft.
Wenn eine BPA-Suche auf einen Dateipfad verweist, der nicht im Arbeitsbereich vorhanden ist, stoppt der Agent und teilt Ihnen mit, welche Pfade fehlen. Öffnen Sie den richtigen Projektordner oder geben Sie die Pfade explizit an, um fortzufahren.