chrome.debugger

Beschrijving

De chrome.debugger API dient als alternatief transport voor het protocol voor foutopsporing op afstand van Chrome. Gebruik chrome.debugger om aan een of meer tabbladen te koppelen om netwerkinteractie te instrumenteren, JavaScript te debuggen, de DOM en CSS te muteren, en meer. Gebruik de Debuggee eigenschap tabId om tabbladen te targeten met sendCommand en gebeurtenissen te routeren op tabId vanuit onEvent callbacks.

Machtigingen

debugger

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

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

Concepten en gebruik

Eenmaal gekoppeld, kunt u met de chrome.debugger API Chrome DevTools Protocol (CDP)-opdrachten naar een bepaald doel verzenden. Het CDP diepgaand uitleggen valt buiten het bestek van deze documentatie. Voor meer informatie over CDP kunt u de officiële CDP-documentatie raadplegen.

Doelstellingen

Doelen vertegenwoordigen iets waarvoor fouten worden opgespoord; dit kan een tabblad, een iframe of een werker zijn. Elk doel wordt geïdentificeerd door een UUID en heeft een bijbehorend type (zoals iframe , shared_worker en meer).

Binnen een doel kunnen er meerdere uitvoeringscontexten zijn; dezelfde proces-iframes krijgen bijvoorbeeld geen uniek doel, maar worden in plaats daarvan weergegeven als verschillende contexten die toegankelijk zijn vanuit één enkel doel.

Beperkte domeinen

Om veiligheidsredenen biedt de chrome.debugger API geen toegang tot alle Chrome DevTools Protocol-domeinen. De beschikbare domeinen zijn: Toegankelijkheid , Audits , CacheStorage , Console , CSS , Database , Debugger , DOM , DOMDebugger , DOMSnapshot , Emulatie , Fetch , IO , Input , Inspector , Log , Netwerk , Overlay , Pagina , Prestaties , Profiler , Runtime , Opslag , Target , Tracing , WebAudio en WebAuthn .

Werk met kaders

Er is geen één-op-één toewijzing van frames aan doelen. Binnen één tabblad kunnen meerdere dezelfde procesframes hetzelfde doel delen, maar een andere uitvoeringscontext gebruiken. Aan de andere kant kan er een nieuw doel worden gemaakt voor een iframe dat niet meer wordt verwerkt.

Om aan alle frames te bevestigen, moet u elk type frame afzonderlijk 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 frames die buiten het proces vallen te identificeren.

Nadat u verbinding heeft gemaakt met een doel, wilt u mogelijk verbinding maken met verdere gerelateerde doelen, waaronder onderliggende frames die niet in behandeling zijn of bijbehorende werkkrachten.

Vanaf Chrome 125 ondersteunt de chrome.debugger API platte sessies. Hierdoor kunt u extra doelen als onderliggende doelen toevoegen aan uw hoofdfoutopsporingssessie en hen een bericht sturen zonder dat u opnieuw chrome.debugger.attach hoeft aan te roepen. In plaats daarvan kunt u een sessionId eigenschap toevoegen wanneer u chrome.debugger.sendCommand aanroept om het onderliggende doel te identificeren waarnaar u een opdracht wilt verzenden.

Om automatisch te koppelen aan onderliggende frames die niet worden verwerkt, voegt u eerst een luisteraar 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 }]
});

Voorbeelden

Als u deze API wilt uitproberen, installeert u het debugger-API-voorbeeld uit de chrome-extension-samples- repository.

Soorten

Debuggee

Debuggee-ID. TabId, extensionId of targetId moeten worden opgegeven

Eigenschappen

  • extensieId

    tekenreeks optioneel

    De id van de extensie waarvoor u fouten wilt opsporen. Het koppelen aan een extensie-achtergrondpagina is alleen mogelijk als de opdrachtregeloptie --silent-debugger-extension-api wordt gebruikt.

  • tabId

    nummer optioneel

    De ID van het tabblad waarvoor u fouten wilt opsporen.

  • doelID

    tekenreeks optioneel

    De ondoorzichtige ID van het foutopsporingsdoel.

DebuggerSession

Chroom 125+

Identificatie van de foutopsporingssessie. Er moet een van tabId, extensionId of targetId worden opgegeven. Bovendien kan een optionele sessionId worden opgegeven. Als sessionId is opgegeven voor argumenten die worden verzonden vanuit onEvent , betekent dit dat de gebeurtenis afkomstig is van een onderliggende protocolsessie binnen de root debuggee-sessie. Als sessionId wordt opgegeven wanneer het wordt doorgegeven aan sendCommand , richt het zich op een onderliggende protocolsessie binnen de root-debuggee-sessie.

Eigenschappen

  • extensieId

    tekenreeks optioneel

    De id van de extensie waarvoor u fouten wilt opsporen. Het koppelen aan een extensie-achtergrondpagina is alleen mogelijk als de opdrachtregeloptie --silent-debugger-extension-api wordt gebruikt.

  • sessieId

    tekenreeks optioneel

    De ondoorzichtige ID van de Chrome DevTools Protocol-sessie. Identificeert een onderliggende sessie binnen de hoofdsessie, geïdentificeerd door tabId, extensionId of targetId.

  • tabId

    nummer optioneel

    De ID van het tabblad waarvoor u fouten wilt opsporen.

  • doelID

    tekenreeks optioneel

    De ondoorzichtige ID van het foutopsporingsdoel.

