chrome.debugger

Açıklama

chrome.debugger API, Chrome'un uzak hata ayıklama protokolü için alternatif bir aktarım aracı olarak kullanılır. Ağ etkileşimini ayarlamak, JavaScript'de hata ayıklama yapmak, DOM ve CSS'yi değiştirmek ve daha fazlası için bir veya daha fazla sekmeye eklemek üzere chrome.debugger simgesini kullanın. Sekmeleri sendCommand ile hedeflemek ve etkinlikleri onEvent geri çağırmalarından tabId'a göre yönlendirmek için Debuggee tabId mülkünü kullanın.

İ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

chrome.debugger API, eklendikten sonra belirli bir hedefe Chrome DevTools Protokolü (CDP) komutları göndermenize olanak tanır. CDP'nin ayrıntılı olarak açıklanması bu dokümanın kapsamına girmiyor. 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 öğe bir sekme, bir iframe veya bir işleyici olabilir. Her hedef bir UUID ile tanımlanır ve ilişkili bir türe (ör. iframe, shared_worker vb.) sahiptir.

Bir hedefte birden fazla yürütme bağlamı olabilir. Örneğin, aynı işlem iframe'leri benzersiz bir hedef almaz, bunun yerine tek bir hedeften erişilebilen farklı bağlamlar olarak temsil edilir.

Kısıtlanmış alanlar

Güvenlik nedeniyle chrome.debugger API, tüm Chrome DevTools Protokol Alan Adlarına erişim sağlamaz. Kullanılabilir alanlar şunlardır: Erişilebilirlik, Denetimler, CacheStorage, Konsol, CSS, Veritabanı, Hata Ayıklama Aracı, DOM, DOMDebugger, DOMSnapshot, Emülasyon, Getir, IO, Giriş, İnceleyici, Günlük, Ağ, Yer paylaşımı, Sayfa, Performans, Profilleyici, Çalışma zamanı, Depolama, Hedef, İzleme, WebAudio ve WebAuthn.

Çerçevelerle çalışma

Karelerin hedeflerle bire bir eşlemesi yoktur. Tek bir sekmede, aynı işlem çerçevesinin birden fazlası aynı hedefi paylaşabilir ancak farklı bir yürütme bağlamı kullanabilir. Öte 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ı işlemeniz gerekir:

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

  • İşlem dışı çerçeveleri tanımlamak 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 diğer ilgili hedeflere bağlanmak isteyebilirsiniz.

Chrome 125'ten itibaren chrome.debugger API, düz oturumları destekler. Bu sayede, ana hata ayıklayıcı oturumunuza çocuk olarak ek hedefler ekleyebilir ve chrome.debugger.attach çağrısı 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ırken bir sessionId mülkü 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, flatten seçeneği true olarak ayarlanmışken Target.setAutoAttach komutunu göndererek otomatik eklemeyi 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 bildiği çerçevelere eklenir. Bu, kendisiyle ilişkili bir çerçevenin ilk alt çerçeveleriyle sınırlıdır. Örneğin, A -> B -> C çerçeve hiyerarşisinde (tümü kaynaktan bağımsızdır) A ile ilişkili hedef için Target.setAutoAttach çağrılırsa oturum B'ye de eklenir. Ancak bu yordam yinelemeli değildir. Bu nedenle, B'nin oturumu C'ye eklemesi için Target.setAutoAttach'nin de çağrılması gerekir.

Örnekler

Bu API'yi denemek için chrome-extension-samples deposundan hata ayıklayıcı 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ıklama yapmak istediğiniz uzantının kimliği. Uzantının arka plan sayfasına ekleme işlemi yalnızca --silent-debugger-extension-api komut satırı anahtarı kullanıldığında yapılabilir.

  • tabId

    number isteğe bağlı

    Hata ayıklama yapmak 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ı oturum tanımlayıcısı. tabId, extensionId veya targetId özelliklerinden biri belirtilmelidir. Ayrıca isteğe bağlı bir sessionId sağlanabilir. onEvent adresinden gönderilen bağımsız değişkenler için sessionId belirtilirse etkinliğin, kök hata ayıklayıcı oturumundaki bir alt protokol oturumundan geldiği anlamına gelir. sessionId, sendCommand parametresine iletilirken belirtilirse kök hata ayıklayıcı oturumundaki bir alt protokol oturumunu hedefler.

