chrome.debugger

Beschrijving

De chrome.debugger API dient als alternatief transportmechanisme voor het externe debugprotocol van Chrome. Gebruik chrome.debugger om verbinding te maken met een of meer tabbladen om netwerkinteractie te instrumenteren, JavaScript te debuggen, de DOM en CSS te wijzigen en meer. Gebruik de eigenschap tabId Debuggee om tabbladen te targeten met sendCommand en gebeurtenissen te routeren op basis van tabId vanuit onEvent -callbacks.

Toestemmingen

debugger

Om deze API te kunnen gebruiken, moet u de "debugger" -machtiging in het manifest van uw extensie declareren.

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

Concepten en gebruik

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

Doelen

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

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

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 .

Werk met kaders

Er is geen één-op-één-relatie tussen frames en targets. Binnen één tabblad kunnen meerdere frames van hetzelfde proces hetzelfde target delen, maar een verschillende uitvoeringscontext gebruiken. Aan de andere kant kan er een nieuw target worden aangemaakt voor een iframe dat buiten het proces draait.

Om aan alle frames te bevestigen, moet u elk frametype afzonderlijk behandelen:

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

  • Volg de stappen om verbinding te maken met gerelateerde doelen om frames te identificeren die niet in het proces zijn opgenomen.

Nadat u verbinding hebt gemaakt met een doel, wilt u mogelijk ook verbinding maken met andere gerelateerde doelen, zoals onderliggende frameworks of bijbehorende workers.

Vanaf Chrome 125 ondersteunt de chrome.debugger API platte sessies. Hierdoor kunt u extra doelen als onderliggende processen aan uw hoofddebuggersessie toevoegen en er berichten naar sturen zonder dat u opnieuw chrome.debugger.attach hoeft aan te roepen. In plaats daarvan kunt u een sessionId eigenschap toevoegen bij het aanroepen van chrome.debugger.sendCommand om het onderliggende doel te identificeren waarnaar u een opdracht wilt sturen.

Om automatisch verbinding te maken met onderliggende frames die niet in hetzelfde proces draaien, voegt u eerst een listener toe voor de Target.attachedToTarget -gebeurtenis:

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 zich alleen aan frames waarvan het doel op de hoogte is, wat beperkt is tot frames die directe kinderen zijn van een frame dat eraan is gekoppeld. Bijvoorbeeld, met de framehiërarchie A -> B -> C (waarbij alle frames van een andere oorsprong zijn), zou het aanroepen van Target.setAutoAttach voor het doel dat is gekoppeld aan A ertoe leiden dat de sessie ook aan B wordt gekoppeld. Dit is echter niet recursief, dus Target.setAutoAttach moet ook worden aangeroepen zodat B de sessie aan C koppelt.

Voorbeelden

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

Soorten

Debuggee

Identificatiecode van de te debuggen applicatie. TabId, extensionId of targetId moet worden opgegeven.

Eigenschappen

  • extensie-ID

    string optioneel

    De ID van de extensie die u wilt debuggen. Het koppelen aan een achtergrondpagina van een extensie is alleen mogelijk wanneer de opdrachtregeloptie --silent-debugger-extension-api wordt gebruikt.

  • tabId

    nummer optioneel

    De ID van het tabblad dat u wilt debuggen.

  • doel-ID

    string optioneel

    De ondoorzichtige ID van het debugdoel.

DebuggerSession

Chrome 125+

Identificatiecode van de debugsessie. Een van de volgende waarden moet worden opgegeven: tabId, extensionId of targetId. Daarnaast kan optioneel een sessionId worden opgegeven. Als sessionId wordt opgegeven voor argumenten die worden verzonden vanuit onEvent , betekent dit dat de gebeurtenis afkomstig is van een subprotocolsessie binnen de hoofddebugsessie. Als sessionId wordt opgegeven bij het doorgeven aan sendCommand , is de gebeurtenis gericht op een subprotocolsessie binnen de hoofddebugsessie.

