browser.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. 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 veya hiçbir şeyi ekleme modeli kullanarak eklemesini kısıtlayabilir (browser.debugger.attach()):

  • Düzenleyen kullanıcı kısıtlamaları: Kurumsal politika ExtensionSettings bir uzantı için engellenen ana makineleri (runtime_blocked_hosts) yapılandırırsa browser.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 browser.debugger.attach(), "Screenshot capture is restricted by policy." hatasıyla başarısız olur.

Kavramlar ve kullanım

Eklendikten sonra browser.debugger API'si, 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ıklanan 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ü (ör. iframe, shared_worker vb.) vardır.

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 browser.debugger API, 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, Runtime, Storage, Target, Tracing, WebAudio ve WebAuthn

Çerçevelerle çalışma

Çerçevelerle 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ışı kareleri 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 browser.debugger API, düz oturumları destekler. Bu sayede, ana hata ayıklayıcı oturumunuza ek hedefleri çocuk olarak ekleyebilir ve browser.debugger.attach'ya başka bir çağrı yapmanıza gerek kalmadan onlara mesaj gönderebilirsiniz. Bunun yerine, komut göndermek istediğiniz alt hedefi tanımlamak için browser.debugger.sendCommand'u çağırırken sessionId özelliği ekleyebilirsiniz.

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

browser.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 browser.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 browser.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 karelere eklenir. Bu da hedef öğeyle ilişkili bir karenin doğrudan alt öğeleri olan karelerle sınırlıdır. Örneğin, A -> B -> C çerçeve hiyerarşisinde (tümü çapraz kaynak) A ile ilişkili hedef için Target.setAutoAttach çağrıldığında oturum B'ye de eklenir. Ancak bu işlem yinelemeli değildir. Bu nedenle, oturumun C'ye eklenmesi için B için de Target.setAutoAttach çağrılmalıdır.

Ö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 program tanımlayıcısı. tabId, extensionId veya targetId belirtilmelidir

Özellikler

  • extensionId

    dize isteğe bağlı

    Hata ayıklamayı planladığınız 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ıklamasını yapmak istediğiniz sekmenin kimliği.

  • targetId

    dize isteğe bağlı

    Hata ayıklama hedefinin opak kimliği.

DebuggerSession

Chrome 125 ve sonraki sürümler

Hata ayıklayıcı oturumu tanımlayıcısı. tabId, extensionId veya targetId değerlerinden 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ıklama oturumu 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ıklamayı planladığınız 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ıklamasını yapmak istediğiniz sekmenin kimliği.

  • targetId

    dize isteğe bağlı

    Hata ayıklama hedefinin opak kimliği.

DetachReason

Chrome 44 ve sonraki sürümler

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

Enum

"target_closed"

"canceled_by_user"

TargetInfo

Hata ayıklama hedef 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ı

    Tür = "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 ve sonraki sürümler

Hedef türü.

Enum

"page"

"background_page"

"worker"

"diğer"

Yöntemler

attach()

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

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üme ve daha büyük veya eşit alt sürüme sahip olanlar hata ayıklanan işleme eklenebilir. Protokol sürümlerinin listesini buradan edinebilirsiniz.

İadeler

  • Promise<void>

    Chrome 96 ve sonraki sürümler

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

detach()

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

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

Parametreler

İadeler

  • Promise<void>

    Chrome 96 ve sonraki sürümler

    Ayırma işlemi başarılı olduğunda 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 ve sonraki sürümler

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 ve sonraki sürümler

    Yanıt gövdesi. İleti yayınlanırken bir hata oluşursa söz reddedilir.

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 yayınladığında tetiklenir.

Parametreler

  • callback

    işlev

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

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