Recently I tried to publish a PowerShell module into the gallery from a relatively fresh Windows 10 installation, when the Publish-Module cmdlet failed with an error:

Running Process Monitor, I found the command line it tries to execute looks like this:
"C:\Program Files\dotnet\dotnet.exe" pack "C:\Users\ExampleUser\AppData\Local\Temp\2f2dd498-4ce3-4ca2-a081-c65b0af71090\Temp.csproj" /p:NuspecFile="C:\Users\ExampleUser\AppData\Local\Temp\1691004664\MyModule\MyModule.nuspec" --output "C:\Users\ExampleUser\AppData\Local\Temp\1691004664\MyModule"

My PowerShellGet installation was at the latest stable version, and the NuGet version clearly has nothing to do with it: there were no calls for “nuget.exe” in the Process Monitor log.

So what happens if I run this command manually?

Aha! A descriptive error finally!
Turns out, the pack command is a part of .NET SDK. And of course, since that was a new Windows installation, it did not have that SDK at the moment.

Thankfully, with winget, .NET SDK installation is a breeze: winget install Microsoft.DotNet.SDK.7

Now let’s check what we’ve got:

The error is different now and perfectly logical – I didn’t pass any project file to it.
And it helped – Publish-Module now works! Hooray!

Hi guys! Those of you, who work with Slack, sure know about PSSlack – a module to work with our beloved messaging system via the official API. That API (and the module) has a tiiiiiny downside: it requires you to add a new app to your workspace in order to get an API token.

And sometimes this new app must be approved by your workspace administrators. But what if you cannot get their approval? Well, I have something for you: SlackWeb, a new module to communicate with Slack from PowerShell which does NOT need any new apps added to the workspace.

This module uses the web-API: this API is primarily used by the official web-client and you know what’s neat? You already have a token for it!
Look at requests the web-client sends and you should see that it makes calls to different API endpoints. In those calls you’ll see a token starting with “xoxc-” – that’s your web-token.

But the web-token won’t work if you try to use it with regular API calls – it needs a counterpart: specifically, one of your cookies – a “d-cookie”.
If you switch to the “Headers” tab of an API request and look closely into the “cookie” section on this tab, you should find a cookie called just “d”. It has some super-long value and you need to save this value to use later along with your web-token.

When you load the module, first thing it does is to ask you for the values of the token and the cookie. Feed them to it and that’s pretty much what you need to start using the module – your team ID/URL are detected automatically.

Not so many features are available right now – I just start with this module. Currently, I cared mostly about messages export.
If you find that the module lack a feature you need, please let me know here or in issues on GitHub and I’ll try to integrate it.

Grab the module from the PowerShell Gallery right now! Just be aware, that it uses reverse-engineered API calls and might stop working any moment – please use on your own risk.

Is there even a problem?

When you develop a complex module, a lot of variables come to play. Naturally, at some point, you probably would like to look at their state, to see how they have changed during the execution. One way do to it is to load module into an IDE and use a debugger during a test run. But what if the module requires an environment which is impossible to recreate at your machine? Or what if you want to keep an eye on it while it works in a production environment?
A log of executed commands/scriptblocks would be useful for this. How can we get such log? What does PowerShell have to offer here?
There are two options are available:
First is the Start-Transcript cmdlet,
Second – script tracing and logging.

Start-Transcript writes commands and host output into a plain, loosely structured, text file.
Script tracing and logging writes all commands into a standard Windows Event Log file.

Both methods suffer from the following problems:

1. They do not log the content of variables. If a variable was populated by a call to something external, like Get-ChildItem, for example, you have no idea what does it contain.
2. When you call a function/cmdlet with variables as parameter values, you cannot be sure what has been passed to the parameters, because the variables’ content was not logged anywhere.

Let’s see for ourselves…

…by creating a simple object:

Here’s what you will see in the event log:

Only one of these will contain a useful (for us) information – Event ID 4104:

Creating Scriptblock text (1 of 1):
$a = [pscustomobject]@{
Name = 'Alice'
Role = 'Role 1'
}
ScriptBlock ID: bfc67bba-cff9-444d-a231-80f9f4ee5b55
Path:


At the same time, in the transcript:

