Add support for debug protocol setVariableRequest. (#283)

* Add support for debug protocol setVariableRequest.

* Cleaned up some comments in the SetVariable method and removed some exceptions that we no longer need to catch now that we aren't using System.Convert.ChangeType().

Author: rkeithhill

src/PowerShellEditorServices.Protocol/DebugAdapter/InitializeRequest.cs

@@ -52,5 +52,11 @@ public class InitializeResponseBody
         /// supports a (side effect free) evaluate request for data hovers.
         /// </summary>
         public bool SupportsEvaluateForHovers { get; set; }
+
+        /// <summary>
+        /// Gets or sets a boolean value that determines whether the debug adapter
+        /// supports allowing the user to set a variable from the Variables debug windows.
+        /// </summary>
+        public bool SupportsSetVariable { get; set; }
     }
 }

src/PowerShellEditorServices.Protocol/DebugAdapter/SetVariableRequest.cs

@@ -0,0 +1,36 @@
+//
+// Copyright (c) Microsoft. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+//
+
+using System.Diagnostics;
+using Microsoft.PowerShell.EditorServices.Protocol.MessageProtocol;
+
+namespace Microsoft.PowerShell.EditorServices.Protocol.DebugAdapter
+{
+    /// <summary>
+    /// SetVariable request; value of command field is "setVariable".
+    /// Request is initiated when user uses the debugger Variables UI to change the value of a variable.
+    /// </summary>
+    public class SetVariableRequest
+    {
+        public static readonly
+            RequestType<SetVariableRequestArguments, SetVariableResponseBody> Type =
+            RequestType<SetVariableRequestArguments, SetVariableResponseBody>.Create("setVariable");
+    }
+
+    [DebuggerDisplay("VariablesReference = {VariablesReference}")]
+    public class SetVariableRequestArguments
+    {
+        public int VariablesReference { get; set; }
+
+        public string Name { get; set; }
+
+        public string Value { get; set; }
+    }
+
+    public class SetVariableResponseBody
+    {
+        public string Value { get; set; }
+    }
+}

src/PowerShellEditorServices.Protocol/PowerShellEditorServices.Protocol.csproj

@@ -54,6 +54,7 @@
     <Compile Include="DebugAdapter\ConfigurationDoneRequest.cs" />
     <Compile Include="DebugAdapter\ContinueRequest.cs" />
     <Compile Include="DebugAdapter\SetFunctionBreakpointsRequest.cs" />
+    <Compile Include="DebugAdapter\SetVariableRequest.cs" />
     <Compile Include="LanguageServer\EditorCommands.cs" />
     <Compile Include="LanguageServer\FindModuleRequest.cs" />
     <Compile Include="LanguageServer\InstallModuleRequest.cs" />

src/PowerShellEditorServices.Protocol/Server/DebugAdapter.cs

@@ -3,6 +3,7 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 //
 
+using Microsoft.PowerShell.EditorServices.Debugging;
 using Microsoft.PowerShell.EditorServices.Protocol.DebugAdapter;
 using Microsoft.PowerShell.EditorServices.Protocol.MessageProtocol;
 using Microsoft.PowerShell.EditorServices.Protocol.MessageProtocol.Channel;
@@ -67,6 +68,7 @@ protected override void Initialize()
             this.SetRequestHandler(StackTraceRequest.Type, this.HandleStackTraceRequest);
             this.SetRequestHandler(ScopesRequest.Type, this.HandleScopesRequest);
             this.SetRequestHandler(VariablesRequest.Type, this.HandleVariablesRequest);
+            this.SetRequestHandler(SetVariableRequest.Type, this.HandleSetVariablesRequest);
             this.SetRequestHandler(SourceRequest.Type, this.HandleSourceRequest);
             this.SetRequestHandler(EvaluateRequest.Type, this.HandleEvaluateRequest);
         }
@@ -461,6 +463,42 @@ protected async Task HandleVariablesRequest(
             await requestContext.SendResult(variablesResponse);
         }
 
