Skip to content

Commit ff48fd5

Browse files
committed
Split classes into their own files; add API docs
This change splits some small classes out into their own files for easier location. It also adds missing documentation for many new classes that were added when debugging support was introduced.
1 parent 0ea0535 commit ff48fd5

21 files changed

+595
-260
lines changed

src/PowerShellEditorServices.Host/MessageLoop.cs

Lines changed: 0 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -104,7 +104,6 @@ async Task ListenForMessages()
104104

105105
// Attach to events from the PowerShell session
106106
this.editorSession.PowerShellSession.OutputWritten += PowerShellSession_OutputWritten;
107-
this.editorSession.PowerShellSession.BreakpointUpdated += PowerShellSession_BreakpointUpdated;
108107
this.editorSession.DebugService.DebuggerStopped += DebugService_DebuggerStopped;
109108

110109
// Send a "started" event
@@ -184,10 +183,6 @@ await this.messageWriter.WriteMessage(
184183
}, null);
185184
}
186185

187-
void PowerShellSession_BreakpointUpdated(object sender, BreakpointUpdatedEventArgs e)
188-
{
189-
}
190-
191186
void PowerShellSession_OutputWritten(object sender, OutputWrittenEventArgs e)
192187
{
193188
// TODO: change this to use the OutputEvent!

src/PowerShellEditorServices.Transport.Stdio/Request/ReplExecuteRequest.cs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ public override Task ProcessMessage(
1616
EditorSession editorSession,
1717
MessageWriter messageWriter)
1818
{
19-
editorSession.PowerShellSession.ExecuteScript(
19+
editorSession.PowerShellSession.ExecuteScriptString(
2020
this.Arguments.CommandString);
2121

2222
return TaskConstants.Completed;

src/PowerShellEditorServices/Analysis/AnalysisService.cs

Lines changed: 15 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -22,26 +22,26 @@ public class AnalysisService : IDisposable
2222

2323
private Runspace analysisRunspace;
2424
private ScriptAnalyzer scriptAnalyzer;
25-
private PowerShellSession powerShellSession;
2625

2726
#endregion
2827

2928
#region Constructors
3029

3130
/// <summary>
32-
/// Creates an instance of the AnalysisService class with a
33-
/// Runspace to use for analysis operations.
31+
/// Creates an instance of the AnalysisService class.
3432
/// </summary>
35-
/// <param name="analysisRunspace">
36-
/// The Runspace in which analysis operations will be performed.
37-
/// </param>
38-
public AnalysisService(Runspace analysisRunspace)
33+
public AnalysisService()
3934
{
40-
this.analysisRunspace = analysisRunspace;
35+
// TODO: Share runspace with PowerShellSession? Probably should always
36+
// run analysis in a local session.
37+
this.analysisRunspace = RunspaceFactory.CreateRunspace(InitialSessionState.CreateDefault2());
38+
this.analysisRunspace.ApartmentState = ApartmentState.STA;
39+
this.analysisRunspace.ThreadOptions = PSThreadOptions.ReuseThread;
40+
this.analysisRunspace.Open();
4141

4242
this.scriptAnalyzer = new ScriptAnalyzer();
4343
this.scriptAnalyzer.Initialize(
44-
analysisRunspace,
44+
this.analysisRunspace,
4545
new AnalysisOutputWriter(),
4646
null,
4747
null,
@@ -90,15 +90,19 @@ public ScriptFileMarker[] GetSemanticMarkers(ScriptFile file)
9090
}
9191
}
9292

93-
#endregion
94-
93+
/// <summary>
94+
/// Disposes the runspace being used by the analysis service.
95+
/// </summary>
9596
public void Dispose()
9697
{
9798
if (this.analysisRunspace != null)
9899
{
100+
this.analysisRunspace.Close();
99101
this.analysisRunspace.Dispose();
100102
this.analysisRunspace = null;
101103
}
102104
}
105+
106+
#endregion
103107
}
104108
}

src/PowerShellEditorServices/Debugging/BreakpointDetails.cs

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,10 +9,23 @@
99

1010
namespace Microsoft.PowerShell.EditorServices
1111
{
12+
/// <summary>
13+
/// Provides details about a breakpoint that is set in the
14+
/// PowerShell debugger.
15+
/// </summary>
1216
public class BreakpointDetails
1317
{
14-
public int LineNumber { get; set; }
18+
/// <summary>
19+
/// Gets the line number at which the breakpoint is set.
20+
/// </summary>
21+
public int LineNumber { get; private set; }
1522

23+
/// <summary>
24+
/// Creates an instance of the BreakpointDetails class from a
25+
/// PowerShell Breakpoint object.
26+
/// </summary>
27+
/// <param name="breakpoint">The Breakpoint instance from which details will be taken.</param>
28+
/// <returns>A new instance of the BreakpointDetails class.</returns>
1629
public static BreakpointDetails Create(Breakpoint breakpoint)
1730
{
1831
Validate.IsNotNull("breakpoint", breakpoint);

src/PowerShellEditorServices/Debugging/DebugService.cs

Lines changed: 74 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,12 +12,15 @@
1212

1313
namespace Microsoft.PowerShell.EditorServices
1414
{
15+
/// <summary>
16+
/// Provides a high-level service for interacting with the
17+
/// PowerShell debugger in the context of a PowerShellSession.
18+
/// </summary>
1519
public class DebugService
1620
{
1721
#region Fields
1822

1923
private PowerShellSession powerShellSession;
20-
private ConsoleServicePSHost consoleServicePSHost;
2124

2225
// TODO: This needs to be managed per nested session
2326
private Dictionary<string, List<Breakpoint>> breakpointsPerFile =
@@ -31,6 +34,13 @@ public class DebugService
3134

3235
#region Constructors
3336

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>
3444
public DebugService(PowerShellSession powerShellSession)
3545
{
3646
Validate.IsNotNull("powerShellSession", powerShellSession);
@@ -44,6 +54,13 @@ public DebugService(PowerShellSession powerShellSession)
4454

4555
#region Public Methods
4656

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>
4764
public async Task<BreakpointDetails[]> SetBreakpoints(
4865
ScriptFile scriptFile,
4966
int[] lineNumbers,
@@ -76,41 +93,68 @@ await this.powerShellSession.ExecuteCommand<Breakpoint>(
7693
return new BreakpointDetails[0];
7794
}
7895

96+
/// <summary>
97+
/// Sends a "continue" action to the debugger when stopped.
98+
/// </summary>
7999
public void Continue()
80100
{
81101
this.powerShellSession.ResumeDebugger(
82102
DebuggerResumeAction.Continue);
83103
}
84104

105+
/// <summary>
106+
/// Sends a "step over" action to the debugger when stopped.
107+
/// </summary>
85108
public void StepOver()
86109
{
87110
this.powerShellSession.ResumeDebugger(
88111
DebuggerResumeAction.StepOver);
89112
}
90113

114+
/// <summary>
115+
/// Sends a "step in" action to the debugger when stopped.
116+
/// </summary>
91117
public void StepIn()
92118
{
93119
this.powerShellSession.ResumeDebugger(
94120
DebuggerResumeAction.StepInto);
95121
}
96122

123+
/// <summary>
124+
/// Sends a "step out" action to the debugger when stopped.
125+
/// </summary>
97126
public void StepOut()
98127
{
99128
this.powerShellSession.ResumeDebugger(
100129
DebuggerResumeAction.StepOut);
101130
}
102131

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>
103137
public void Break()
104138
{
105139
// Break execution in the debugger
106140
this.powerShellSession.BreakExecution();
107141
}
108142

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()
110148
{
111149
this.powerShellSession.AbortExecution();
112150
}
113151

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>
114158
public VariableDetails[] GetVariables(int variableReferenceId)
115159
{
116160
VariableDetails[] childVariables = null;
@@ -148,6 +192,15 @@ public VariableDetails[] GetVariables(int variableReferenceId)
148192
return childVariables;
149193
}
150194

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>
151204
public VariableDetails EvaluateExpression(string expressionString, int stackFrameId)
152205
{
153206
// Break up the variable path
@@ -183,11 +236,24 @@ public VariableDetails EvaluateExpression(string expressionString, int stackFram
183236
return resolvedVariable;
184237
}
185238

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>
186246
public StackFrameDetails[] GetStackFrames()
187247
{
188248
return this.callStackFrames;
189249
}
190250

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>
191257
public VariableScope[] GetVariableScopes(int stackFrameId)
192258
{
193259
// TODO: Return different scopes based on PowerShell scoping mechanics
@@ -260,6 +326,9 @@ private async Task FetchStackFrames()
260326

261327
#region Events
262328

329+
/// <summary>
330+
/// Raised when the debugger stops execution at a breakpoint or when paused.
331+
/// </summary>
263332
public event EventHandler<DebuggerStopEventArgs> DebuggerStopped;
264333

265334
private async void OnDebuggerStop(object sender, DebuggerStopEventArgs e)
@@ -275,6 +344,9 @@ private async void OnDebuggerStop(object sender, DebuggerStopEventArgs e)
275344
}
276345
}
277346

347+
/// <summary>
348+
/// Raised when a breakpoint is added/removed/updated in the debugger.
349+
/// </summary>
278350
public event EventHandler<BreakpointUpdatedEventArgs> BreakpointUpdated;
279351

280352
private void OnBreakpointUpdated(object sender, BreakpointUpdatedEventArgs e)

src/PowerShellEditorServices/Debugging/StackFrameDetails.cs

Lines changed: 25 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -8,18 +8,40 @@
88

99
namespace Microsoft.PowerShell.EditorServices
1010
{
11+
/// <summary>
12+
/// Contains details pertaining to a single stack frame in
13+
/// the current debugging session.
14+
/// </summary>
1115
public class StackFrameDetails
1216
{
17+
/// <summary>
18+
/// Gets the path to the script where the stack frame occurred.
19+
/// </summary>
1320
public string ScriptPath { get; private set; }
1421

22+
/// <summary>
23+
/// Gets the name of the function where the stack frame occurred.
24+
/// </summary>
1525
public string FunctionName { get; private set; }
1626

27+
/// <summary>
28+
/// Gets the line number of the script where the stack frame occurred.
29+
/// </summary>
1730
public int LineNumber { get; private set; }
1831

32+
/// <summary>
33+
/// Gets the column number of the line where the stack frame occurred.
34+
/// </summary>
1935
public int ColumnNumber { get; private set; }
2036

21-
public Dictionary<string, PSVariable> LocalVariables { get; private set; }
22-
37+
/// <summary>
38+
/// Creates an instance of the StackFrameDetails class from a
39+
/// CallStackFrame instance provided by the PowerShell engine.
40+
/// </summary>
41+
/// <param name="callStackFrame">
42+
/// The original CallStackFrame instance from which details will be obtained.
43+
/// </param>
44+
/// <returns>A new instance of the StackFrameDetails class.</returns>
2345
static internal StackFrameDetails Create(
2446
CallStackFrame callStackFrame)
2547
{
@@ -31,8 +53,7 @@ static internal StackFrameDetails Create(
3153
ScriptPath = callStackFrame.ScriptName,
3254
FunctionName = callStackFrame.FunctionName,
3355
LineNumber = callStackFrame.Position.StartLineNumber,
34-
ColumnNumber = callStackFrame.Position.StartColumnNumber,
35-
LocalVariables = callStackFrame.GetFrameVariables()
56+
ColumnNumber = callStackFrame.Position.StartColumnNumber
3657
};
3758
}
3859
}

0 commit comments

Comments
 (0)