VSCode Debug Does Not Display Module Code

[ghost]

Verified issue does not already exist?

I have searched and found no existing issue

What error did you receive?

There is no error and I can step through the code. The variables/watch and call stack update with each execution step. However, the tab that opens in VSCode to display the module code as we step through it remains empty.

I have another bug to report. Not being able to see the code as I step through it makes it harder for me to help identify the source of the issue in the module.

Steps to Reproduce

# Set a breakpoint on this command and F5.  Then step into the function.  
# A tab will open in VSCode for the script that's empty.  
# The file path for this file is C:\Users\xxx\AppData\Local\Temp\PSES-12868\[xxx] Script Listing.ps1
# The file will exist, but is empty.
# Continue using step into (F11) to see that the variable values and stack info updates with each step.   
Find-DbaInstance -ComputerName 'xxxxxxxx' -ScanType Browser, SqlService, SPN

Please confirm that you are running the most recent version of dbatools

Get-Module dbatools | Select-Object ModuleType, Version, Name

ModuleType Version   Name
---------- -------   ----
    Binary 0.10.0.75 dbatools
    Script 2.0.3     DbaTools

Other details or mentions

I notice a binary module. Is there a way to update the module to allow VSCode to display the code?

What PowerShell host was used when producing this error

VS Code (integrated terminal)

PowerShell Host Version

Name                           Value
----                           -----
PSVersion                      7.3.4
PSEdition                      Core
GitCommitId                    7.3.4
OS                             Microsoft Windows 10.0.19045
Platform                       Win32NT
PSCompatibleVersions           {1.0, 2.0, 3.0, 4.0…}
PSRemotingProtocolVersion      2.3
SerializationVersion           1.1.0.1
WSManStackVersion              3.0

SQL Server Edition and Build number

NA

.NET Framework Version

.NET 7.0.5

PSChildName                      Version
-----------                      -------
v2.0.50727                       2.0.50727.4927
v3.0                             3.0.30729.4926
Windows Communication Foundation 3.0.4506.4926
Windows Presentation Foundation  3.0.6920.4902
v3.5                             3.5.30729.4926
Client                           4.8.04084
Full                             4.8.04084
Client                           4.0.0.0

[wsmelton]

Short answer is no because the PowerShell debugger cannot "jump" into a compiled DLL library.

[wsmelton]

Longer answer. You are talking about debugging two separate languages. Our module uses:

• PowerShell (dbatools.psd1 --> follow paths)
• C# (dbatools.library module --> C# debugger required)

PowerShell won't "jump" into the cs files even if you had cloned the library locally. The other restriction though is there is no code in our library module repository for any user to build the library on their own. Chrissy has that setup right now where it only works "on her machine". That is preferred as she is the only one that will control that repository and make updates to it at this time.

Commands that mix class and Cmdlet usage that is within our library (dbatools.dll) you can debug with PowerShell debugger up to the point it hits something that is in the library. You will always need to step over those and debugger interface in VS Code may tell you as much (never tried).

If you want to debug the dbatools module (core code) you can clone the repository to your local device and then add breakpoints where you need. This will allow you to step through it all you want.

You cannot debug our module as-is when it is installed from the PS Gallery, only from GitHub version.

[ghost]

@wsmelton Darn. Is there a work around? A "debug" module that comes from the same code used for the binary module?

Is there any concept of adding debug definitions to a module?

[ghost]

Not sure if this applies, but it looks relevant.

MicrosoftDocs/PowerShell-Docs#5330

[ghost]

Okay, so a clone is the way to go. One step closer to getting entangled in dbatools for fun, not just work. I'm a DBA, will I just be able to clone and run? Do I need to build and deploy the binary module? (It's been about 10 years since I compiled something.)

[wsmelton]

Correct. No compiling or building required for the dbatool repository, just clone and go. The dbatools.library is setup specific to Chrissy's local dev machine/environment. It's not a repository we are accepting contributions to at this time.

[ghost]

I'm not sure I understand. Does this sound correct?

1. The dbatools.library is off limits. I won't see its code.
2. The PSGallery version of dbatools requires the dbatools.library module.
3. The GitHub version of dbatools has everything and does not use dbatools.library
4. There is an extra step to deploy the GitHub version to PSGallery to incorporate the binary module.
5. To validate code is safe, we have to use a clone from GitHub and avoid the binary module.

[wsmelton]

https://github.com/dataplat/dbatools.library

That is where you find the code for the library that dbatools module requires. Requires no matter what source of the dbatools code you are using.

[potatoqualitee]

i probably should make a build.ps1 work but it's SUCH a headache to do because of the way SMO works. if you look in the /build directory in dbatools.library, you can see the pain