+        protected async Task HandleSetVariablesRequest(
+            SetVariableRequestArguments setVariableParams,
+            RequestContext<SetVariableResponseBody> requestContext)
+        {
+            try
+            {
+                string updatedValue =
+                    await editorSession.DebugService.SetVariable(
+                        setVariableParams.VariablesReference,
+                        setVariableParams.Name,
+                        setVariableParams.Value);
+
+                var setVariableResponse = new SetVariableResponseBody
+                {
+                    Value = updatedValue
+                };
+
+                await requestContext.SendResult(setVariableResponse);
+            }
+            catch (Exception ex) when (ex is ArgumentTransformationMetadataException ||
+                                       ex is InvalidPowerShellExpressionException ||
+                                       ex is SessionStateUnauthorizedAccessException)
+            {
+                // Catch common, innocuous errors caused by the user supplying a value that can't be converted or the variable is not settable.
+                Logger.Write(LogLevel.Verbose, $"Failed to set variable: {ex.Message}");
+                await requestContext.SendError(ex.Message);
+            }
+            catch (Exception ex)
+            {
+                Logger.Write(LogLevel.Error, $"Unexpected error setting variable: {ex.Message}");
+                string msg =
+                    $"Unexpected error: {ex.GetType().Name} - {ex.Message}  Please report this error to the PowerShellEditorServices project on GitHub.";
+                await requestContext.SendError(msg);
+            }
+        }
+
         protected Task HandleSourceRequest(
             SourceRequestArguments sourceParams,
             RequestContext<SourceResponseBody> requestContext)

src/PowerShellEditorServices.Protocol/Server/DebugAdapterBase.cs

@@ -59,7 +59,8 @@ await requestContext.SendResult(
                 new InitializeResponseBody {
                     SupportsConfigurationDoneRequest = true,
                     SupportsConditionalBreakpoints = true,
-                    SupportsFunctionBreakpoints = true
+                    SupportsFunctionBreakpoints = true,
+                    SupportsSetVariable = true
                 });
 
             // Send the Initialized event so that we get breakpoints

src/PowerShellEditorServices/Debugging/DebugService.cs

@@ -8,7 +8,9 @@
 using System.Linq;
 using System.Management.Automation;
 using System.Management.Automation.Language;
+using System.Text;
 using System.Threading.Tasks;
+using Microsoft.PowerShell.EditorServices.Debugging;
 using Microsoft.PowerShell.EditorServices.Utility;
 
 namespace Microsoft.PowerShell.EditorServices
@@ -278,7 +280,7 @@ public VariableDetailsBase[] GetVariables(int variableReferenceId)
         /// </summary>
         /// <param name="variableExpression">The variable expression string to evaluate.</param>
         /// <param name="stackFrameId">The ID of the stack frame in which the expression should be evaluated.</param>
