chrome.debugger

Beschreibung

Die chrome.debugger API dient als alternativer Transport für das Remote-Debugging-Protokoll von Chrome. Mit chrome.debugger können Sie eine oder mehrere Tabs anhängen, um Netzwerkinteraktionen zu analysieren, JavaScript zu debuggen, das DOM und CSS zu ändern und vieles mehr. Verwenden Sie das Attribut Debuggee tabId, um Tabs mit sendCommand auszurichten und Ereignisse über 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",
  ],
  ...
}

Konzepte und Verwendung

Nachdem das Ziel angehängt wurde, können Sie mit der chrome.debugger API Chrome-Entwicklertools-Protokoll-Befehle (CDP) an ein bestimmtes Ziel senden. Eine ausführliche Beschreibung der 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, z. B. ein Tab, ein iFrame oder ein Worker. Jedes Ziel wird durch eine UUID identifiziert und hat einen zugehörigen Typ (z. B. iframe oder shared_worker).

Innerhalb eines Ziels kann es mehrere Ausführungskontexte geben. Iframe-Elemente im selben Prozess erhalten beispielsweise 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 DevTools Protocol-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, Profiler, Runtime, Storage, Target, Tracing, WebAudio und WebAuthn.

Mit Frames arbeiten

Es gibt keine 1:1-Zuordnung von Frames zu Zielen. Auf einem einzelnen Tab können mehrere Frames desselben Prozesses dasselbe Ziel haben, aber einen anderen Ausführungskontext verwenden. 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 Runtime.executionContextCreated-Ereignis, um neue Ausführungskontexte zu identifizieren, die mit denselben Prozess-Frames verknüpft sind.

  • Folgen Sie der Anleitung zum Anhängen an zugehörige Ziele, um Frames zu identifizieren, die nicht im Prozess enthalten sind.

Nachdem Sie eine Verbindung zu einem Ziel hergestellt haben, möchten Sie möglicherweise 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 chrome.debugger API flache Sitzungen. So können Sie Ihrer Haupt-Debuggersitzung zusätzliche Ziele als untergeordnete Elemente hinzufügen und ihnen Nachrichten senden, ohne einen weiteren Aufruf von chrome.debugger.attach zu benötigen. Stattdessen können Sie beim Aufrufen von chrome.debugger.sendCommand das Attribut sessionId hinzufügen, um das untergeordnete Ziel zu identifizieren, an das Sie einen Befehl senden möchten.

Wenn Sie automatisch an untergeordnete Frames außerhalb des Prozesses anhängen möchten, fügen Sie zuerst einen Listener für das Target.attachedToTarget-Ereignis 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 auto attach, indem Sie den Befehl Target.setAutoAttach mit der Option flatten auf true festlegen:

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

„Auto-attach“ wird nur an Frames angehängt, die dem Ziel bekannt sind. Das sind nur Frames, die unmittelbare untergeordnete Elemente eines zugehörigen Frames sind. Beispiel: Bei der Frame-Hierarchie A -> B -> C (alle sind ursprungsübergreifend) würde der Aufruf von Target.setAutoAttach für das mit A verknüpfte Ziel dazu führen, 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.

Typen

Debuggee

Kennung der zu debuggenden Komponente. 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 Erweiterungs-Hintergrundseite 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 Debugging-Ziels.

DebuggerSession

Chrome 125 und höher

Debugger-Sitzungs-ID. Es muss entweder „tabId“, „extensionId“ oder „targetId“ angegeben werden. Außerdem kann optional eine sessionId angegeben werden. Wenn „sessionId“ für Argumente angegeben wird, die von onEvent gesendet werden, bedeutet das, dass das Ereignis aus einer untergeordneten Protokollsitzung innerhalb der Debuggee-Stammsitzung stammt. Wenn „sessionId“ angegeben wird, wenn es an sendCommand übergeben wird, wird eine untergeordnete Protokollsitzung innerhalb der Debuggee-Stammsitzung angesprochen.

Attribute

  • extensionId

    String optional

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

  • sessionId

    String optional

    Die verschlüsselte ID der Chrome-Entwicklertools-Protokollsitzung. Gibt eine untergeordnete Sitzung innerhalb der Stammsitzung an, 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 Debugging-Ziels.

DetachReason

Chrome 44 und höher

Grund für die Beendigung der Verbindung.

Enum

"target_closed"

"canceled_by_user"

TargetInfo

Informationen zum Debugging-Ziel

Attribute

  • Hinzugefügt

    boolean

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

  • extensionId

    String optional

    Die Erweiterungs-ID, die definiert wird, 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

    Titel der Zielseite.

  • Zieltyp.

  • URL

    String

    Ziel-URL.

TargetInfoType

Chrome 44 und höher

Zieltyp.

Enum

"page"

"background_page"

"worker"

"other"

Methoden

attach()

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

Hängt den Debugger an das angegebene Ziel an.

Parameter

  • Ziel

    Debuggee

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

  • requiredVersion

    String

    Erforderliche Debugging-Protokollversion („0.1“). Die Hauptversion muss übereinstimmen und die Nebenversion muss größer oder gleich sein. Eine Liste der Protokollversionen finden Sie hier.

Ausgabe

  • Promise<void>

    Chrome 96 und höher

detach()

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

Trennt den Debugger vom angegebenen Ziel.

Parameter

  • Ziel

    Debuggee

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

Ausgabe

  • Promise<void>

    Chrome 96 und höher

getTargets()

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

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

Ausgabe

sendCommand()

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

Sendet den angegebenen Befehl an das Debugging-Ziel.

Parameter

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

  • method

    String

    Methodenname. Muss eine der Methoden sein, die durch das Remotedebugging-Protokoll definiert werden.

  • commandParams

    object optional

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

Ausgabe

  • Promise<object | undefined>

    Chrome 96 und höher

Ereignisse

onDetach

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

Wird ausgelöst, wenn der Browser die Debugging-Sitzung für den Tab beendet. Dies geschieht, wenn der Tab geschlossen wird oder Chrome-Entwicklertools für den angehängten Tab aufgerufen werden.

Parameter

onEvent

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

Wird immer ausgelöst, wenn ein Instrumentierungsereignis für das Debugging von Zielproblemen auftritt.

Parameter

  • callback

    Funktion

    Der Parameter callback sieht so aus: 

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