chrome.debugger

Beschreibung

Die chrome.debugger API dient als alternativer Transport für das Remote-Debugging-Protokoll von Chrome. Verwenden Sie chrome.debugger, um einen oder mehrere Tabs hinzuzufügen, um die Netzwerkinteraktion zu instrumentieren, JavaScript-Fehler zu beheben, das DOM und CSS zu ändern und vieles mehr. Verwende die Debuggee-Eigenschaft 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 Verwendung

Nach dem Hinzufügen der chrome.debugger API können Sie das Chrome DevTools Protocol senden. (CDP) an ein bestimmtes Ziel. Eine ausführliche Erläuterung des CDP fällt nicht in den Aufgabenbereich. für diese Dokumentation. Weitere Informationen zu CDP finden Sie in der offizielle CDP-Dokumentation.

Ziele

Ziele stellen etwas dar, das gerade geprüft wird, z. B. ein Tab, iFrame oder Worker. Jedes Ziel wird durch eine UUID identifiziert und hat eine zugehörige Typ (z. B. iframe oder shared_worker).

Innerhalb eines Ziels kann es mehrere Ausführungskontexte geben, z. B. denselben Prozess-iFrames erhalten kein eindeutiges Ziel, sondern werden Kontexte, auf die von einem einzelnen Ziel aus zugegriffen werden kann.

Eingeschränkte Domains

Aus Sicherheitsgründen bietet die chrome.debugger API nicht auf alle Chrome-Entwicklertools Zugriff Protokolldomains. Folgende Domains sind verfügbar: Barrierefreiheit im Internet, Audits, CacheStorage, Console, CSS, Datenbank, Debugger, DOM DOMDebugger, DOMSnapshot, Emulation, Abrufen, E/A, Eingabe Inspector, Protokoll, Netzwerk, Overlay, Seite, Leistung, Profiler, Laufzeit, Speicher, Ziel, Tracing WebAudio und WebAuthn.

Mit Rahmen arbeiten

Es gibt keine 1:1-Zuordnung von Frames zu Zielen. Auf einem einzelnen Tab Mehrere dieselben Prozessframes haben möglicherweise dasselbe Ziel, verwenden aber ein anderes Ausführungskontext. Andererseits kann ein neues Ziel die für einen Out-of-Process-iFrame erstellt wurden.

Um sie an allen Frames anzubringen, müssen Sie jeden Frame-Typ separat handhaben:

  • Auf das Ereignis Runtime.executionContextCreated warten, um neue zu identifizieren Ausführungskontexte, die mit denselben Prozess-Frames verknüpft sind.

  • Folgen Sie der Anleitung zum Anhängen an zugehörige Ziele, um Out-of-Process-Frames zu identifizieren.

Nachdem Sie eine Verbindung zu einem Ziel hergestellt haben, sollten Sie eine Verbindung zu weiteren verwandten Zielen herstellen einschließlich untergeordneter Out-of-Process-Frames oder zugehöriger Worker.

Ab Chrome 125 unterstützt die chrome.debugger API Flat Sessions. Dieses können Sie Ihrer Haupt-Debugger-Sitzung zusätzliche Ziele als untergeordnete Ziele hinzufügen. Nachrichten senden, ohne chrome.debugger.attach noch einmal anrufen zu müssen. Stattdessen kannst du eine sessionId-Property hinzufügen, wenn du chrome.debugger.sendCommand für und geben Sie das untergeordnete Ziel an, an das Sie einen Befehl senden möchten.

Fügen Sie zum automatischen Anhängen an untergeordnete Frames außerhalb der Verarbeitung zunächst einen Listener für Das Target.attachedToTarget-Ereignis:

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 automatisches Anhängen, indem Sie den Befehl Target.setAutoAttach mit ist die Option flatten auf true festgelegt:

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

Beispiele

Wenn Sie diese API ausprobieren möchten, installieren Sie das Debugger API-Beispiel aus chrome-extension-samples. zu erstellen.

Typen

Debuggee