-        /// <returns>A VariableDetails object containing the result.</returns>
+        /// <returns>A VariableDetailsBase object containing the result.</returns>
         public VariableDetailsBase GetVariableFromExpression(string variableExpression, int stackFrameId)
         {
             // Break up the variable path
@@ -314,6 +316,154 @@ public VariableDetailsBase GetVariableFromExpression(string variableExpression,
             return resolvedVariable;
         }
 
+        /// <summary>
+        /// Sets the specified variable by container variableReferenceId and variable name to the
+        /// specified new value.  If the variable cannot be set or converted to that value this
+        /// method will throw InvalidPowerShellExpressionException, ArgumentTransformationMetadataException, or 
+        /// SessionStateUnauthorizedAccessException.
+        /// </summary>
+        /// <param name="variableContainerReferenceId">The container (Autos, Local, Script, Global) that holds the variable.</param>
+        /// <param name="name">The name of the variable prefixed with $.</param>
+        /// <param name="value">The new string value.  This value must not be null.  If you want to set the variable to $null
+        /// pass in the string "$null".</param>
+        /// <returns>The string representation of the value the variable was set to.</returns>
+        public async Task<string> SetVariable(int variableContainerReferenceId, string name, string value)
+        {
+            Validate.IsNotNull(nameof(name), name);
+            Validate.IsNotNull(nameof(value), value);
+
+            Logger.Write(LogLevel.Verbose, $"SetVariableRequest for '{name}' to value string (pre-quote processing): '{value}'");
+
+            // An empty or whitespace only value is not a valid expression for SetVariable.
+            if (value.Trim().Length == 0)
+            {
+                throw new InvalidPowerShellExpressionException("Expected an expression.");
+            }
+
+            // Evaluate the expression to get back a PowerShell object from the expression string.
+            PSCommand psCommand = new PSCommand();
+            psCommand.AddScript(value);
+            var errorMessages = new StringBuilder();
+            var results = 
+                await this.powerShellContext.ExecuteCommand<object>(
+                    psCommand, 
+                    errorMessages, 
+                    false, 
+                    false);
+
+            // Check if PowerShell's evaluation of the expression resulted in an error.
+            object psobject = results.FirstOrDefault();
+            if ((psobject == null) && (errorMessages.Length > 0))
+            {
+                throw new InvalidPowerShellExpressionException(errorMessages.ToString());
+            }
+
+            // If PowerShellContext.ExecuteCommand returns an ErrorRecord as output, the expression failed evaluation.  
+            // Ideally we would have a separate means from communicating error records apart from normal output. 
+            ErrorRecord errorRecord = psobject as ErrorRecord;
+            if (errorRecord != null)
+            {
+                throw new InvalidPowerShellExpressionException(errorRecord.ToString());
+            }
+
+            // OK, now we have a PS object from the supplied value string (expression) to assign to a variable.
+            // Get the variable referenced by variableContainerReferenceId and variable name.
+            VariableContainerDetails variableContainer = (VariableContainerDetails)this.variables[variableContainerReferenceId];
+            VariableDetailsBase variable = variableContainer.Children[name];
+
+            // Determine scope in which the variable lives. This is required later for the call to Get-Variable -Scope.
+            string scope = null;
+            if (variableContainerReferenceId == this.scriptScopeVariables.Id)
+            {
+                scope = "Script";
+            }
+            else if (variableContainerReferenceId == this.globalScopeVariables.Id)
+            {
+                scope = "Global";
+            }
+            else
+            {
+                // Determine which stackframe's local scope the variable is in.
+                for (int i = 0; i < this.stackFrameDetails.Length; i++)
+                {
+                    var stackFrame = this.stackFrameDetails[i];
+                    if (stackFrame.LocalVariables.ContainsVariable(variable.Id))
+                    {
+                        scope = i.ToString();
+                        break;
+                    }
+                }
+            }
+
+            if (scope == null)
+            {
+                // Hmm, this would be unexpected.  No scope means do not pass GO, do not collect $200.
+                throw new Exception("Could not find the scope for this variable.");
+            }
+
+            // Now that we have the scope, get the associated PSVariable object for the variable to be set.
+            psCommand.Commands.Clear();
+            psCommand = new PSCommand();
+            psCommand.AddCommand(@"Microsoft.PowerShell.Utility\Get-Variable");
+            psCommand.AddParameter("Name", name.TrimStart('$'));
+            psCommand.AddParameter("Scope", scope);
+
+            IEnumerable<PSVariable> result = await this.powerShellContext.ExecuteCommand<PSVariable>(psCommand, sendErrorToHost: false);
+            PSVariable psVariable = result.FirstOrDefault();
+            if (psVariable == null)
+            {
+                throw new Exception($"Failed to retrieve PSVariable object for '{name}' from scope '{scope}'.");
+            }
+
+            // We have the PSVariable object for the variable the user wants to set and an object to assign to that variable.
+            // The last step is to determine whether the PSVariable is "strongly typed" which may require a conversion.
+            // If it is not strongly typed, we simply assign the object directly to the PSVariable potentially changing its type.
+            // Turns out ArgumentTypeConverterAttribute is not public. So we call the attribute through it's base class - 
+            // ArgumentTransformationAttribute.
+            var argTypeConverterAttr = 
+                psVariable.Attributes
+                          .OfType<ArgumentTransformationAttribute>()
+                          .FirstOrDefault(a => a.GetType().Name.Equals("ArgumentTypeConverterAttribute"));
+
+            if (argTypeConverterAttr != null)
+            {
+                // PSVariable is strongly typed. Need to apply the conversion/transform to the new value.
+                psCommand.Commands.Clear();
+                psCommand = new PSCommand();
+                psCommand.AddCommand(@"Microsoft.PowerShell.Utility\Get-Variable");
+                psCommand.AddParameter("Name", "ExecutionContext");
+                psCommand.AddParameter("ValueOnly");
+
+                errorMessages.Clear();
+
+                var getExecContextResults = 
+                    await this.powerShellContext.ExecuteCommand<object>(
+                        psCommand, 
+                        errorMessages, 
+                        sendErrorToHost: false);
+
+                EngineIntrinsics executionContext = getExecContextResults.OfType<EngineIntrinsics>().FirstOrDefault();
+
+                var msg = $"Setting variable '{name}' using conversion to value: {psobject ?? "<null>"}";
+                Logger.Write(LogLevel.Verbose, msg);
+
+                psVariable.Value = argTypeConverterAttr.Transform(executionContext, psobject);
+            }
+            else
+            {
+                // PSVariable is *not* strongly typed. In this case, whack the old value with the new value.
+                var msg = $"Setting variable '{name}' directly to value: {psobject ?? "<null>"} - previous type was {psVariable.Value?.GetType().Name ?? "<unknown>"}";
+                Logger.Write(LogLevel.Verbose, msg);
+                psVariable.Value = psobject;
+            }
+
+            // Use the VariableDetails.ValueString functionality to get the string representation for client debugger.
+            // This makes the returned string consistent with the strings normally displayed for variables in the debugger.
+            var tempVariable = new VariableDetails(psVariable);
+            Logger.Write(LogLevel.Verbose, $"Set variable '{name}' to: {tempVariable.ValueString ?? "<null>"}");
+            return tempVariable.ValueString;
+        }
+
         /// <summary>
         /// Evaluates an expression in the context of the stopped
         /// debugger.  This method will execute the specified expression

src/PowerShellEditorServices/Debugging/InvalidPowerShellExpressionException.cs

@@ -0,0 +1,24 @@
+//
+// Copyright (c) Microsoft. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+//
+
+using System;
+
+namespace Microsoft.PowerShell.EditorServices.Debugging
+{
+    /// <summary>
+    /// Represents the exception that is thrown when an invalid expression is provided to the DebugService's SetVariable method.
+    /// </summary>
+    public class InvalidPowerShellExpressionException : Exception
+    {
+        /// <summary>
+        /// Initializes a new instance of the SetVariableExpressionException class.
+        /// </summary>
+        /// <param name="message">Message indicating why the expression is invalid.</param>
+        public InvalidPowerShellExpressionException(string message) 
+            : base(message)
+        {
+        }
+    }
+}

src/PowerShellEditorServices/Debugging/VariableContainerDetails.cs

@@ -77,5 +77,23 @@ public override VariableDetailsBase[] GetChildren()
             this.children.Values.CopyTo(variablesArray, 0);
             return variablesArray;
         }
