Discussion: Different method of passing $Context to Editor Commands

[gerane]

I wanted to start a discussion on how PSES could improve the way it passes $Context to Editor Commands.

The way $Context is made accessible to an Editor Command currently, is it is passed as a parameter to the Command. This is not immediately evident and I can see this causing confusion.

In a scriptblock, this can be handled by adding a context param.

Register-EditorCommand `
        -Name "Teamviewer.ConnectDevice" `
        -DisplayName "Connect to Teamviewer Device" `
        -SuppressOutput `
        -ScriptBlock {
            param([Microsoft.PowerShell.EditorServices.Extensions.EditorContext]$context)
            Connect-Teamviewer
        }

However, if you were to just specify the function you may get some results you didn't expect.

Register-EditorCommand `
        -Name "Teamviewer.ConnectDevice" `
        -DisplayName "Connect to Teamviewer Device" `
        -SuppressOutput `
        -Function Connect-Teamviewer

In the above example, Connect-Teamviewer will be passed $context as a parameter when executed as an Editor Command.

function Connect-Teamviewer
{
    [Cmdletbinding()]
    param
    (
        [parameter(Mandatory=$true)]        
        [string]$ComputerName
    )

If your function looks something like the above code the command will actually error. $context will be passed to the $CompuerName parameter. Meaning you would need to write your functions with this in mind.

function Connect-Teamviewer
{
    [Cmdletbinding()]
    param
    (
        [parameter(Mandatory=$false)]        
        [[Microsoft.PowerShell.EditorServices.Extensions.EditorContext]]$Context,

        [parameter(Mandatory=$true)]        
        [string]$ComputerName
    )

This is likely not a good solution ether. It is going to be confusing to those writing their first commands, and there could potentially be some unwanted results. I have not tested it, but I wonder of the potential issues of a parameter not checking for a type and being passed context to do something like delete something.

function Delete-Stuff
{
    [Cmdletbinding()]
    param
    (     
        $Stuff
    )

    Process
    {
        foreach ($item in $Stuff) 
        { 
            Delete-AllTheThings $item 
        }
    }
}

One question I wanted to ask, could the information in $Context, be added to $psEditor? Is there a reason it has to be passed to the function @daviwil ?

$psEditor.context.cursorposition

Something along the lines of that. When I was first learning the Editor commands, this is sort of what I thought $psEditor was doing. I didn't realize there was a difference between $Context and $psEditor. @daviwil can you better explain the exact differences between the 2? I'd like to get a better grasp of exactly how each differ.

[daviwil]

$context is a separate variable because it carries information about the current state of the editor. It's intended to be accessed on demand so that the editor doesn't need to keep sending updates to the variable any time the user does something in the editor.

We need to pass the $context variable to registered editor commands because the EditorContext gets transmitted to the editor when the user executes your command. This saves you from having to call $psEditor.GetEditorContext() and making a full round-trip back to the editor again before you can do anything.

$psEditor encapsulates anything that can be done without the editor's context. Its methods can be invoked at any time without knowing what state the editor is in.

[gerane]

I've mainly stuck to wrapper script blocks. I didn't want $context to cause issues when piping.