chrome.debugger

Beschreibung

Die chrome.debugger API dient als alternativer Transport für das Remote-Debugging-Protokoll von Chrome. Verwenden Sie chrome.debugger, um Elemente an einen oder mehrere Tabs anzuhängen, um Netzwerkinteraktionen zu instrumentieren, JavaScript-Fehler zu beheben, DOM und CSS zu ändern und vieles mehr. Verwende die Debuggee-Property tabId, um ein Targeting auf Tabs mit sendCommand vorzunehmen und Ereignisse nach tabId aus onEvent-Callbacks weiterzuleiten.

Berechtigungen

debugger

Du musst die Berechtigung „"debugger"“ im Manifest deiner Erweiterung deklarieren, um diese API verwenden zu können.

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

Konzepte und Nutzung

Nach dem Anhängen können Sie über die chrome.debugger API Befehle für das Chrome DevTools Protocol (CDP) an ein bestimmtes Ziel senden. Eine ausführliche Erläuterung der CDP ist in dieser Dokumentation nicht möglich. Weitere Informationen zu CDP finden Sie in der offiziellen CDP-Dokumentation.

Ziele

Ziele stellen etwas dar, das gerade debuggt wird – beispielsweise ein Tab, ein iFrame oder ein Worker. Jedes Ziel wird durch eine UUID identifiziert und einem zugehörigen Typ zugeordnet (z. B. iframe, shared_worker usw.).

Innerhalb eines Ziels kann es mehrere Ausführungskontexte geben. Beispielsweise erhalten dieselben Prozess-iFrames kein eindeutiges Ziel, sondern werden stattdessen als unterschiedliche Kontexte dargestellt, auf die von einem einzigen Ziel aus zugegriffen werden kann.

Eingeschränkte Domains