+
+        /// <summary>
+        /// Determines whether this variable container contains the specified variable by its referenceId.
+        /// </summary>
+        /// <param name="variableReferenceId">The variableReferenceId to search for.</param>
+        /// <returns>Returns true if this variable container directly contains the specified variableReferenceId, false otherwise.</returns>
+        public bool ContainsVariable(int variableReferenceId)
+        {
+            foreach (VariableDetailsBase value in this.children.Values)
+            {
+                if (value.Id == variableReferenceId)
+                {
+                    return true;
+                }
+            }
+
+            return false;
+        }
     }
 }

src/PowerShellEditorServices/Debugging/VariableDetails.cs

@@ -145,7 +145,13 @@ private static string GetValueString(object value, bool isExpandable)
 
             if (value == null)
             {
-                valueString = "null";
+                // Set to identifier recognized by PowerShell to make setVariable from the debug UI more natural.
+                valueString = "$null";
+            }
+            else if (value is bool)
+            {
+                // Set to identifier recognized by PowerShell to make setVariable from the debug UI more natural.
+                valueString = (bool) value ? "$true" : "$false";
             }
             else if (isExpandable)
             {

src/PowerShellEditorServices/PowerShellEditorServices.csproj

@@ -71,6 +71,7 @@
     <Compile Include="Debugging\BreakpointDetailsBase.cs" />
     <Compile Include="Debugging\DebugService.cs" />
     <Compile Include="Debugging\CommandBreakpointDetails.cs" />
+    <Compile Include="Debugging\InvalidPowerShellExpressionException.cs" />
     <Compile Include="Debugging\StackFrameDetails.cs" />
     <Compile Include="Debugging\VariableDetails.cs" />
     <Compile Include="Debugging\VariableDetailsBase.cs" />