chrome.debugger

Beschreibung

Berechtigungen

Sie müssen die Berechtigung "debugger" im Manifest Ihrer Erweiterung deklarieren, um diese API zu verwenden.

{
  "name": "My extension",
  ...
  "permissions": [
    "debugger",
  ],
  ...
}

Einschränkungen durch Unternehmensrichtlinien

Auf Unternehmensgeräten können einige Richtlinien verhindern, dass Erweiterungen den Debugger mit einem Alles-oder-Nichts-Modell zum Zeitpunkt des Anhängens (chrome.debugger.attach()) anhängen:

• Hosteinschränkungen: Wenn in der Unternehmensrichtlinie ExtensionSettings blockierte Hosts (runtime_blocked_hosts) für eine Erweiterung konfiguriert sind, wird chrome.debugger.attach() für alle Ziele mit dem Fehler "Host access is restricted by policy." blockiert (auch wenn einzelne Ursprünge in runtime_allowed_hosts enthalten sind).
• Richtlinien für Screenshots und DLP: Wenn die Unternehmensrichtlinie DisableScreenshots die Aufnahme von Screenshots deaktiviert oder Regeln zum Schutz vor Datenverlust (Data Loss Prevention, DLP) auf das Ziel angewendet werden, schlägt chrome.debugger.attach() mit dem Fehler "Screenshot capture is restricted by policy." fehl.

Konzepte und Verwendung

Nach dem Anhängen können Sie mit der chrome.debugger API Befehle des Chrome-Entwicklertools-Protokolls (Chrome DevTools Protocol, CDP) an ein bestimmtes Ziel senden. Eine detaillierte Erläuterung des CDP würde den Rahmen dieser Dokumentation sprengen . Weitere Informationen finden Sie in der offiziellen CDP-Dokumentation.

Ziele

Ziele stellen etwas dar, das debuggt wird. Dazu können ein Tab, ein Iframe oder ein Worker gehören. Jedes Ziel wird durch eine UUID identifiziert und hat einen zugehörigen Typ (z. B. iframe, shared_worker usw.).

Innerhalb eines Ziels kann es mehrere Ausführungskontexte geben. Beispielsweise erhalten Iframes im selben Prozess kein eindeutiges Ziel, sondern werden als verschiedene Kontexte dargestellt, auf die über ein einzelnes Ziel zugegriffen werden kann.

Eingeschränkte Domains

Aus Sicherheitsgründen bietet die chrome.debugger API keinen Zugriff auf alle Chrome-Entwicklertools-Protokolldomains. Die verfügbaren Domains sind: Accessibility, Audits, CacheStorage, Console, CSS, Database, Debugger, DOM, DOMDebugger, DOMSnapshot, Emulation, Fetch, IO, Input, Inspector, Log, Network, Overlay, Page, Performance, Profiler, Runtime, Storage, Target, Tracing, WebAudio und WebAuthn.

Mit Frames arbeiten

Es gibt keine Eins-zu-eins-Zuordnung von Frames zu Zielen. Auf einem einzelnen Tab, können mehrere Frames im selben Prozess dasselbe Ziel verwenden, aber einen anderen Ausführungskontextnutzen. Andererseits kann für einen Iframe außerhalb des Prozesses ein neues Ziel erstellt werden.

Wenn Sie alle Frames anhängen möchten, müssen Sie jeden Frame-Typ separat verarbeiten:

• Achten Sie auf das Ereignis Runtime.executionContextCreated, um neue Ausführungskontexte zu identifizieren, die mit Frames im selben Prozess verknüpft sind.

• Folgen Sie der Anleitung zum Anhängen an verknüpfte Ziele, um Frames außerhalb des Prozesses zu identifizieren.

An verknüpfte Ziele anhängen

Nachdem Sie eine Verbindung zu einem Ziel hergestellt haben, können Sie eine Verbindung zu weiteren verknüpften Zielen herstellen, z. B. untergeordneten Frames außerhalb des Prozesses oder zugehörigen Workern.

Ab Chrome 125 unterstützt die chrome.debugger API flache Sitzungen. So können Sie Ihrer Haupt-Debuggersitzung weitere Ziele als untergeordnete Elemente hinzufügen und ihnen Nachrichten senden, ohne chrome.debugger.attach noch einmal aufrufen zu müssen. Stattdessen können Sie beim Aufrufen von chrome.debugger.sendCommand die Eigenschaft sessionId hinzufügen, um das untergeordnete Ziel zu identifizieren, an das Sie einen Befehl senden möchten.

Wenn Sie automatisch untergeordnete Frames außerhalb des Prozesses anhängen möchten, fügen Sie zuerst einen Listener für das Ereignis Target.attachedToTarget hinzu:

chrome.debugger.onEvent.addListener((source, method, params) => {
  if (method === "Target.attachedToTarget") {
    // `source` identifies the parent session, but we need to construct a new
    // identifier for the child session
    const session = { ...source, sessionId: params.sessionId };

    // Call any needed CDP commands for the child session
    await chrome.debugger.sendCommand(session, "Runtime.enable");
  }
});

Aktivieren Sie dann das automatische Anhängen, indem Sie den Befehl Target.setAutoAttach senden und die Option flatten auf true setzen:

await chrome.debugger.sendCommand({ tabId }, "Target.setAutoAttach", {
  autoAttach: true,
  waitForDebuggerOnStart: false,
  flatten: true,
  filter: [{ type: "iframe", exclude: false }]
});

Beim automatischen Anhängen werden nur Frames angehängt, die dem Ziel bekannt sind. Das sind nur Frames, die unmittelbare untergeordnete Elemente eines zugehörigen Frames sind. Wenn beispielsweise die Frame-Hierarchie A -> B -> C ist (wobei alle ursprungsübergreifend sind), führt der Aufruf von Target.setAutoAttach für das Ziel, das mit A verknüpft ist, dazu, dass die Sitzung auch an B angehängt wird. Dies ist jedoch nicht rekursiv. Daher muss Target.setAutoAttach auch für B aufgerufen werden, um die Sitzung an C anzuhängen.

Beispiele

Wenn Sie diese API testen möchten, installieren Sie das Debugger-API-Beispiel aus dem Repository chrome-extension-samples.

chrome.debugger.attach(
  target: Debuggee,
  requiredVersion: string,
): Promise<void>

chrome.debugger.detach(
  target: Debuggee,
): Promise<void>

chrome.debugger.getTargets(): Promise<TargetInfo[]>

chrome.debugger.sendCommand(
  target: DebuggerSession,
  method: string,
  commandParams?: object,
): Promise<object | undefined>

chrome.debugger.onDetach.addListener(
  callback: function,
)

chrome.debugger.onEvent.addListener(
  callback: function,
)