Eigenschappen

  • extensie-ID

    string optioneel

    De ID van de extensie die u wilt debuggen. Het koppelen aan een achtergrondpagina van een extensie is alleen mogelijk wanneer de opdrachtregeloptie --silent-debugger-extension-api wordt gebruikt.

  • sessie-ID

    string optioneel

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

  • tabId

    nummer optioneel

    De ID van het tabblad dat u wilt debuggen.

  • doel-ID

    string optioneel

    De ondoorzichtige ID van het debugdoel.

DetachReason

Chrome 44+

Reden voor het verbreken van de verbinding.

Enum

"doel_gesloten"

"geannuleerd_door_gebruiker"

TargetInfo

Foutopsporingsdoelinformatie

Eigenschappen

  • bijgevoegd

    booleaans

    Retourneert true als de debugger al is gekoppeld.

  • extensie-ID

    string optioneel

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

  • faviconUrl

    string optioneel

    Doel-URL voor het favicon.

  • id

    snaar

    Doel-ID.

  • tabId

    nummer optioneel

    De tab-ID, gedefinieerd als type == 'page'.

  • titel

    snaar

    Doelpaginatitel.

  • Doeltype.

  • URL

    snaar

    Doel-URL.

TargetInfoType

Chrome 44+

Doeltype.

Enum

"pagina"

"achtergrondpagina"

"werknemer"

"ander"

Methoden

attach()

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

Koppelt de debugger aan het opgegeven doel.

Parameters

  • doel

    Debuggee

    Het debugdoel waaraan u zich wilt koppelen.

  • vereiste versie

    snaar

    Vereiste debugprotocolversie ("0.1"). Men kan alleen verbinding maken met het te debuggen systeem met een overeenkomende hoofdversie en een subversie die groter of gelijk is aan die versie. Een lijst met protocolversies is hier te vinden.

Retourneert

  • Promise<void>

    Chrome 96+

    De promise wordt opgelost zodra de koppelingsbewerking slaagt of mislukt. De promise wordt opgelost zonder waarde. Als de koppeling mislukt, wordt de promise afgewezen.

detach()

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

Ontkoppelt de debugger van het opgegeven doel.

Parameters

  • doel

    Debuggee

    Het debugdoel waarvan u zich wilt loskoppelen.

Retourneert

  • Promise<void>

    Chrome 96+

    De promise wordt opgelost zodra de ontkoppelingsbewerking slaagt of mislukt. De promise wordt opgelost zonder waarde. Als de ontkoppeling mislukt, wordt de promise afgewezen.

getTargets()

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

Geeft de lijst met beschikbare debugdoelen weer.

Retourneert

sendCommand()

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

Verstuurt het opgegeven commando naar het debugdoel.

Parameters

  • Het debugdoel waarnaar u de opdracht wilt verzenden.

  • methode

    snaar

    Methodenaam. Dit moet een van de methoden zijn die gedefinieerd zijn door het protocol voor debuggen op afstand .

  • commandoParams

    object optioneel

    JSON-object met verzoekparameters. Dit object moet voldoen aan het parameterschema voor debuggen op afstand voor de betreffende methode.

Retourneert

  • Promise<object | undefined>

    Chrome 96+

    De reactiebody. Als er een fout optreedt tijdens het verzenden van het bericht, wordt de promise afgewezen.

Evenementen

onDetach

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

Deze gebeurtenis wordt geactiveerd wanneer de browser de debugsessie voor het tabblad beëindigt. Dit gebeurt wanneer het tabblad wordt gesloten of wanneer Chrome DevTools wordt geopend voor het gekoppelde tabblad.

Parameters

onEvent

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

Wordt geactiveerd wanneer het debugdoel een instrumentatiegebeurtenis genereert.

Parameters

  • terugbelverzoek

    functie

    De callback parameter ziet er als volgt uit: 

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