chrome.debugger

Açıklama

chrome.debugger API, Chrome'un uzaktan hata ayıklama protokolü için alternatif bir aktarım görevi görür. Ağ etkileşimini ölçmek, JavaScript'te hata ayıklamak, DOM ve CSS'yi değiştirmek ve daha fazlası için chrome.debugger simgesini kullanarak bir veya daha fazla sekmeye bağlanın. Debuggee özelliğini kullanarak sendCommand ile sekmeleri hedefleyin ve onEvent geri çağırmalarından gelen etkinlikleri tabId ile yönlendirin.tabId

İzinler

debugger

Bu API'yi kullanmak için uzantınızın manifest dosyasında "debugger" iznini beyan etmeniz gerekir.

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

Kavramlar ve kullanım

Eklendikten sonra chrome.debugger API, belirli bir hedefe Chrome Geliştirici Araçları Protokolü (CDP) komutları göndermenize olanak tanır. CDP'nin ayrıntılı açıklaması bu dokümanın kapsamı dışındadır. CDP hakkında daha fazla bilgi edinmek için resmi CDP dokümanlarına göz atın.

Hedefler

Hedefler, hata ayıklaması yapılan bir şeyi temsil eder. Bu, bir sekme, bir iFrame veya bir çalışan olabilir. Her hedef bir UUID ile tanımlanır ve ilişkili bir türü vardır (ör. iframe, shared_worker vb.).

Bir hedef içinde birden fazla yürütme bağlamı olabilir. Örneğin, aynı işlemdeki iFrame'ler benzersiz bir hedef almaz ancak tek bir hedeften erişilebilen farklı bağlamlar olarak temsil edilir.

Kısıtlanmış alanlar

Güvenlik nedeniyle, chrome.debugger API'si tüm Chrome Geliştirici Araçları Protokol Alanlarına erişim sağlamaz. Kullanılabilir alanlar: 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 ve WebAuthn

Çerçevelerle çalışma

Kareler ve hedefler arasında bire bir eşleme yoktur. Tek bir sekmede, aynı işleme ait birden fazla çerçeve aynı hedefi paylaşabilir ancak farklı bir yürütme bağlamı kullanabilir. Diğer yandan, işlem dışı bir iframe için yeni bir hedef oluşturulabilir.

Tüm çerçevelere eklemek için her çerçeve türünü ayrı ayrı ele almanız gerekir:

  • Aynı işlem çerçeveleriyle ilişkili yeni yürütme bağlamlarını belirlemek için Runtime.executionContextCreated etkinliğini dinleyin.

  • İşlem dışı çerçeveleri belirlemek için ilgili hedeflere ekleme adımlarını uygulayın.

Bir hedefe bağlandıktan sonra, işlem dışı alt çerçeveler veya ilişkili çalışanlar da dahil olmak üzere ilgili diğer hedeflere bağlanmak isteyebilirsiniz.

Chrome 125'ten itibaren chrome.debugger API'si düz oturumları destekler. Bu sayede, ana hata ayıklama oturumunuza ek hedefler ekleyebilir ve chrome.debugger.attach'ya başka bir çağrı yapmanıza gerek kalmadan bu hedeflere mesaj gönderebilirsiniz. Bunun yerine, komut göndermek istediğiniz alt hedefi tanımlamak için chrome.debugger.sendCommand çağrısı yaparken sessionId özelliği ekleyebilirsiniz.

İşlem dışı alt çerçevelere otomatik olarak eklemek için önce Target.attachedToTarget etkinliği için bir dinleyici ekleyin:

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

Ardından, Target.setAutoAttach komutunu flatten seçeneği true olarak ayarlanmış şekilde göndererek otomatik ekleme'yi etkinleştirin:

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

Otomatik ekleme yalnızca hedefin farkında olduğu çerçevelere eklenir. Bu da hedefle ilişkili bir çerçevenin doğrudan alt öğeleri olan çerçevelerle sınırlıdır. Örneğin, A -> B -> C çerçeve hiyerarşisinde (tümü kaynaklar arası) A ile ilişkili hedef için Target.setAutoAttach çağrısı yapıldığında oturum B'ye de eklenir. Ancak bu işlem yinelemeli olmadığından oturumun C'ye eklenmesi için Target.setAutoAttach de çağrılmalıdır.

Örnekler

Bu API'yi denemek için chrome-extension-samples deposundan debugger API örneğini yükleyin.

Türler

Debuggee

Hata ayıklanan uygulama tanımlayıcısı. tabId, extensionId veya targetId belirtilmelidir

Özellikler

  • extensionId

    dize isteğe bağlı

    Hata ayıklamak istediğiniz uzantının kimliği. Bir uzantı arka plan sayfasına ekleme yalnızca --silent-debugger-extension-api komut satırı anahtarı kullanıldığında mümkündür.

  • tabId

    number isteğe bağlı

    Hata ayıklamak istediğiniz sekmenin kimliği.

  • targetId

    dize isteğe bağlı

    Hata ayıklama hedefinin opak kimliği.

