{"id":13387919,"url":"https://github.com/microsoft/dbgshell","last_synced_at":"2025-04-12T23:30:36.300Z","repository":{"id":40680486,"uuid":"104886007","full_name":"microsoft/DbgShell","owner":"microsoft","description":"A PowerShell front-end for the Windows debugger engine.","archived":false,"fork":false,"pushed_at":"2024-04-03T21:19:10.000Z","size":2256,"stargazers_count":680,"open_issues_count":21,"forks_count":89,"subscribers_count":44,"default_branch":"master","last_synced_at":"2025-04-04T02:08:44.396Z","etag":null,"topics":["debugger","debugger-extension","debugging","windbg"],"latest_commit_sha":null,"homepage":null,"language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/microsoft.png","metadata":{"files":{"readme":"ReadMe.md","changelog":"Changelog.md","contributing":"Contributing.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2017-09-26T13:08:45.000Z","updated_at":"2025-03-02T22:50:38.000Z","dependencies_parsed_at":"2024-04-12T10:07:54.216Z","dependency_job_id":null,"html_url":"https://github.com/microsoft/DbgShell","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microsoft%2FDbgShell","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microsoft%2FDbgShell/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microsoft%2FDbgShell/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microsoft%2FDbgShell/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/microsoft","download_url":"https://codeload.github.com/microsoft/DbgShell/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248647249,"owners_count":21139081,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["debugger","debugger-extension","debugging","windbg"],"created_at":"2024-07-30T12:01:39.325Z","updated_at":"2025-04-12T23:30:36.282Z","avatar_url":"https://github.com/microsoft.png","language":"C#","funding_links":[],"categories":["\u003ca id=\"b478e9a9a324c963da11437d18f04998\"\u003e\u003c/a\u003e工具"],"sub_categories":["\u003ca id=\"1afda3039b4ab9a3a1f60b179ccb3e76\"\u003e\u003c/a\u003e其他"],"readme":"# DbgShell\nA PowerShell front-end for the Windows debugger engine.\n\nReady to tab your way to glory? For a quicker intro, take a look at [Getting\nStarted](doc/GettingStarted.md).\n\n[![Build status](https://ci.appveyor.com/api/projects/status/h5ejj6kpyn2tjdat/branch/master?svg=true)](https://ci.appveyor.com/project/jazzdelightsme/dbgshell/branch/master)\n\n## Disclaimers\n\n1. This project is not produced, endorsed, or monitored by the Windows debugger team.\n   While the debugger team welcomes feedback about their API and front ends (windbg, kd,\n   et al), they have no connection with this project. Do not file bugs or feedback to the\n   debugger team concerning this project.\n\n2. This is not a funded project: it has no official resources allocated to it, and is only\n   worked on by volunteers. Do not take any production dependency on this project unless\n   you are willing to support it completely yourself. Feel free to file Issues and submit\n   Pull Requests, but understand that with the limited volunteer resources, it may be a\n   while before your submissions are handled.\n\n3. This is an experimental project: it is not fully baked, and you should expect breaking\n   changes to be made *often*.\n\nCorollary of above disclaimers: I would avoid attaching DbgShell to live targets of high value.\n\n\n## Binaries\n\n[https://aka.ms/dbgshell-latest](https://aka.ms/dbgshell-latest)\n\n\n## Motivation\n\nHave you ever tried automating anything in the debugger? (cdb/ntsd/kd/windbg) How did that\ngo for you?\n\nThe main impetus for DbgShell is that it's just waaaay too hard to automate anything in\nthe debugger. There *are* facilities today to assist in automating the debugger, of\ncourse. But in my opinion they are not meeting people's needs.\n* Using the built-in scripting language is arcane, limited, difficult to get right, and\n  difficult to get help with.\n* Writing a full-blown debugger extension DLL is very powerful, but it's a significant\n  investment—way too expensive for solving quick, \"one-off\" problems as you debug random,\n  real-world problems. Despite the cost, there are a large number of debugger extensions\n  in existence. I think there should not be nearly so many; I think the only reason there\n  are so many is because there aren't viable alternatives.\n* Existing attempts at providing a better interface (such as\n  [PowerDbg](http://powerdbg.codeplex.com/)) are based on \"scraping\" and text parsing,\n  which is hugely limiting (not to mention ideologically annoying) and thus are not able\n  to fulfill the promise of a truly better interface (they are only marginally better, at\n  best).\n* Existing attempts to provide an easier way to write a debugger extension are merely a\n  stop-gap addressing the pain of developing a debugger extension; they don't really solve\n  the larger problem. (for instance, two major shortcomings are: they are still too\n  low-level (you have to deal with the dbgeng COM API), and there's no REPL)\n* The debugger team has recently introduce [Javascript\n  scripting](https://docs.microsoft.com/en-us/windows-hardware/drivers/debugger/javascript-debugger-scripting).\n  Javascript is a much better (and more well-defined) language than the old windbg\n  scripting language, but I think that PowerShell has some advantages, the largest of\n  which is that nobody really uses a Javascript shell--PowerShell is much better as a\n  combined shell *and* scripting language.\n\n\n**The goal of the DbgShell project is to bring the goodness of the object-based PowerShell\nworld to the debugging world.** When you do 'dt' to dump an 'object', you should get an\n*actual* object. Scripting should be as easy as writing a PowerShell script.\n\nThe DbgShell project provides a PowerShell front-end for dbgeng.dll, including:\n* a managed \"object model\" (usable from C# if you wished), which is higher-level than the\n  dbgeng COM API,\n* a PowerShell \"navigation provider\", which exposes aspects of a debugging target as a\n  hierarchical namespace (so you can \"cd\" to a particular thread, type \"dir\" to see the\n  stack, \"cd\" into a frame, do another \"dir\" to see locals/registers/etc.),\n* cmdlets for manipulating the target,\n* a custom PowerShell host which allows better control of the debugger CLI experience, as\n  well as providing features not available in the standard powershell.exe host (namely,\n  support for text colorization using ANSI escape codes (a la [ISO/IEC\n  6429](http://en.wikipedia.org/wiki/ISO/IEC_6429)))\n\nThe custom host is still a command-line (conhost.exe-based) program (analogous to\nntsd/cdb/kd), but it can be invoked from windbg (`!DbgShell`).\n\nIn addition to making automation much easier and more powerful, it will address other\nconcerns as well, such as ease of use for people who don't have to use the debuggers so\noften. (one complaint I've heard is that \"when I end up needing to use windbg, I spend all\nmy time in the .CHM\")\n\nFor seasoned windbg users, on the other hand, another goal is to make the transition as\nseamless as possible. So, for instance, the namespace provider is not the only way to\naccess data; you can still use traditional commands like \"`~3 s`\", \"`k`\", etc.\n\n## What do you mean by \"automation\" and \"scripting\"?\nI'm not _only_ talking about the sort of thing where you open up a text editor and write\nsome big script to do something complex—I'm _also_ talking about being able to whip out\nrelatively simple stuff directly on the command line. There are many situations where you\nwould like to be able to use a little bit of logic, but nothing so big or re-usable that\nyou would even want to save it. It should be easy to just whip off \"one-liners\" like\n\"break on CreateFile if the file being opened is on the user's desktop and function Blah\nis on the stack.\"\n\n## Why PowerShell?\n\nLet me be clear: it took me approximately 4 years to \"warm up\" to PowerShell. I feel it\nhas sharp edges, aspects that are just plain difficult, and plenty of bugs, both in design\nand implementation. Sometimes it really irritates me. *However,* the benefits of\nPowerShell are compelling, and have convinced me that it's the best thing to use for this\nproject:\n\n* It is both a scripting environment and a CLI environment. The fact that it has to do\n  both leads to some negative things like a steeper learning curve, but in the end it is\n  extremely handy, because you want to be able to both do stuff quickly in a command-line\n  REPL, as well as write full-featured, robust scripts.\n* It is very discoverable—things like `Get-Command`, tab completion, the ability to expose\n  hierarchical data like a filesystem, the facilities for providing and synthesizing help,\n  are very good.\n* Tab completion. I know I mentioned it in the previous bullet, but it's awesome enough to\n  get its very own bullet.\n* The object pipeline: the object-oriented nature of the PowerShell pipeline is so much\n  more powerful and easy to use than the bad old days of string-parsing-based scripting\n  that it's not even funny. Imagine doing \"`dt`\" to \"dump\" an \"object\", and actually\n  getting an object. DbgShell does that.\n* People know it: I estimate that the number of people who know PowerShell and/or C# is at\n  least a handful of orders of magnitude larger than the people who know windbg scripting\n  techniques. That means more people will be able to easily \"pick up\" a PowerShell-based\n  debugger; and it also means that when people need help, the pool of potential helpers is\n  much larger (for scripting-related issues, anyway).\n* PowerShell is still a general-purpose shell: when using DbgShell, you have access to not\n  just debugger commands, but you can \"`cd`\" over to the filesystem, registry, AD, etc.;\n  you can execute `Send-MailMessage`, `Get-WmiObject`, `Invoke-WebRequest`,\n  `Invoke-RestMethod`, run arbitrary programs, etc.\n\n## Current Status\n\nDbgShell has been in \"prototyping mode\" for a long time. I have spent a lot of time\nfiguring how something could or should be done, but not necessarily \"finishing\"\neverything. There are a huge number of TODOs in the current code. So although it has\nstarted to become actually useful, the project is still pretty green. However, it can\ndefinitely demonstrate enough to give you a good taste of what it should be like.\n\nBelow are some screenshots. It's important to note that nothing you see is dbgeng text\noutput. Although some stuff in the output will look familiar, that is only because I have\nused PowerShell's formatting and output features to customize how certain objects are\ndisplayed—all the output you see actually corresponds to real, full .NET objects. For\ninstance, those ModLoad messages each correspond to a `MS.Dbg.ModuleLoadedEventArgs`\nobject, which has more properties than what get displayed when sent to `Out-Default`.\nThere is no string parsing of anything from dbgeng whatsoever. (Well... almost. I've made\na few compromises where there is no other way to get information. For instance,\ndisassembly stuff, or parsing the symbolic name of an adjustor thunk function to find the\noffset.)\n\nThis is a sort of \"hello world\" scenario: attaching to an instance of cmd.exe. I first use\nthe PowerShell built-in command `Start-Process`, then pipe the output to the DbgShell\ncommand `Connect-Process`, and then poke around the namespace:\n\n![Hello DbgShell](doc/screenshot_01.png)\n\n\nHere I have attached to a test program, and looked at the stack, switched to a particular\nstack frame, dumped locals, inspected the value of a local `std::map`, and inspected some\ntype information for a local enum value. Note the display of the enumeration value: not\nonly does DbgShell handle looking up the symbolic name for single enumerands, but also\nwhen multiple enumerands are OR'ed together. You can't tell this from the screenshot, but\nthere is tab completion for all of this stuff.\n\n![tbd](doc/screenshot_02.png)\n\n## Notable Features\n* [Color](doc/Color.md): support for text colorization using ANSI escape codes (a la\n  [ISO/IEC 6429](http://en.wikipedia.org/wiki/ISO/IEC_6429))\n* [Custom formatting engine](doc/CustomFormattingEngine.md): Don't like .ps1xml stuff? Me\n  neither. In addition to standard table, list, and custom views, you can define\n  \"single-line\" views which are very handy for customizing symbol value displays.\n* [Custom symbol value conversion](doc/SymbolValueConversion.md): For most variables, the\n  default conversion and display are good. But sometimes, you'd like the debugger to do a\n  little more work for you. The symbol value conversion feature allows, for instance, STL\n  collection objects to be transformed into .NET collection objects that are much easier\n  to deal with.\n* [Derived type detection](doc/DerivedTypeDetection.md): For when your variable is an\n  IFoo, but the actual object is a FooImpl.\n* [Rich type information](doc/RichTypeInfo.md): exposed for your programmatic pleasure.\n* **Q:** Does it work in WinDbg? I will only use WinDbg. **A:** Yes--load up the\n  DbgShellExt.dll extension DLL, and then run \"`!dbgshell`\" to pop open a DbgShell\n  console.\n\n## Current Deficiencies\n* The biggest deficiency currently is that it does not support kernel mode well (if you\n  are already in the proper context, you can display values, but you can't change context\n  from within DbgShell, and the namespace is not wired up).\n* Although you can load and execute traditional debugger extensions in the usual way,\n  there are still many windbg commands missing.\n* Remotes are not supported: the dbgeng API supports connecting to a remote debugger.\n  Unfortunately, the symbol and type information exposed by the dbgeng API is critically\n  insufficient for DbgShell's needs, so DbgShell uses the dbghelp API. Unfortunately,\n  there is no such thing as remote dbghelp. We will need to work with the debugger team to\n  solve this problem.\n\n## License\nLicensed under the [MIT](License.txt) License.\n\n## Contributing\n\nThis project welcomes contributions and suggestions. Most contributions require you to\nagree to a Contributor License Agreement (CLA) declaring that you have the right to, and\nactually do, grant us the rights to use your contribution. For details, visit\nhttps://cla.microsoft.com.\n\nWhen you submit a pull request, a CLA-bot will automatically determine whether you need to\nprovide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the\ninstructions provided by the bot. You will only need to do this once across all repos\nusing our CLA.\n\nSee [Contributing](Contributing.md) for more information about contributing to the project.\n\n## Code of Conduct\n\nThis project has adopted the [Microsoft Open Source Code of\nConduct](https://opensource.microsoft.com/codeofconduct/).\n\nFor more information see the [Code of Conduct\nFAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact\n[opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or\ncomments.\n\n## Other topics\n* [Getting Started with DbgShell](doc/GettingStarted.md)\n* [Color](doc/Color.md)\n* [Custom formatting engine](doc/CustomFormattingEngine.md)\n* [Custom symbol value conversion](doc/SymbolValueConversion.md)\n* [Derived type detection](doc/DerivedTypeDetection.md)\n* [Rich type information](doc/RichTypeInfo.md)\n\n* [Hacking on DbgShell](Contributing.md)\n\n* [DbgEngWrapper](doc/DbgEngWrapper.md)\n\n\nYou can find a short (3 minute) video introduction here: https://youtu.be/ynbg2zZ1Igc\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicrosoft%2Fdbgshell","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmicrosoft%2Fdbgshell","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicrosoft%2Fdbgshell/lists"}