Die ID 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 Erweiterungshintergrundseite ist nur bei Verwendung des --silent-debugger-extension-api-Befehlszeilenparameters möglich.

  • tabId

    Zahl 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 für Argumente, die von onEvent gesendet werden, „sessionId“ angegeben ist, stammt das Ereignis aus einer Sitzung mit einem untergeordneten Protokoll in der Sitzung der zu debuggenden Root-Komponente. Wenn bei der Übergabe an sendCommand die sessionId angegeben wird, wird eine untergeordnete Protokollsitzung innerhalb der Sitzung der zu debuggenden Root-Komponente verwendet.

Attribute

  • extensionId

    String optional

    Die ID der Erweiterung, die Sie debuggen möchten. Das Anhängen an eine Erweiterungshintergrundseite ist nur bei Verwendung des --silent-debugger-extension-api-Befehlszeilenparameters möglich.

  • sessionId

    String optional

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

  • tabId

    Zahl optional

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

  • targetId

    String optional

    Die intransparente ID des Fehlerbehebungsziels.

DetachReason

Chrome (ab Version 44)

Grund für Verbindungsabbruch.

Enum

"target_closed"

"canceled_by_user"

TargetInfo

Zielinformationen zur Fehlerbehebung

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

    Zahl optional

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

  • Titel

    String

    Titel der Landingpage.

  • Zieltyp.

  • URL

    String

    Ziel-URL

TargetInfoType

Chrome (ab Version 44)

Zieltyp.

Enum

„Seite“

"background_page"

"Mitarbeiter"

"Sonstiges"

Methoden

attach()

<ph type="x-smartling-placeholder"></ph> Versprechen 
chrome.debugger.attach(
  target: Debuggee,
  requiredVersion: string,
  callback?: function,
)

Hängt den Debugger an das angegebene Ziel an.

Parameter

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

  • requiredVersion

    String

    Erforderliche Version des Debugging-Protokolls ("0.1") Die zu debuggende Komponente kann nur mit einer übereinstimmenden Hauptversion und einer höheren oder gleichen Nebenversion an die zu debuggende Komponente angehängt werden. Eine Liste der Protokollversionen finden Sie hier.

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

    () => void

Gibt Folgendes zurück:

  • Versprechen<void>

    Chrome 96 und höher

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks sind jedoch für Abwärtskompatibilität. Sie können nicht beide in demselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das Callback übergeben wird.

detach()

<ph type="x-smartling-placeholder"></ph> Versprechen 
chrome.debugger.detach(
  target: Debuggee,
  callback?: function,
)

Trennt den Debugger vom angegebenen Ziel.

Parameter

  • Debuggingziel, von dem Sie die Verbindung trennen möchten

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

    () => void

Gibt Folgendes zurück:

  • Versprechen<void>

    Chrome 96 und höher

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks sind jedoch für Abwärtskompatibilität. Sie können nicht beide in demselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das Callback übergeben wird.

getTargets()

<ph type="x-smartling-placeholder"></ph> 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: <ph type="x-smartling-placeholder"></ph>

    (result: TargetInfo[]) => void

    • Ergebnis

      TargetInfo[]

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

Gibt Folgendes zurück:

  • Promise&lt;TargetInfo[]&gt;

    Chrome 96 und höher

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks sind jedoch für Abwärtskompatibilität. Sie können nicht beide in demselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das Callback übergeben wird.

sendCommand()

<ph type="x-smartling-placeholder"></ph> Versprechen 
chrome.debugger.sendCommand(
  target: DebuggerSession,
  method: string,
  commandParams?: object,
  callback?: function,
)

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 durch das Remote-Debugging-Protokoll definierten Methoden sein.

  • commandParams

    Objekt optional

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

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

    (result?: object) => void

    • Ergebnis

      Objekt optional

      JSON-Objekt mit der Antwort. Die Struktur der Antwort variiert je nach Methodenname und wird durch die "returns"- Attribut der Befehlsbeschreibung im Remote-Debugging-Protokoll.

Gibt Folgendes zurück:

  • Promise&lt;object | nicht definiert>

    Chrome 96 und höher

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks sind jedoch für Abwärtskompatibilität. Sie können nicht beide in demselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das Callback übergeben wird.

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 entweder der Tab 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 beim Debugging des Ziels Probleme mit dem Instrumentierungsereignis auftreten.

Parameter

  • callback

    Funktion

    Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

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