DebuggerSession

Chrome 125+

Hata ayıklayıcı oturumu tanımlayıcısı. tabId, extensionId veya targetId özelliklerinden biri belirtilmelidir. Ayrıca, isteğe bağlı bir sessionId de sağlanabilir. onEvent öğesinden gönderilen bağımsız değişkenler için sessionId belirtilmişse etkinlik, kök hata ayıklanan oturum içindeki bir alt protokol oturumundan geliyor demektir. sendCommand'ye iletilirken sessionId belirtilirse kök hata ayıklanan oturumdaki bir alt protokol oturumunu hedefler.

Özellikler

  • extensionId

    dize isteğe bağlı

    Hata ayıklamak istediğiniz uzantının kimliği. Bir uzantı arka plan sayfasına ekleme yalnızca --silent-debugger-extension-api komut satırı anahtarı kullanıldığında mümkündür.

  • sessionId

    dize isteğe bağlı

    Chrome Geliştirici Araçları Protokolü oturumunun opak kimliği. tabId, extensionId veya targetId ile tanımlanan kök oturumdaki bir alt oturumu tanımlar.

  • tabId

    number isteğe bağlı

    Hata ayıklamak istediğiniz sekmenin kimliği.

  • targetId

    dize isteğe bağlı

    Hata ayıklama hedefinin opak kimliği.

DetachReason

Chrome 44 veya daha yeni bir sürüm

Bağlantı sonlandırma nedeni.

Enum

"target_closed"

"canceled_by_user"

TargetInfo

Hata ayıklama hedef bilgileri

Özellikler

  • ekli

    boolean

    Hata ayıklayıcı zaten eklenmişse doğru değerini döndürür.

  • extensionId

    dize isteğe bağlı

    type = "background_page" ise tanımlanan uzantı kimliği.

  • faviconUrl

    dize isteğe bağlı

    Hedef site simgesi URL'si.

  • id

    dize

    Hedef kimliği.

  • tabId

    number isteğe bağlı

    Tür == "page" ise tanımlanan sekme kimliği.

  • title

    dize

    Hedef sayfa başlığı.

  • Hedef türü.

  • url

    dize

    Hedef URL.

TargetInfoType

Chrome 44 veya daha yeni bir sürüm

Hedef türü.

Enum

"page"

"background_page"

"worker"

"other"

Yöntemler

attach()

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

Hata ayıklayıcıyı belirtilen hedefe ekler.

Parametreler

  • hedef

    Hata ayıklanan (Debuggee)

    Eklemek istediğiniz hata ayıklama hedefi.

  • requiredVersion

    dize

    Gerekli hata ayıklama protokolü sürümü ("0.1"). Yalnızca eşleşen ana sürüme ve daha büyük veya eşit küçük sürüme sahip bir hata ayıklama işlemine eklenebilir. Protokol sürümlerinin listesine buradan ulaşabilirsiniz.

İadeler

  • Promise<void>

    Chrome 96 veya daha yeni bir sürüm

detach()

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

Hata ayıklayıcıyı belirtilen hedeften ayırır.

Parametreler

  • hedef

    Hata ayıklanan (Debuggee)

    Ayrılmak istediğiniz hata ayıklama hedefi.

İadeler

  • Promise<void>

    Chrome 96 veya daha yeni bir sürüm

getTargets()

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

Kullanılabilir hata ayıklama hedeflerinin listesini döndürür.

İadeler

  • Promise<TargetInfo[]>

    Chrome 96 veya daha yeni bir sürüm

sendCommand()

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

Belirtilen komutu hata ayıklama hedefine gönderir.

Parametreler

  • Komutu göndermek istediğiniz hata ayıklama hedefi.

  • method

    dize

    Yöntem adı. Uzaktan hata ayıklama protokolü tarafından tanımlanan yöntemlerden biri olmalıdır.

  • commandParams

    object isteğe bağlı

    İstek parametrelerini içeren JSON nesnesi. Bu nesne, belirli bir yöntem için uzaktan hata ayıklama parametreleri şemasına uygun olmalıdır.

İadeler

  • Promise<object | undefined>

    Chrome 96 veya daha yeni bir sürüm

Etkinlikler

onDetach

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

Tarayıcı, sekme için hata ayıklama oturumunu sonlandırdığında tetiklenir. Bu durum, sekme kapatıldığında veya ekli sekme için Chrome Geliştirici Araçları çağrıldığında meydana gelir.

Parametreler

onEvent

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

Hata ayıklama hedefi, enstrümantasyon etkinliğini her tetiklediğinde tetiklenir.

Parametreler

  • callback

    işlev

    callback parametresi şu şekilde görünür: 

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