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 izlemek, 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. sendCommand içeren sekmeleri hedeflemek ve onEvent geri çağırmalarından gelen etkinlikleri tabId ile yönlendirmek için Debuggee özelliğini tabId 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",
  ],
  ...
}

Kurumsal politika kısıtlamaları

Kurumsal cihazlarda bazı politikalar, uzantıların hata ayıklayıcıyı ekleme sırasında her şeyi dahil etme veya hiçbir şeyi dahil etmeme modeli kullanarak eklemesini kısıtlayabilir (chrome.debugger.attach()):

  • Ana makine kısıtlamaları: Kurumsal politika ExtensionSettings bir uzantı için engellenen ana makineleri (runtime_blocked_hosts) yapılandırırsa chrome.debugger.attach(), "Host access is restricted by policy." hatasıyla tüm hedeflerde engellenir (tek tek kaynaklar runtime_allowed_hosts içinde olsa bile).
  • Ekran görüntüsü ve DLP politikaları: DisableScreenshots kurumsal politikası ekran görüntüsü almayı devre dışı bırakırsa veya hedef için veri kaybını önleme (DLP) kuralları geçerliyse chrome.debugger.attach(), "Screenshot capture is restricted by policy." hatasıyla başarısız olur.

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 belgelerine 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 şunlardır: 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 taraftan, 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 daha fazla ilgili hedefe bağlanmak isteyebilirsiniz.

Chrome 125'ten itibaren chrome.debugger API, düz oturumları destekler. Bu sayede, ana hata ayıklama oturumunuza ek hedefler ekleyebilir ve chrome.debugger.attach'a 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 özelliğini etkinleştirin:

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

Otomatik ekleme yalnızca hedef öğenin farkında olduğu çerçevelere eklenir. Bu da hedef öğeyle ilişkili bir çerçevenin hemen alt öğeleri olan çerçevelerle sınırlıdır. Örneğin, A -> B -> C çerçeve hiyerarşisinde (tümü kaynaklar arasıdır) 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 değildir. Bu nedenle, oturumu C'ye eklemek 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ıklama yapılacak uygulama tanımlayıcısı. tabId, extensionId veya targetId belirtilmelidir

Özellikler

  • extensionId

    dize isteğe bağlı

    Hatasını 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ı oturum tanımlayıcısı. tabId, extensionId veya targetId'den biri belirtilmelidir. Ek olarak, isteğe bağlı olarak bir sessionId de sağlanabilir. Gönderilen argümanlar için sessionId belirtilmişseonEvent Bu, olayın kök hata ayıklama oturumu içindeki bir alt protokol oturumundan geldiği anlamına gelir. Eğer sessionId, iletilirken belirtilirsesendCommand Bu, kök hata ayıklama oturumu içindeki bir alt protokol oturumunu hedef alır.

Özellikler

  • extensionId

    dize isteğe bağlı

    Hatasını 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 oturum içindeki 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ının kesilme nedeni.

Enum

"target_closed"

"kullanıcı_tarafından_iptal_edildi"

TargetInfo

Hata ayıklama hedefi bilgileri

Özellikler

  • ekli

    boole

    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>

Belirtilen hedefe hata ayıklayıcıyı bağlar.

Parametreler

  • Bağlanmak istediğiniz hata ayıklama hedefi.

  • requiredVersion

    dize

    Gerekli hata ayıklama protokolü sürümü ("0.1"). Yalnızca ana sürümü eşleşen ve alt sürümü ona eşit veya daha büyük olan hata ayıklanacak programa bağlanabilir. Protokol sürümlerinin listesi buradan alınabilir.

İadeler

  • Promise<void>

    Chrome 96+

    Bağlantı işlemi başarılı veya başarısız olduğunda çözümlenir. Verilen söz hiçbir değer taşımadan sona eriyor. Bağlantı başarısız olursa, vaat reddedilecektir.

detach()

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

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

Parametreler

İadeler

  • Promise<void>

    Chrome 96+

    Ayırma işlemi başarılı veya başarısız olduğunda çözülür. Promise, değer olmadan çözümlenir. Ayırma işlemi başarısız olursa söz reddedilir.

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

    Yanıt gövdesi. Mesaj gönderilirken bir hata oluşursa, işlem reddedilecektir.

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 bağlı 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 hedefinde izleme olayı meydana geldiğinde tetiklenir.

Parametreler

  • callback

    işlev

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

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