browser.debugger

Beschreibung

Die chrome.debugger API dient als alternativer Transport für das Remote-Debugging-Protokoll von Chrome. Mit chrome.debugger können Sie einen oder mehrere Tabs anhängen, um die Netzwerkinteraktion zu instrumentieren, JavaScript zu debuggen, das DOM und CSS zu mutieren und vieles mehr. Verwenden Sie das Debuggee-Attribut tabId, um Tabs mit sendCommand anzusprechen und Ereignisse nach tabId aus onEvent-Callbacks weiterzuleiten.

Berechtigungen

debugger

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

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

Einschränkungen für Unternehmensrichtlinien

Auf Unternehmensgeräten können einige Richtlinien verhindern, dass Erweiterungen den Debugger anhängen. Dabei wird beim Anhängen ein Alles-oder-Nichts-Modell verwendet (browser.debugger.attach()):

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

Konzepte und Verwendung

Nach dem Anhängen können Sie mit der browser.debugger API Chrome-Entwicklertools-Protokoll-Befehle (CDP) an ein bestimmtes Ziel senden. Eine ausführliche Erläuterung des CDP würde den Rahmen dieser Dokumentation sprengen. Weitere Informationen zum CDP finden Sie in der offiziellen CDP-Dokumentation.

Ziele

Ziele stellen etwas dar, das gerade debuggt wird. Das kann ein Tab, ein iFrame oder ein Worker sein. 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 von einem einzelnen Ziel aus zugegriffen werden kann.

Eingeschränkte Domains

Aus Sicherheitsgründen bietet die browser.debugger API keinen Zugriff auf alle Chrome-Entwicklertools-Protokoll-Domains. 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, Runtime, Storage, Target, Tracing, WebAudio und WebAuthn.

Mit Frames arbeiten

Es gibt keine 1:1-Zuordnung von Frames zu Zielen. In einem einzelnen Tab können mehrere Frames desselben Prozesses dasselbe Ziel verwenden, aber einen anderen Ausführungskontext. Andererseits kann ein neues Ziel für einen Out-of-Process-iFrame erstellt werden.

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

  • Warten Sie auf das Ereignis Runtime.executionContextCreated, um neue Ausführungskontexte zu identifizieren, die mit denselben Prozessframes verknüpft sind.

  • Folgen Sie der Anleitung unter An verwandte Ziele anhängen, um Frames außerhalb des Prozesses zu identifizieren.

Nachdem Sie eine Verbindung zu einem Ziel hergestellt haben, können Sie eine Verbindung zu weiteren zugehörigen Zielen herstellen, einschließlich untergeordneter Frames außerhalb des Prozesses oder zugehöriger Worker.

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

Wenn Sie automatisch eine Verbindung zu untergeordneten Frames außerhalb des Prozesses herstellen möchten, fügen Sie zuerst einen Listener für das Ereignis Target.attachedToTarget hinzu:

browser.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 browser.debugger.sendCommand(session, "Runtime.enable");
  }
});

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

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

Das automatische Anhängen erfolgt nur an Frames, die dem Ziel bekannt sind. Dies ist auf Frames beschränkt, die direkte untergeordnete Elemente eines mit dem Ziel verknüpften Frames sind. Wenn Sie beispielsweise die Frame-Hierarchie A -> B -> C haben (wobei alle ursprungsübergreifend sind) und Target.setAutoAttach für das mit A verknüpfte Ziel aufrufen, wird die Sitzung auch an B angehängt. 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 ausprobieren möchten, installieren Sie das Debugger API-Beispiel aus dem Repository chrome-extension-samples.

Typen

Debuggee

Debuggee-ID. Es muss entweder „tabId“, „extensionId“ oder „targetId“ angegeben werden.

Attribute

  • extensionId

    String optional

    Die ID der Erweiterung, die Sie debuggen möchten. Das Anhängen an eine Hintergrundseite einer Erweiterung ist nur möglich, wenn der Befehlszeilenschalter --silent-debugger-extension-api verwendet wird.

  • tabId

    number optional

    Die ID des Tabs, den Sie debuggen möchten.

  • targetId

    String optional

    Die intransparente ID des Debug-Ziels.

DebuggerSession

Chrome 125 und höher browser.* seit Chrome 148

Debugger-Sitzungs-ID. Es muss entweder „tabId“, „extensionId“ oder „targetId“ angegeben werden. Zusätzlich kann eine optionale sessionId angegeben werden. Wenn „sessionId“ für Argumente angegeben ist, die von onEvent gesendet werden, bedeutet das, dass das Ereignis von einer untergeordneten Protokollsitzung innerhalb der Stamm-Debuggee-Sitzung stammt. Wenn „sessionId“ bei der Übergabe an sendCommand angegeben wird, wird eine untergeordnete Protokollsitzung innerhalb der Stamm-Debuggee-Sitzung als Ziel verwendet.

