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 einen oder mehrere Tabs anhängen, um die Netzwerkinteraktion zu erfassen, JavaScript zu debuggen, das DOM und CSS zu verändern und vieles mehr. Verwenden Sie das Debuggee-Attribut tabId, um Tabs mit sendCommand anzusteuern und Ereignisse von onEvent-Callbacks anhand von tabId 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

Nach der Verknüpfung können Sie über die chrome.debugger API Chrome DevTools Protocol-Befehle (CDP) an ein bestimmtes Ziel senden. Eine ausführliche Erklärung der CDP ist in dieser Dokumentation nicht möglich. Weitere Informationen 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 oder shared_worker).

Innerhalb eines Ziels kann es mehrere Ausführungskontexte geben. Beispielsweise erhalten iframes desselben Prozesses kein eindeutiges Ziel, sondern werden als unterschiedliche Kontexte dargestellt, auf die über ein einzelnes Ziel zugegriffen werden kann.

Eingeschränkt zulässige Domains

Aus Sicherheitsgründen bietet die chrome.debugger API keinen Zugriff auf alle Chrome DevTools-Protokolldomains. Die verfügbaren Domains sind: Barrierefreiheit, Audits, CacheStorage, Console, CSS, Datenbank, Debugger, DOM, DOMDebugger, DOMSnapshot, Emulation, Fetch, IO, Input, Inspector, Log, Netzwerk, Overlay, Seite, Leistung, Profiler, Laufzeit, Speicher, Ziel, Tracing, WebAudio und WebAuthn.

Mit Frames arbeiten

Es gibt keine eindeutige Zuordnung von Frames zu Zielen. Innerhalb eines einzelnen Tabs können mehrere Prozessframes 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 die Untertitel an 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 zugehörige Ziele anhängen, um Out-of-Process-Frames 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 Out-of-Process-Frames oder verknüpfter 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 chrome.debugger.attach noch einmal aufrufen zu müssen. Stattdessen können Sie beim Aufrufen von chrome.debugger.sendCommand eine sessionId-Property hinzufügen, um das untergeordnete Ziel anzugeben, an das ein Befehl gesendet werden soll.

Wenn Sie ein Element automatisch an 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 die automatische Anhängefunktion, indem Sie den Befehl Target.setAutoAttach mit der Option flatten = true senden:

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

Die automatische Anbringung erfolgt nur an Frames, die dem Ziel bekannt sind. Das ist auf Frames beschränkt, die unmittelbare untergeordnete Elemente eines zugehörigen Frames sind. Bei der Framehierarchie A -> B -> C (alle seitenübergreifend) würde beispielsweise der Aufruf von Target.setAutoAttach für das mit A verknüpfte Ziel dazu führen, dass die Sitzung auch mit B verknüpft wird. Dies ist jedoch nicht rekursiv. Daher muss Target.setAutoAttach auch für B aufgerufen werden, damit die Sitzung an C angehängt werden kann.

Beispiele

Wenn Sie diese API ausprobieren 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 Hintergrundseite der 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

Debugger-Sitzungs-ID. Es muss eine der Optionen „tabId“, „extensionId“ oder „targetId“ angegeben werden. Optional kann auch eine „sessionId“ angegeben werden. Wenn „sessionId“ für Argumente angegeben ist, die von onEvent gesendet werden, stammt das Ereignis aus einer untergeordneten Protokollsitzung innerhalb der übergeordneten Debuggee-Sitzung. Wenn „sessionId“ angegeben wird, wenn sie an sendCommand übergeben wird, wird eine untergeordnete Protokollsitzung innerhalb der übergeordneten Debuggee-Sitzung anvisiert.

Attribute

  • extensionId

    String optional

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

  • sessionId

    String optional

    Die verschlüsselte ID der Chrome-Entwicklertools-Protokollsitzung. Identifiziert eine untergeordnete Sitzung innerhalb der über „tabId“, „extensionId“ oder „targetId“ identifizierten Stammsitzung.

  • 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

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, definiert, wenn „type“ = „background_page“ ist.

  • faviconUrl

    String optional

    Ziel-Favicon-URL.

  • id

    String

    Ziel-ID.

  • tabId

    number optional

    Die Tab-ID, definiert, wenn „type“ == „page“ ist.

  • Titel

    String

    Titel der Landingpage.

  • Zieltyp

  • URL

    String

    Ziel-URL

