12
12
13
13
namespace Microsoft . PowerShell . EditorServices
14
14
{
15
+ /// <summary>
16
+ /// Provides a high-level service for interacting with the
17
+ /// PowerShell debugger in the context of a PowerShellSession.
18
+ /// </summary>
15
19
public class DebugService
16
20
{
17
21
#region Fields
18
22
19
23
private PowerShellSession powerShellSession ;
20
- private ConsoleServicePSHost consoleServicePSHost ;
21
24
22
25
// TODO: This needs to be managed per nested session
23
26
private Dictionary < string , List < Breakpoint > > breakpointsPerFile =
@@ -31,6 +34,13 @@ public class DebugService
31
34
32
35
#region Constructors
33
36
37
+ /// <summary>
38
+ /// Initializes a new instance of the DebugService class and uses
39
+ /// the given PowerShellSession for all future operations.
40
+ /// </summary>
41
+ /// <param name="powerShellSession">
42
+ /// The PowerShellSession to use for all debugging operations.
43
+ /// </param>
34
44
public DebugService ( PowerShellSession powerShellSession )
35
45
{
36
46
Validate . IsNotNull ( "powerShellSession" , powerShellSession ) ;
@@ -44,6 +54,13 @@ public DebugService(PowerShellSession powerShellSession)
44
54
45
55
#region Public Methods
46
56
57
+ /// <summary>
58
+ /// Sets the list of breakpoints for the current debugging session.
59
+ /// </summary>
60
+ /// <param name="scriptFile">The ScriptFile in which breakpoints will be set.</param>
61
+ /// <param name="lineNumbers">The line numbers at which breakpoints will be set.</param>
62
+ /// <param name="clearExisting">If true, causes all existing breakpoints to be cleared before setting new ones.</param>
63
+ /// <returns>An awaitable Task that will provide details about the breakpoints that were set.</returns>
47
64
public async Task < BreakpointDetails [ ] > SetBreakpoints (
48
65
ScriptFile scriptFile ,
49
66
int [ ] lineNumbers ,
@@ -76,41 +93,68 @@ await this.powerShellSession.ExecuteCommand<Breakpoint>(
76
93
return new BreakpointDetails [ 0 ] ;
77
94
}
78
95
96
+ /// <summary>
97
+ /// Sends a "continue" action to the debugger when stopped.
98
+ /// </summary>
79
99
public void Continue ( )
80
100
{
81
101
this . powerShellSession . ResumeDebugger (
82
102
DebuggerResumeAction . Continue ) ;
83
103
}
84
104
105
+ /// <summary>
106
+ /// Sends a "step over" action to the debugger when stopped.
107
+ /// </summary>
85
108
public void StepOver ( )
86
109
{
87
110
this . powerShellSession . ResumeDebugger (
88
111
DebuggerResumeAction . StepOver ) ;
89
112
}
90
113
114
+ /// <summary>
115
+ /// Sends a "step in" action to the debugger when stopped.
116
+ /// </summary>
91
117
public void StepIn ( )
92
118
{
93
119
this . powerShellSession . ResumeDebugger (
94
120
DebuggerResumeAction . StepInto ) ;
95
121
}
96
122
123
+ /// <summary>
124
+ /// Sends a "step out" action to the debugger when stopped.
125
+ /// </summary>
97
126
public void StepOut ( )
98
127
{
99
128
this . powerShellSession . ResumeDebugger (
100
129
DebuggerResumeAction . StepOut ) ;
101
130
}
102
131
132
+ /// <summary>
133
+ /// Causes the debugger to break execution wherever it currently
134
+ /// is at the time. This is equivalent to clicking "Pause" in a
135
+ /// debugger UI.
136
+ /// </summary>
103
137
public void Break ( )
104
138
{
105
139
// Break execution in the debugger
106
140
this . powerShellSession . BreakExecution ( ) ;
107
141
}
108
142
109
- public void Stop ( )
143
+ /// <summary>
144
+ /// Aborts execution of the debugger while it is running, even while
145
+ /// it is stopped. Equivalent to calling PowerShellSession.AbortExecution.
146
+ /// </summary>
147
+ public void Abort ( )
110
148
{
111
149
this . powerShellSession . AbortExecution ( ) ;
112
150
}
113
151
152
+ /// <summary>
153
+ /// Gets the list of variables that are children of the scope or variable
154
+ /// that is identified by the given referenced ID.
155
+ /// </summary>
156
+ /// <param name="variableReferenceId"></param>
157
+ /// <returns>An array of VariableDetails instances which describe the requested variables.</returns>
114
158
public VariableDetails [ ] GetVariables ( int variableReferenceId )
115
159
{
116
160
VariableDetails [ ] childVariables = null ;
@@ -148,6 +192,15 @@ public VariableDetails[] GetVariables(int variableReferenceId)
148
192
return childVariables ;
149
193
}
150
194
195
+ /// <summary>
196
+ /// Evaluates an expression in the context of the stopped
197
+ /// debugger. For now, this just does simple evaluation of
198
+ /// a variable in the session. In the future it will execute
199
+ /// commands in the PowerShellSession.
200
+ /// </summary>
201
+ /// <param name="expressionString">The expression string to execute.</param>
202
+ /// <param name="stackFrameId">The ID of the stack frame in which the expression should be executed.</param>
203
+ /// <returns>A VariableDetails object containing the result.</returns>
151
204
public VariableDetails EvaluateExpression ( string expressionString , int stackFrameId )
152
205
{
153
206
// Break up the variable path
@@ -183,11 +236,24 @@ public VariableDetails EvaluateExpression(string expressionString, int stackFram
183
236
return resolvedVariable ;
184
237
}
185
238
239
+ /// <summary>
240
+ /// Gets the list of stack frames at the point where the
241
+ /// debugger sf stopped.
242
+ /// </summary>
243
+ /// <returns>
244
+ /// An array of StackFrameDetails instances that contain the stack trace.
245
+ /// </returns>
186
246
public StackFrameDetails [ ] GetStackFrames ( )
187
247
{
188
248
return this . callStackFrames ;
189
249
}
190
250
251
+ /// <summary>
252
+ /// Gets the list of variable scopes for the stack frame that
253
+ /// is identified by the given ID.
254
+ /// </summary>
255
+ /// <param name="stackFrameId">The ID of the stack frame at which variable scopes should be retrieved.</param>
256
+ /// <returns>The list of VariableScope instances which describe the available variable scopes.</returns>
191
257
public VariableScope [ ] GetVariableScopes ( int stackFrameId )
192
258
{
193
259
// TODO: Return different scopes based on PowerShell scoping mechanics
@@ -260,6 +326,9 @@ private async Task FetchStackFrames()
260
326
261
327
#region Events
262
328
329
+ /// <summary>
330
+ /// Raised when the debugger stops execution at a breakpoint or when paused.
331
+ /// </summary>
263
332
public event EventHandler < DebuggerStopEventArgs > DebuggerStopped ;
264
333
265
334
private async void OnDebuggerStop ( object sender , DebuggerStopEventArgs e )
@@ -275,6 +344,9 @@ private async void OnDebuggerStop(object sender, DebuggerStopEventArgs e)
275
344
}
276
345
}
277
346
347
+ /// <summary>
348
+ /// Raised when a breakpoint is added/removed/updated in the debugger.
349
+ /// </summary>
278
350
public event EventHandler < BreakpointUpdatedEventArgs > BreakpointUpdated ;
279
351
280
352
private void OnBreakpointUpdated ( object sender , BreakpointUpdatedEventArgs e )
0 commit comments