Attribute

  • extensionId

    String optional

    Die ID der Erweiterung, die Sie debuggen möchten. Das Anhängen an eine Hintergrundseite einer Erweiterung ist nur möglich, wenn der Befehlszeilenschalter --silent-debugger-extension-api verwendet wird.

  • sessionId

    String optional

    Die opake ID der Chrome-Entwicklertools-Protokoll-Sitzung. Identifiziert eine untergeordnete Sitzung innerhalb der Stammsitzung, die durch „tabId“, „extensionId“ oder „targetId“ identifiziert wird.

  • tabId

    number optional

    Die ID des Tabs, den Sie debuggen möchten.

  • targetId

    String optional

    Die intransparente ID des Debug-Ziels.

DetachReason

Chrome 44 und höher browser.* seit Chrome 148

Grund für die Beendigung der Verbindung.

Enum

"target_closed"

"canceled_by_user"

TargetInfo

Informationen zum Debug-Ziel

Attribute

  • Hinzugefügt

    boolean

    „True“, wenn der Debugger bereits angehängt ist.

  • extensionId

    String optional

    Die Erweiterungs-ID, die definiert ist, wenn „type“ = „background_page“.

  • faviconUrl

    String optional

    Ziel-Favicon-URL.

  • id

    String

    Ziel-ID.

  • tabId

    number optional

    Die Tab-ID, definiert, wenn type == 'page'.

  • Titel

    String

    Seitentitel der Zielseite.

  • Zieltyp.

  • URL

    String

    Ziel-URL.

TargetInfoType

Chrome 44 und höher browser.* seit Chrome 148

Zieltyp.

Enum

"page"

"background_page"

"worker"

"other"

Methoden

attach()

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

Hängt den Debugger an das angegebene Ziel an.

Parameter

  • Ziel

    Debuggee

    Debugging-Ziel, an das Sie anhängen möchten.

  • requiredVersion

    String

    Erforderliche Version des Debugging-Protokolls („0.1“). Sie können nur eine Verbindung zum Debuggee mit der übereinstimmenden Hauptversion und einer höheren oder gleichen Nebenversion herstellen. Eine Liste der Protokollversionen finden Sie hier.

Ausgabe

  • Promise<void>

    Chrome 96+ browser.* seit Chrome 148

    Wird aufgelöst, sobald der Anhängevorgang erfolgreich ist oder fehlschlägt. Das Promise wird ohne Wert aufgelöst. Wenn das Anhängen fehlschlägt, wird das Promise abgelehnt.

detach()

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

Trennt den Debugger vom angegebenen Ziel.

Parameter

  • Ziel

    Debuggee

    Debugging-Ziel, von dem Sie die Verbindung trennen möchten.

Ausgabe

  • Promise<void>

    Chrome 96+ browser.* seit Chrome 148

    Wird aufgelöst, sobald der Trennvorgang erfolgreich ist oder fehlschlägt. Das Promise wird ohne Wert aufgelöst. Wenn das Trennen fehlschlägt, wird das Promise abgelehnt.

getTargets()

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

Gibt die Liste der verfügbaren Debugging-Ziele zurück.

Ausgabe

  • Promise<TargetInfo[]>

    Chrome 96+ browser.* seit Chrome 148

sendCommand()

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

Sendet den angegebenen Befehl an das Debugging-Ziel.

Parameter

  • Debugging-Ziel, an das Sie den Befehl senden möchten.

  • method

    String

    Methodenname. Sollte eine der Methoden sein, die im Remote-Debugging-Protokoll definiert sind.

  • commandParams

    Objekt optional

    JSON-Objekt mit Anfrageparametern. Dieses Objekt muss dem Remote-Debugging-Parameterschema für die angegebene Methode entsprechen.

Ausgabe

  • Promise<object | undefined>

    Chrome 96+ browser.* seit Chrome 148

    Antworttext. Wenn beim Posten der Nachricht ein Fehler auftritt, wird das Promise abgelehnt.

Ereignisse

onDetach

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

Wird ausgelöst, wenn der Browser die Fehlerbehebungssitzung für den Tab beendet. Das passiert, wenn entweder der Tab geschlossen oder die Chrome-Entwicklertools für den angehängten Tab aufgerufen werden.

Parameter

onEvent

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

Wird ausgelöst, wenn das Debugging-Ziel ein Instrumentierungsereignis ausgibt.

Parameter

  • callback

    Funktion

    Der Parameter callback sieht so aus: 

    (source: DebuggerSession, method: string, params?: object) => void