1. You can see the code if you clone the repo, that is still open source. It'll even debug
2. All versions of dbatools require dbatools.library -- both the one in the gallery and the one in the repo.
3. The GitHub version of dbatools is debuggable while the Gallery version focuses on speed import which uses compression and disables debugging
4. Yes, many. Very many steps and I haven't automated it and put it on GitHub for others to see but it'll pretty much be build-full.ps1 and build-core.ps1 (or close, i dont have it up)
5. The binary module is digitally signed by me, you can trust it as much as you can trust the rest of dbatools and/or use dnSpy to decompile if you'd like to see the code. we only have 3 or 4 compiled cmdlets. the rest is our library which is like classes and stuff. Fred Weinmann wrote most of it and I now maintain it by the skin of my teeth 😄

[ghost]

Thanks. We had Solarwinds. I think it's only a matter of time before a foreign government sees a DBATools binary or obfuscated dat file as an opportunity. There's no way I can review all the code in the module, but I felt better knowing the code was public. Somebody would notice an issue eventually. I did look through most of the code I used. Can I be sure the binary you signed is the binary you want me to have?

[potatoqualitee]

I literally look at every single commit to our repo, unlike SolarWinds. I also built and manually initiate the build process. If you don't trust our process, which includes code signing, you can build the module from our repo or use Microsoft's module, which is also signed. If you'd like additional info, please visit https://dbatools.io/security

[ghost]

Thanks for the link. I think I've become too paranoid.

[ghost]

FYI The reason I wanted to step through the code is to figure out why I was getting debug messages from DBATools. I finally figured out it was F8. I enable debug for my code and temporarily turn it off when importing or running DBATools stuff. (I like the DBATools debug messages, but debug/verbose on module loads and cmdlet executes using 20 threads....) There are no DBATools debug messages when I use F5. With F8, I get debug messages no matter what preferences I set in my function. This might be a VSCode bug or feature request related to F8.

I found a fascinating article about running code in the context of a module.

https://seeminglyscience.github.io/powershell/2017/09/30/invocation-operators-states-and-scopes

I tried it out to see if I could examine if the module was using unexpected preferences.

$modules = Get-Module -Name DBATools -All -ErrorAction Stop
$modBinary = $modules | Sort-Object Version -Descending | Where-Object { $_.ModuleType -eq 'Binary' } | Select-Object -First 1
$modScript = $modules | Sort-Object Version -Descending | Where-Object { $_.ModuleType -eq 'Script' } | Select-Object -First 1

& { [PSCustomObject]@{ '$DebugPreference' = $DebugPreference; '$script:DebugPreference' = $script:DebugPreference; '$global:DebugPreference' = $global:DebugPreference } } | out-host
& $modBinary { [PSCustomObject]@{ '$DebugPreference' = $DebugPreference; '$script:DebugPreference' = $script:DebugPreference; '$global:DebugPreference' = $global:DebugPreference } } | out-host
& $modScript { [PSCustomObject]@{ '$DebugPreference' = $DebugPreference; '$script:DebugPreference' = $script:DebugPreference; '$global:DebugPreference' = $global:DebugPreference } }  | out-host

The results for the script module are the same with f5 and f8. For the binary module, I see the error because Get-Module did not return the session state for the module. (I think Pester will not work on the binary module.)

$DebugPreference $script:DebugPreference $global:DebugPreference
---------------- ----------------------- -----------------------
SilentlyContinue                                SilentlyContinue

InvalidOperation: Cannot use '&' to invoke in the context of binary module 'dbatools'. Specify a non-binary module after the '&' and try the operation again.

Anyway, that's probably too much information.

[Shashtsoh]

I've been struggling with this as well since the 2.0 update... When debugging the 1.x versions, stepping into one of the functions would jump you to the allcommands.ps1 file; this seems to have been left out of the 2.x releases. For the casual debugger like me isn't familiar enough to the code to dare actually contribute to the project (yet), being able to debug without cloning was super convenient. From what I've seen of the recent changes and after reading this thread, it looks like cloning the repo is the best/only way to debug reliably now. Am I interpreting that correctly?

[wsmelton]

Debugging in the source @Shashtsoh should be fairly straight forward with your scripts. Simply import the module from the GitHub source folder, instead of the "installed" module. The PowerShell debugger should allow you to step into the function when you do that because it has file access to each function (we import the functions via file path when we see it is our source git folder).

1. Clone the project to c:\git\dbatools
2. Open VS Code workspace with your script
3. Import-Module c:\git\dbatools\dbatools.psd1 in the PS extension terminal
4. Add your breakpoint on your script
5. Run the debugger
6. Step into your breakpoint when it gets to a dbatools function call