explainpowershell

KO | EN

gitlite — search

#dotfiles #vim #ruby #java #plugin #mantisbt-plugin #javascript #php #python #vim-configuration #shell #unmaintained

explainpowershell

★ 38 Open GitHub ↗

PowerShell version of explainshell.com

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

[![Deploy app to Azure](https://github.com/Jawz84/explainpowershell/actions/workflows/deploy_app.yml/badge.svg)](https://github.com/Jawz84/explainpowershell/actions/workflows/deploy_app.yml)

# Explain PowerShell

PowerShell version of [explainshell.com](https://explainshell.com)

On ExplainShell.com, you can enter a Linux terminal oneliner, and the site will analyze it, and return snippets from the proper man-pages, in an effort to explain the oneliner. 
I have created a similar thing but for PowerShell here:

https://www.explainpowershell.com

If you'd like a tour of this repo, open the repo in VS Code (from here with the '.' key), and install the [CodeTour](https://marketplace.visualstudio.com/items?itemName=vsls-contrib.codetour) extension. In the Explorer View, you will now see CodeTour all the way at the bottom left. There currently are four code tours available:
- [High level tour of the application](.tours/high-level-tour-of-the-application.tour)
- [Tour of the AI explanation feature](.tours/tour-of-the-ai-explanation-feature.tour)
- [Tour of the Azure bootstrapper](.tours/tour-of-the-azure-bootstrapper.tour)
- [Tour of the help collector](.tours/tour-of-the-help-collector.tour)

## Goal

I wanted to make it easy for anyone to find out what a certain line of PowerShell code does, without having to actually run it. I wanted the codebase to be easy to do development on.

## Azure Resources overview

* C# Azure Function backend API that analyzes PowerShell oneliners.
* Azure Storage that hosts Blazor Wasm pages as a static website.
* Azure Storage Table in which all help metadata is for currently supported modules.

![azure resources](https://raw.githubusercontent.com/Jawz84/explainpowershell/main/img/AzViz.png)

## Development

The repo now runs directly on your host machine; no devcontainers are required. A typical setup looks like this:

1. Install prerequisites: the latest .NET SDK (currently 10.x), Azure Functions Core Tools v4, PowerShell 7.4+, and the VS Code extensions recommended in `.vscode/extensions.json` (notably the Azurite extension `azurite.azurite`).
2. Clone the repository and open it in VS Code. Run `./bootstrap.ps1` from the repo root once to install PowerShell modules, restore dependencies, seed the Azurite table storage, and run the test suite. The Azure Function backend now runs as a .NET 10 isolated worker, so make sure the `FUNCTIONS_WORKER_RUNTIME` remains `dotnet-isolated` in `local.settings.json`.
3. Start the Azurite Table service via the VS Code Azurite extension (`Azurite: Start` from the Command Palette). The tests expect the table endpoint to be available on `http://127.0.0.1:10002`.
4. Use the provided launch configurations to run and debug the solution, or the frontend or backend separately. 
5. Use the `Run test suite` configuration to run all available tests, both dotnet unit tests and Pester integration tests.

### Available custom PowerShell commands

If you load 
```powershell
. .\explainpowershell.analysisservice.tests\Get-HelpDatabaseData.ps1
. .\explainpowershell.analysisservice.tests\Get-MetaData.ps1
. .\explainpowershell.analysisservice.tests\Invoke-SyntaxAnalyzer.ps1
. .\explainpowershell.analysisservice.tests\Invoke-AiExplanation.ps1
```
into your powershell session, you can use these commands to play with the solution. 
If you run into errors, make sure you have Azurite running and the function app backend too. 
You can run `.\bootstrap.ps1 -UpdateProfile` to automatically have these commands added to your powershell profile.

### Access to local emulated db

With the Azurite extension running, the local table endpoint is still `http://localhost:10002/devstoreaccount1/HelpData`. Connect with [Azure Storage Explorer](https://azure.microsoft.com/en-us/features/storage-explorer/) using the default development keys if you want to inspect the generated metadata. Or use the PowerShell command `Get-HelpDatabaseData` as explained above.

### AI generated explanations

The `/SyntaxAnalyzer` Function can optionally call Azure OpenAI (or any compatible endpoint) to produce a concise AI-written explanation alongside the legacy explanation tree. Configure the new `AiExplanation` section in `explainpowershell.analysisservice/local.settings.json` (and your production configuration source) with:

- `Enabled`: set to `true` to turn the feature on.
- `Endpoint`: the base endpoint for your Azure OpenAI resource, e.g. `https://contoso-resource.openai.azure.com/`.
- `DeploymentName`: the name of the chat completion deployment to use.
- `ApiKey`: store this in Key Vault or configuration, never in source control.
- `SystemPrompt` (optional): override the default “explain PowerShell oneliners” instruction.

If the service is disabled or the call fails, ExplainPowerShell silently falls back to the legacy explanation only.

## Deploying to Azure

Deploying to Azure is done using GitHub Actions. To set everything up, you will need to create an Azure resource group, an service principal for that group. Also you will need to save the secret for that service principal in GitHub as a secret. Lastly you need to give your resources a name. 
I wrote a script so you can sit back and relax while all that is being done for you. Just make sure you log on to GitHub an Azure when prompted.

```powershell
./azuredeploymentbootstrapper.ps1 -SubscriptionId 12345678-91e7-42d9-bb2d-09876543321 -ResourceGroupName MyExplainPowerShell -AzureLocation westeurope
```

Want to spin up a disposable test infra without touching the production secrets? Add `-TestEnv` (optionally `-TestEnvName smoke`) and the script will provision a suffixed resource group plus Function App/Storage using the local Bicep template. The metadata is stored in `explainpowershell.azureinfra/test-environments.json` so you can tear it down later with `-RemoveTestEnv -TestEnvName smoke`.

```powershell
# create a throw-away environment
./azuredeploymentbootstrapper.ps1 -SubscriptionId ... -ResourceGroupName MyExplainPowerShell -AzureLocation westeurope -TestEnv -TestEnvName smoke

# remove it again
./azuredeploymentbootstrapper.ps1 -SubscriptionId ... -ResourceGroupName MyExplainPowerShell -AzureLocation westeurope -RemoveTestEnv -TestEnvName smoke
```

After this, go to your explainpowershell fork on GitHub. Under Actions, run the `Deploy Azure Infra` workflow, then the `Deploy app to Azure` workflow and run `./explainpowershell.helpwriter.ps1 -Force -IsProduction -ResourceGroupName $ResourceGroupName -StorageAccountName $StorageAccountName`.
The Url where you can reach your version of the project can be found in the Azure Portal. Under the storage account resource that was deployed, find the `Static Website` entry in the menu. It is the Url for `Primary Endpoint`. 
Alternatively, you can retrieve it with `az`:

```powershell
$myStorageAccountName = ".."
(az storage account show --name $myStorageAccountName | convertfrom-json).primaryEndpoints.web
```

explainpowershell

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README