requesting metadata on the site is becoming too slow at 2+ seconds
for quick checks in scripts if a certain module was or was not yet added, I want a swift response too.

When runing the application in a DevContainer and sending:

configuration MyDscConfig {sdf}

This happens:

# log
[2021-06-12T19:53:44.338Z] Executing 'SyntaxAnalyzer' (Reason='This function was programmatically called via the host APIs.', Id=f5f0071b-c60e-4893-a083-0f6903777f82)
[2021-06-12T19:53:44.339Z] PowerShell code sent: configuration MyDscConfig {sdf}
Unhandled exception. System.TypeInitializationException: The type initializer for 'System.Management.Automation.Tracing.PSEtwLog' threw an exception.
 ---> System.TypeInitializationException: The type initializer for 'System.Management.Automation.Tracing.PSSysLogProvider' threw an exception.
 ---> System.DllNotFoundException: Unable to load shared library 'libpsl-native' or one of its dependencies. In order to help diagnose loading problems, consider setting the LD_DEBUG environment variable: liblibpsl-native: cannot open shared object file: No such file or directory
   at System.Management.Automation.Tracing.NativeMethods.OpenLog(IntPtr ident, SysLogPriority facility)
   at System.Management.Automation.Tracing.SysLogProvider..ctor(String applicationId, PSLevel level, PSKeyword keywords, PSChannel channels)
   at System.Management.Automation.Tracing.PSSysLogProvider..cctor()
   --- End of inner exception stack trace ---
   at System.Management.Automation.Tracing.PSSysLogProvider..ctor()
   at System.Management.Automation.Tracing.PSEtwLog..cctor()
   --- End of inner exception stack trace ---
   at System.Management.Automation.Tracing.PSEtwLog.LogOperationalInformation(PSEventId id, PSOpcode opcode, PSTask task, PSKeyword keyword, Object[] args)
   at System.Management.Automation.Remoting.RemoteSessionNamedPipeServer.ProcessListeningThread(Object state)
   at System.Threading.ThreadHelper.ThreadStart_Context(Object state)
   at System.Threading.ExecutionContext.RunInternal(ExecutionContext executionContext, ContextCallback callback, Object state)
--- End of stack trace from previous location where exception was thrown ---
   at System.Threading.ThreadHelper.ThreadStart(Object obj)

localhost website hangs:

Works just fine on the live website:

The helpcollector is a bit messy, and the caching mechanism doesn't scale well either. When we want to create a PSGallery module scraper later, we need this part to work on a per module basis.

Microsoft.Graph

Originally posted by @jannickoeben in #43 (comment)

Todo :

• Improve detection of this kind of errors, so that requester at least gets ample feedback about what happened.
• Find root cause and try and fix that too

Just did a quick test with

Get-VM | Get-Stat -Stat 'cpu.usage.average' -Realtime

It looks as if the explanation for the parameters is not expanded,

although it is available in the help.

Originally posted by @lucdekens in #63 (comment)

It would be nice if the RelatedLinks section would list multiple entries as a (bulleted?) list instead of the current flat list.

The High Level Design (HLD) should describe:

microservice / modular approach, split up in roughly these components:

• Command line analyzer (AST, alias resolver) -> azure function?
• PSGallery Module scraper (background job) -> azure function
• Help analyzer/cache builder (background job) -> azure function
• Help-to-token matcher
• Database for help (meta)information
• frontend website

Improve speed of helpwriter in the pipeline by eliminating the need for Azure PowerShell (which takes forever to load / login to from azure/login@v1)

Use Az cli instead in https://github.com/Jawz84/explainpowershell/blob/09f902583fc4df8ec655d006464ce01b6c861fdb/explainpowershell.helpcollector/helpwriter.ps1

Get storage account key
$a = az storage account keys list --resource-group powershellexplainer --account-name explainpowershell | convertfrom-json
$a | where keyname -eq key2 | select -exp value
$key2 = $a | where keyname -eq key2 | select -exp value

how to read an entity:
az storage entity show --account-name explainpowershell --table-name TestHelpData --partition-key CommandHelp --row-key it --account-key $key2

write entity:
see here: https://github.com/Azure/azure-cli-samples/blob/master/storage/tables.md

If one module has a 'get-vm' cmdlet, and another one does as well, the second may overwrite the first in the helpdb.

@marcduiker wrote:

Looks cool! My only suggestion would be to be mindful of accessibility regarding color contrast and font sizes. There are some tools out there to assist: https://www.w3.org/WAI/ER/tools/?q=online-tool

Analyzing Get-aduser -Filter { $_.SamAccountName -like '*demo*' -and $_.PasswordNeverExpires -eq $true } throws an unhandled exception.

I know it is invalid filter syntax for Get-ADUser, it's just a demo. The real one, Get-aduser -Filter { SamAccountName -like '*demo*' -and PasswordNeverExpires -eq $true }, has other problems. Properties inside filter aren't detected, but that's ActiveDirectory-module specific syntax so it's a different issue. 🙂

ParseExceptions should be handled better, user should be notified what went wrong.

current behaviour: http500 without any context
expected behaviour: a message to the user what's wrong with their oneliner

cc @1RedOne thanks!

Command parameters are now largely left dangling. We want to provide some context, but first we need to figure out how to get that information from cmdlet help and store it.
Also cmdlet parameter binding is harder than it looks.

Try

. {dir}
& {dir}

The previous cache is not cleared is this case.

about ~38 / 63 to go.

You can automatically request support for a module via this issue.
Comment with ONLY the name of the module you would like to see added, and this GitHub Action will automatically try to install it from PSGallery and process it.

Note: this GitHub Action is best-effort. Feel free to create a new issue if your module was not added correctly.

Comments starting with '#.' will be ignored by the Action.

