chrome.debugger

Beschrijving

Machtigingen

U moet de machtiging "debugger" in het manifest van uw extensie declareren om deze API te gebruiken.

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

Begrippen en gebruik

Eenmaal gekoppeld, kunt u met de chrome.debugger API Chrome DevTools Protocol (CDP)-opdrachten naar een bepaald doel sturen. Een uitgebreide uitleg van CDP valt buiten het bestek van deze documentatie. Raadpleeg de officiële CDP-documentatie voor meer informatie over CDP.

Doelen

Targets vertegenwoordigen iets dat wordt gedebugd – dit kan een tabblad, een iframe of een worker zijn. Elk target wordt geïdentificeerd door een UUID en heeft een bijbehorend type (zoals iframe , shared_worker , enzovoort).

Binnen een doel kunnen er meerdere uitvoeringscontexten zijn. Zo krijgen dezelfde proces-iframes geen uniek doel, maar worden ze weergegeven als verschillende contexten die toegankelijk zijn vanaf één doel.

Beperkte domeinen

Om veiligheidsredenen biedt de chrome.debugger API geen toegang tot alle Chrome DevTools Protocol-domeinen. De beschikbare domeinen zijn: 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 en WebAuthn .

Werken met frames

Er is geen één-op-één-koppeling van frames aan targets. Binnen één tabblad kunnen meerdere frames van hetzelfde proces hetzelfde target delen, maar een andere uitvoeringscontext gebruiken. Aan de andere kant kan er een nieuw target worden aangemaakt voor een out-of-process iframe.

Om aan alle frames te kunnen bevestigen, moet u elk type frame apart behandelen:

• Luister naar de gebeurtenis Runtime.executionContextCreated om nieuwe uitvoeringscontexten te identificeren die aan dezelfde procesframes zijn gekoppeld.

• Volg de stappen om aan gerelateerde doelen te koppelen om out-of-proces frames te identificeren.

Koppelen aan gerelateerde doelen

Nadat u verbinding hebt gemaakt met een doel, wilt u mogelijk verbinding maken met gerelateerde doelen, zoals out-of-process-subframes of bijbehorende workers.

Vanaf Chrome 125 ondersteunt de chrome.debugger API platte sessies. Hiermee kunt u extra targets als onderliggende targets aan uw hoofddebuggersessie toevoegen en deze een bericht sturen zonder dat u chrome.debugger.attach opnieuw hoeft aan te roepen. In plaats daarvan kunt u een sessionId -eigenschap toevoegen wanneer u chrome.debugger.sendCommand aanroept om de onderliggende target te identificeren waarnaar u een opdracht wilt verzenden.

Om automatisch aan onderliggende frames buiten het proces te koppelen, voegt u eerst een listener toe voor de gebeurtenis Target.attachedToTarget :

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");
  }
});

Schakel vervolgens automatisch koppelen in door de opdracht Target.setAutoAttach te verzenden met de optie flatten ingesteld op true :

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

Auto-attach koppelt alleen aan frames waarvan het doel op de hoogte is, en is beperkt tot frames die directe onderliggende frames zijn van een frame dat eraan gekoppeld is. Bijvoorbeeld, met de framehiërarchie A -> B -> C (waarbij alle frames cross-origin zijn), zou het aanroepen van Target.setAutoAttach voor het doel dat aan A gekoppeld is, ertoe leiden dat de sessie ook aan B gekoppeld wordt. Dit is echter niet recursief, dus moet Target.setAutoAttach ook aangeroepen worden zodat B de sessie aan C kan koppelen.

Voorbeelden

Om deze API uit te proberen, installeert u het debugger API-voorbeeld uit de chrome-extension-samples repository.

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

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

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

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

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

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