PS C:\> $a = [pscustomobject]@{
Name = 'Alice'
Role = 'Role 1'
}


OK, so far, so good – we can clearly see what command was executed in both the event log and the transcript. But we also see the first problem with Start-Transcript – it does not log time.

Now, let’s retrieve the object back:

Here’s what a new 4104 event contains:

Creating Scriptblock text (1 of 1):
$a

ScriptBlock ID: 639f6d2b-a75a-4042-9da4-8692cdffdf9e
Path:


And no, there’s no event which contains an output of that command.
Transcript log in the meantime recorded this:

PS C:\> $a

Name Role
—- —-
Alice Role 1

Just as seen in the console!

So, here we see the first flaw of the Event Log – it does not store output.

Let’s continue with something more complex

First, let’s define a function:

Then, we call this function as following:

Here’s what we got in return:
828
944
976

What does it mean? Did our function work correctly? Were there any other processes with PID less than 1000?
We don’t know. Because we have no idea of what was in the $Processes variable at the time. We do not know what was passed to the -Process parameter, each time the function was called.

So, here are some pros and cons for each logging type which we’ve seen so far:

Script tracing and logging:
❌ Can not show content of variables.
✔ Shows at what time each scriptblock was executed.
❌ Does not show at what time each command was run (yup, scriptblocks only).
❌ Does not show what exactly was passed to a function’s parameters.
❌ Logs only into a file.

Start-Transcript:
✔ Can show content of variables.
❌ Does not show at what time each scriptblock was executed.
❌ Does not show at what time each command was run.
❌ Does not show what exactly was passed to a function’s parameters.
❌ Logs only into a file.

Write-Debug to the rescue!

In the end I stuck with a rather strange and obscure solution: Write-Debug. Why? Because this cmdlet solves all the problems:

1. It send everything into another stream which leaves my pipeline untouched (it’s specifically designed to DEBUG code, duh).
2. It is up to me which information gets sent to the debug output.
3. I am not constrained with an output format chosen for me by the language developers – I can change it with accordance to my needs.
4. It logs into a stream, not into a file: you can send it to a screen or into a file or into another function! (see below)

But of course, Write-Debug has its downsides:

1. It has no built-in knowledge of what line of code it should log – you have to, basically, write your code twice. This could be circumvented by executing everything through a special function which would log the line and then execute it, but it introduces additional requirements for your code to run, not everybody would have that additional module installed, and I want my code to be as much transferable as possible.
2. There’s no built-in way to write the debug stream into a persistent file.

Here’s how that code, which we executed earlier, would look like if I debug-enabled it (see in-line comments for clarification):

Looks a bit ugly, I admit ?

How do I Write-Debug into a file?

Earlier I said that I would like to have my debug log as a file, but Write-Debug cannot write into a file – it sends messages into the debug output. How can we create a log file, containing these debug messages? That’s where SplitOutput (yes, probably, not the best name, but whatever) module comes to play. Its single function (Split-Output) accepts objects, filters them and sends all filtered out objects into a scriptblock, passing all other objects down to the pipeline. You can use this function to filter out debug messages from the pipeline and send them into a function which writes a log file.

Since Split-Output picks up messages from the pipeline, our last challenge is to merge the debug stream into the output stream. Thankfully, PowerShell has a built-in functionality for this – redirection operators. To redirect the debug stream into the output stream, use the following construction: 5>&1.
MyFunction 5>&1 | Split-Output -ScriptBlock {Write-Log -Path C:\Log.txt} -Mode Debug

Here I stand (corrected?)

As you can see, utilizing Write-Debug for hardcore logging is not an easy task – you have to copy/paste your code twice, you have to use external functions to log into a file, but it gives you a lot of flexibility and additional features which the other two existing logging methods cannot provide. So far, I find it the best solutions currently existing, to write a detailed log of how exactly my functions work, while they merrily interact with each other in a production environment.

Certainly, this task would be much easier if we could intercept commands inside PowerShell’s engine, but I am not aware of an interface which allows us to do just that — I tried to look at the source code, but did not understand much. Is there any? Maybe it would be a good idea to file an RFC for such functionality??

Oh, by the way, you can see this debug pattern in a real module here: SCVMReliableMigration