Is explainpowershell dot com available, and what does it cost?

#. Sorry @Jawz84 cc @Jawz84, I was not able to process module 'invoke-commandas' on my own.. :-( See details here

Originally posted by @github-actions in #43 (comment)

Throws exception:

class Person {[int]$age ; Person($a) {$this.age = $a}}; class Child : Person {[string]$School   ;   Child([int]$a, [string]$s ) : base($a) {         $this.School = $s     } }

#log:
[2021-06-12T19:46:13.911Z] PowerShell code sent: class Person {[int]$age ; Person($a) {$this.age = $a}}; class Child : Person {[string]$School   ;   Child([int]$a, [string]$s ) : base($a) {         $this.School = $s     } }
[2021-06-12T19:46:13.934Z] error
[2021-06-12T19:46:13.934Z] explainpowershell: Object reference not set to an instance of an object.
[2021-06-12T19:46:13.936Z] Executed 'SyntaxAnalyzer' (Succeeded, Id=81cd567f-89e4-4054-a6c6-4389f5f28c51, Duration=32ms)

Example :

$Enumerable=[System.Data.DataTableExtensions]::AsEnumerable($Dt) ; $D=[Datetime]::Now

The first instruction is, in my opinion, correctly explained.

Invoke the static method 'AsEnumerable' on class '[System.Data.DataTableExtensions]', with arguments '$Dt'.

For a static property is not the case :

Access the property 'Now' on object '[Datetime]'

instead of

Access the static property 'Now' on class '[Datetime]'

Throws exception:

class Person {[int]$age ; Person($a) {$this.age = $a}}; class Child : Person {[string]$School   ;   Child([int]$a, [string]$s ) : base($a) {         $this.School = $s     } }

#log:
[2021-06-12T19:46:13.911Z] PowerShell code sent: class Person {[int]$age ; Person($a) {$this.age = $a}}; class Child : Person {[string]$School   ;   Child([int]$a, [string]$s ) : base($a) {         $this.School = $s     } }
[2021-06-12T19:46:13.934Z] error
[2021-06-12T19:46:13.934Z] explainpowershell: Object reference not set to an instance of an object.
[2021-06-12T19:46:13.936Z] Executed 'SyntaxAnalyzer' (Succeeded, Id=81cd567f-89e4-4054-a6c6-4389f5f28c51, Duration=32ms)

Examples :

$names=[System.Collections.Generic.List[String]]::New()
{} -as [System.Action[String,int]] #only the operator is known not the operands
(${function:Print} -as [System.Action[String]])
[System.Action[String]]
{} -as [System.Action[String,int]]

That said, Bravo . Because Powershell code analysis is difficult

What is the most suitable frontend?

what functional needs do I have?

what technical needs do I have?

thanks

Today, there isn't an immediately obvious link from the Repo to the actual site. That would be a low-hanging fruit to add it!

Bonus points if it's linked in the Repo settings so it appears on the sidebar.

Various Mocks will be needed:

• index.html (landing page, with input box)
• explain.html (show results, maybe a few examples)
• ...?

When I navigate to explainpowershell.com, it should also just work.

#. Sorry @lucdekens cc @Jawz84, I was not able to process module 'VMware.PowerCLI' on my own.. :-( See details here

Originally posted by @github-actions[bot] in #43 (comment)

@lucdekens thanks for trying out my stuff. Too bad this one didn't work out of the box. Would you like to help me add this module to the DB?

because there could be modules with clobbering commands. We want to be able to capture both.

What information do we want to display, and what metadata do we need?

The top bar is crowded on mobile. I don't like how 'in your face' the 'buy me a coffee' text is on mobile.

For easier readability, results should be color coded. For example:

Gci| select fullname

🔴Get-ChildItem | 🍏Select-Object fullname

🔴 [Gci help ]
🍏 [ Select help]

The | token does nog get explained. But it would certainly be better if it were. Now, the explanation for
$abc; sls '456' and $abc | sls '456' is the same, where in fact, they are quite different.

PsNetTools

#. Sorry @Jawz84 cc @Jawz84, I was not able to process module 'PSExcel' on my own.. :-( See details here

Originally posted by @github-actions in #43 (comment)

Proof of Concept should be built for the following parts:

• AST code analyzer
• PSgallery scraper (or something with a copy to storage with nuget?)
• Helpfile analyzer / help cache builder
• Database schema (what will I actually be needing?)
• token-to-help matcher
• frontend with fancy graphics (flask?)

Goals:

• gather knowledge
• find bottlenecks early

@nohwnd said:

1. idea with the vscode: you select code and get it explained.
2. idea with the command handler: You would handle command not found (e.g. for Invoke-Pester and throw): "Command not found. Try looking at http://explainpowershell.com/search?q=Invoke-Pester"

@indented-automation wrote subs for a few modules:
https://github.com/indented-automation/Indented.StubCommand/tree/master/examples

It appears statements in general are not supported yet

How does explainshell.com draw the nice lines between parts of the command line and the explanation?

like this:

It seems there there are two problems here: one is that for some cmdlets, the parameter help is so big, it doesn't fit the 64k limit in an Azure Table storage property. This is why Import-Module -name didn't return any help (-allowclobber is not a valid param here). So that part needs some work, because it means some module help imports may have failed because the Parameter property data was too big. It appears I can compress the json before uploading, and that saves quite a bit of space. This is what I did to fix this for Import-Module. But now I have to figure out a way to fix this at scale.

The other problem (where the parameter data does not fit the schema) I have not even touched yet.

Originally posted by @Jawz84 in #64 (comment)

Especially on mobile, the amount of space taken up by the title and text below that is a bit too much. I want to shrink/hide it when the Explain action is started, so more space becomes available for explanations.