Aus Sicherheitsgründen bietet die chrome.debugger API nicht auf alle Protokolldomains für Chrome-Entwicklertools Zugriff. Folgende Domains stehen zur Verfügung: Accessibility, Audits, CacheStorage, Console, CSS, Database, Debugger, DOMDebugger, DOMSnapshot, DOMSnapshot, DOM,{/30,{/3,WebAudioWebAuthn

Mit Frames arbeiten

Es gibt keine 1:1-Zuordnung von Frames zu Zielen. Innerhalb eines einzelnen Tabs können mehrere gleiche Prozessframes dasselbe Ziel gemeinsam haben, aber einen anderen Ausführungskontext verwenden. Andererseits kann ein neues Ziel für einen Out-of-Process-iFrame erstellt werden.

Um sie an alle Frames anzuhängen, müssen Sie jeden Frametyp separat behandeln:

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

  • Führen Sie die Schritte zum Anhängen an zugehörige Ziele aus, um Out-of-Process-Frames zu identifizieren.

Nachdem Sie eine Verbindung zu einem Ziel hergestellt haben, möchten Sie möglicherweise eine Verbindung zu weiteren zugehörigen Zielen wie untergeordneten Frames außerhalb des Prozesses oder zugehörigen Workern herstellen.

Ab Chrome 125 unterstützt die chrome.debugger API flache Sitzungen. Auf diese Weise können Sie Ihrer Haupt-Debugger-Sitzung zusätzliche Ziele als untergeordnete Ziele hinzufügen und ihnen Nachrichten senden, ohne dass ein weiterer Aufruf von chrome.debugger.attach erforderlich ist. Stattdessen können Sie beim Aufrufen von chrome.debugger.sendCommand ein sessionId-Attribut hinzufügen, um das untergeordnete Ziel zu identifizieren, an das Sie einen Befehl senden möchten.

Fügen Sie zum automatischen Anhängen an untergeordnete Frames außerhalb des Prozesses 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. Senden Sie dazu den Befehl Target.setAutoAttach und setzen Sie die Option flatten auf true:

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

Beispiele

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

Typen

Debuggee

Kennung der zu debuggenden Komponente. Es muss entweder eine tabId, eine Erweiterungs-ID oder eine Ziel-ID angegeben werden

Attribute

  • extensionId

    String optional

    Die ID der Erweiterung, für die Sie ein Debugging ausführen möchten. Anhängen an eine Hintergrundseite einer Erweiterung sind nur möglich, wenn die --silent-debugger-extension-api-Befehlszeile verwendet wird.

  • tabId

    Nummer optional

    Die ID des Tabs, auf dem Sie Fehler beheben möchten.

  • targetId

    String optional

    Die intransparente ID des Fehlerbehebungsziels.

DebuggerSession

Chrome 125 oder höher

Debugger-Sitzungs-ID. Es muss entweder „tabId“, „extensionId“ oder „targetId“ angegeben werden. Außerdem kann eine optionale sessionId angegeben werden. Wenn „sessionId“ für Argumente angegeben ist, die von onEvent gesendet werden, bedeutet dies, dass das Ereignis aus einer untergeordneten Protokollsitzung in der Root-Sitzung der zu debuggenden Komponente stammt. Wenn bei der Übergabe an sendCommand „sessionId“ angegeben ist, wird eine untergeordnete Protokollsitzung innerhalb der Stammsitzung der zu debuggenden Komponente angesprochen.

Attribute

  • extensionId

    String optional

    Die ID der Erweiterung, für die Sie ein Debugging ausführen möchten. Anhängen an eine Hintergrundseite einer Erweiterung sind nur möglich, wenn die --silent-debugger-extension-api-Befehlszeile verwendet wird.

  • sessionId

    String optional

    Die intransparente ID der Sitzung im Chrome-Entwicklertools-Protokoll. Kennzeichnet eine untergeordnete Sitzung innerhalb der Stammsitzung, die durch tabId, ExtensionsId oder targetId identifiziert wird.

  • tabId

    Nummer optional

    Die ID des Tabs, auf dem Sie Fehler beheben möchten.

  • targetId

    String optional

    Die intransparente ID des Fehlerbehebungsziels.

DetachReason

Chrome 44 und höher

Grund für Beendigung der Verbindung.

Enum

"target_closed"

"canceled_by_user"

TargetInfo

Informationen zum Fehlerbehebungsziel

Attribute

  • Hinzugefügt

    boolean

    True, wenn Debugger bereits angehängt ist.

  • extensionId

    String optional

    Die Erweiterungs-ID, definiert, wenn type = 'background_page'.

  • faviconUrl

    String optional

    Favicon-URL des Ziels.

  • id

    String

    Ziel-ID.

  • tabId

    Nummer optional

    Die Tab-ID, definiert bei Typ == 'page'.

  • Titel

    String

    Titel der Zielseite.

  • Zieltyp.

  • url

    String

    Ziel-URL

TargetInfoType

Chrome 44 und höher

Zieltyp.

Enum

"background_page"

Methoden

attach()

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

Fügt Debugger an das angegebene Ziel an.

Parameter

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

  • requiredVersion

    String

    Erforderliche Version des Debugging-Protokolls („0.1“). Einer kann nur an die zu debuggende Komponente mit übereinstimmender Hauptversion und größerer oder gleicher Nebenversion angehängt werden. Eine Liste der Protokollversionen finden Sie hier.

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    () => void

Rückgabe

  • Promise<void>

    Chrome 96 und höher

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.

detach()

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

Trennt den Debugger vom angegebenen Ziel.

Parameter

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

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    () => void

Rückgabe

  • Promise<void>

    Chrome 96 und höher

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.

getTargets()

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

Gibt die Liste der verfügbaren Fehlerbehebungsziele zurück.

Parameter

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    (result: TargetInfo[]) => void

    • Ergebnis

      TargetInfo[]

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

Rückgabe

  • Promise<TargetInfo[]>

    Chrome 96 und höher

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.

sendCommand()

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

Sendet den angegebenen Befehl an das Debugging-Ziel.

Parameter

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

  • method

    String

    Name der Methode. Dies sollte eine der im Remote-Debugging-Protokoll definierten Methoden sein.

  • commandParams

    Objekt optional

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

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    (result?: object) => void

    • Ergebnis

      Objekt optional

      JSON-Objekt mit der Antwort. Die Struktur der Antwort hängt vom Methodennamen ab und wird durch das "returns"-Attribut der Befehlsbeschreibung im Remote-Debugging-Protokoll definiert.

Rückgabe

  • Promise<object | undefined>

    Chrome 96 und höher

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.

Veranstaltungen

onDetach

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

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

Parameter

onEvent

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

Wird ausgelöst, wenn das Instrumentierungsereignis mit dem Zielfehler behoben wird.

Parameter

  • callback

    Funktion

    Der Parameter callback sieht so aus: 

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