DetachReason

Chroom 44+

Reden voor beëindiging van de verbinding.

Enum

"doel_gesloten"

"geannuleerd_door_gebruiker"

TargetInfo

Debug doelinformatie

Eigenschappen

  • bijgevoegd

    Booleaans

    Waar als debugger al is aangesloten.

  • extensieId

    tekenreeks optioneel

    De extensie-ID, gedefinieerd als type = 'background_page'.

  • faviconUrl

    tekenreeks optioneel

    Doelfavicon-URL.

  • Identiteitskaart

    snaar

    Doel-ID.

  • tabId

    nummer optioneel

    De tabblad-ID, gedefinieerd als type == 'pagina'.

  • titel

    snaar

    Titel van doelpagina.

  • Doeltype.

  • URL

    snaar

    Doel-URL.

TargetInfoType

Chroom 44+

Doeltype.

Enum

"pagina"

"achtergrond_pagina"

"werknemer"

"ander"

Methoden

attach()

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

Koppelt debugger aan het opgegeven doel.

Parameters

  • Foutopsporing in het doel waaraan u wilt koppelen.

  • vereiste versie

    snaar

    Vereiste versie van het foutopsporingsprotocol ("0.1"). Men kan alleen aan de debuggee koppelen met een overeenkomende hoofdversie en een grotere of gelijke secundaire versie. Een lijst met de protocolversies kunt u hier verkrijgen.

  • terugbellen

    functie optioneel

    De callback parameter ziet er als volgt uit: 

    () => void

Retouren

  • Beloof <nietig>

    Chroom 96+

    Beloften worden ondersteund in Manifest V3 en hoger, maar er zijn callbacks beschikbaar voor achterwaartse compatibiliteit. U kunt niet beide gebruiken bij dezelfde functieaanroep. De belofte wordt opgelost met hetzelfde type dat wordt doorgegeven aan de callback.

detach()

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

Ontkoppelt debugger van het opgegeven doel.

Parameters

  • Foutopsporing in het doel waarvan u zich wilt losmaken.

  • terugbellen

    functie optioneel

    De callback parameter ziet er als volgt uit: 

    () => void

Retouren

  • Beloof <nietig>

    Chroom 96+

    Beloften worden ondersteund in Manifest V3 en hoger, maar er zijn callbacks beschikbaar voor achterwaartse compatibiliteit. U kunt niet beide gebruiken bij dezelfde functieaanroep. De belofte wordt opgelost met hetzelfde type dat wordt doorgegeven aan de callback.

getTargets()

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

Retourneert de lijst met beschikbare foutopsporingsdoelen.

Parameters

  • terugbellen

    functie optioneel

    De callback parameter ziet er als volgt uit: 

    (result: TargetInfo[]) => void

    • resultaat

      DoelInfo []

      Array van TargetInfo-objecten die overeenkomen met de beschikbare foutopsporingsdoelen.

Retouren

  • Beloof < DoelInfo []>

    Chroom 96+

    Beloften worden ondersteund in Manifest V3 en hoger, maar er zijn callbacks beschikbaar voor achterwaartse compatibiliteit. U kunt niet beide gebruiken bij dezelfde functieaanroep. De belofte wordt opgelost met hetzelfde type dat wordt doorgegeven aan de callback.

sendCommand()

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

Stuurt het opgegeven commando naar het foutopsporingsdoel.

Parameters

  • Foutopsporing in het doel waarnaar u de opdracht wilt verzenden.

  • methode

    snaar

    Naam van methode. Moet een van de methoden zijn die zijn gedefinieerd door het protocol voor foutopsporing op afstand .

  • commandoParams

    object optioneel

    JSON-object met aanvraagparameters. Dit object moet voldoen aan het parameterschema voor foutopsporing op afstand voor een bepaalde methode.

  • terugbellen

    functie optioneel

    De callback parameter ziet er als volgt uit: 

    (result?: object) => void

    • resultaat

      object optioneel

      JSON-object met het antwoord. De structuur van het antwoord varieert afhankelijk van de naam van de methode en wordt gedefinieerd door het attribuut 'returns' van de opdrachtbeschrijving in het protocol voor foutopsporing op afstand.

Retouren

  • Belofte<object | ongedefinieerd>

    Chroom 96+

    Beloften worden ondersteund in Manifest V3 en hoger, maar er zijn callbacks beschikbaar voor achterwaartse compatibiliteit. U kunt niet beide gebruiken bij dezelfde functieaanroep. De belofte wordt opgelost met hetzelfde type dat wordt doorgegeven aan de callback.

Evenementen

onDetach

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

Wordt geactiveerd wanneer de browser de foutopsporingssessie voor het tabblad beëindigt. Dit gebeurt wanneer het tabblad wordt gesloten of Chrome DevTools wordt aangeroepen voor het bijgevoegde tabblad.

Parameters

onEvent

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

Wordt geactiveerd wanneer foutopsporing in de instrumentatiegebeurtenis van doelproblemen optreedt.

Parameters

  • terugbellen

    functie

    De callback parameter ziet er als volgt uit: 

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