Özellikler

  • extensionId

    dize isteğe bağlı

    Hata ayıklama yapmak istediğiniz uzantının kimliği. Uzantının arka plan sayfasına ekleme işlemi yalnızca --silent-debugger-extension-api komut satırı anahtarı kullanıldığında yapılabilir.

  • sessionId

    dize isteğe bağlı

    Chrome DevTools 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ıklama yapmak istediğiniz sekmenin kimliği.

  • targetId

    dize isteğe bağlı

    Hata ayıklama hedefinin opak kimliği.

DetachReason

Chrome 44 ve üzeri sürümler

Bağlantının sonlandırılma nedeni.

Enum

"target_closed"

"canceled_by_user"

TargetInfo

Hata ayıklama hedefi bilgileri

Özellikler

  • ekli

    boolean

    Hata ayıklayıcı zaten bağlıysa 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ı

    type == "page" ise tanımlanan sekme kimliği.

  • title

    dize

    Hedef sayfa başlığı.

  • Hedef türü.

  • url

    dize

    Hedef URL.

TargetInfoType

Chrome 44 ve üzeri sürümler

Hedef türü.

Enum

"page"

"background_page"

"worker"

"other"

Yöntemler

attach()

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

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

Parametreler

  • 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üm ve daha yüksek veya eşit küçük sürüme sahip hata ayıklayıcıya bağlanılabilir. Protokol sürümlerinin listesini burada bulabilirsiniz.

  • callback

    işlev isteğe bağlı

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

    () => void

İadeler

  • Promise<void>

    Chrome 96 ve üzeri sürümler

    Sözler Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırma işlevleri sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Sözleşme, geri çağırma işlevine iletilen türün aynısıyla çözülür.

detach()

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

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

Parametreler

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

  • callback

    işlev isteğe bağlı

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

    () => void

İadeler

  • Promise<void>

    Chrome 96 ve üzeri sürümler

    Sözler Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırma işlevleri sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Sözleşme, geri çağırma işlevine iletilen türün aynısıyla çözülür.

getTargets()

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

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

Parametreler

  • callback

    işlev isteğe bağlı

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

    (result: TargetInfo[]) => void

    • sonuç

      TargetInfo[]

      Mevcut hata ayıklama hedeflerine karşılık gelen TargetInfo nesneleri dizisi.

İadeler

  • Promise<TargetInfo[]>

    Chrome 96 ve üzeri sürümler

    Sözler Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırma işlevleri sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Sözleşme, geri çağırma işlevine iletilen türün aynısıyla çözülür.

sendCommand()

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

Belirtilen komutu hata ayıklama hedefine gönderir.

Parametreler

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

  • method

    dize

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

  • commandParams

    nesne isteğe bağlı

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

  • callback

    işlev isteğe bağlı

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

    (result?: object) => void

    • sonuç

      nesne isteğe bağlı

      Yanıtı içeren JSON nesnesi. Yanıtın yapısı, yöntem adına bağlı olarak değişir ve uzak hata ayıklama protokolündeki komut açıklamasının "döndürür" özelliğiyle tanımlanır.

İadeler

  • Promise<object | undefined>

    Chrome 96 ve üzeri sürümler

    Sözler Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırma işlevleri sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Sözleşme, geri çağırma işlevine iletilen türün aynısıyla çözülür.

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 DevTools çağrıldığında gerçekleşir.

Parametreler

onEvent

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

Hata ayıklama hedefi enstrümantasyon etkinliği her tetiklendiğinde tetiklenir.

Parametreler

  • callback

    işlev

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

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