TargetInfoType

Chrome 44 und höher

Zieltyp

Enum

"page"

"background_page"

"worker"

„Sonstiges“

Methoden

attach()

Promise 
chrome.debugger.attach(
  target: Debuggee,
  requiredVersion: string,
  callback?: function,
)

Hängt den Debugger an das angegebene Ziel an.

Parameter

  • Ziel

    Debuggee

    Debug-Ziel, an das Sie eine Verbindung herstellen möchten.

  • requiredVersion

    String

    Erforderliche Version des Debugging-Protokolls („0.1“). Es kann nur eine Verbindung zum zu überwachenden Programm mit derselben Hauptversion und einer höheren oder gleichwertigen Nebenversion hergestellt werden. Eine Liste der Protokollversionen finden Sie hier.

  • callback

    function optional

    Der Parameter callback sieht so aus: 

    () => void

Ausgabe

  • Promise<void>

    Chrome 96 und höher

    Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks sind für die Abwärtskompatibilität verfügbar. Sie können nicht beide für denselben Funktionsaufruf verwenden. Das Versprechen wird mit demselben Typ aufgelöst, der an den Rückruf übergeben wird.

detach()

Promise 
chrome.debugger.detach(
  target: Debuggee,
  callback?: function,
)

Trennt den Debugger vom angegebenen Ziel.

Parameter

  • Ziel

    Debuggee

    Debug-Ziel, das Sie trennen möchten.

  • callback

    function optional

    Der Parameter callback sieht so aus: 

    () => void

Ausgabe

  • Promise<void>

    Chrome 96 und höher

    Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks sind für die Abwärtskompatibilität verfügbar. Sie können nicht beide für denselben Funktionsaufruf verwenden. Das Versprechen wird mit demselben Typ aufgelöst, der an den Rückruf übergeben wird.

getTargets()

Promise 
chrome.debugger.getTargets(
  callback?: function,
)

Liste der verfügbaren Debug-Ziele zurückgeben

Parameter

  • callback

    function optional

    Der Parameter callback sieht so aus: 

    (result: TargetInfo[]) => void

    • Ergebnis

      TargetInfo[]

      Array von TargetInfo-Objekten, die den verfügbaren Debugzielen entsprechen.

Ausgabe

  • Promise<TargetInfo[]>

    Chrome 96 und höher

    Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks sind für die Abwärtskompatibilität verfügbar. Sie können nicht beide für denselben Funktionsaufruf verwenden. Das Versprechen wird mit demselben Typ aufgelöst, der an den Rückruf übergeben wird.

sendCommand()

Promise 
chrome.debugger.sendCommand(
  target: DebuggerSession,
  method: string,
  commandParams?: object,
  callback?: function,
)

Sendet den angegebenen Befehl an das Debug-Ziel.

Parameter

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

  • method

    String

    Methodenname. Muss eine der Methoden sein, die vom Remote-Debugging-Protokoll definiert sind.

  • commandParams

    object optional

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

  • callback

    function optional

    Der Parameter callback sieht so aus: 

    (result?: object) => void

    • Ergebnis

      object optional

      JSON-Objekt mit der Antwort. Die Struktur der Antwort variiert je nach Methodenname und wird durch das Attribut „returns“ der Befehlsbeschreibung im Remote-Debugging-Protokoll definiert.

Ausgabe

  • Promise<object | undefined>

    Chrome 96 und höher

    Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks sind für die Abwärtskompatibilität verfügbar. Sie können nicht beide für denselben Funktionsaufruf verwenden. Das Versprechen wird mit demselben Typ aufgelöst, der an den Rückruf übergeben wird.

Ereignisse

onDetach

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

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

Parameter

onEvent

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

Wird ausgelöst, wenn beim Debuggen des Ziels ein Instrumentierungsereignis auftritt.

Parameter

  • callback

    Funktion

    Der Parameter callback sieht so aus: 

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