C# Class PowerStudio.DebugEngine.DebugEngineBase

Inheritance: IDebugEngine2, IDebugEngineLaunch2

Mostrar archivo Open project: IntelliTect/PowerStudio Class Usage Examples

Public Methods

Method	Description
Attach ( IDebugProgram2 rgpPrograms, IDebugProgramNode2 rgpProgramNodes, uint celtPrograms, IDebugEventCallback2 pCallback, enum_ATTACH_REASON dwReason ) : int	Attaches a debug DebugEngine (DE) to a program or programs. Called by the session debug manager (SDM) when the DE is running in-process to the SDM. There are three reasons for attaching to a program, as follows: ATTACH_REASON_LAUNCH indicates that the DE is attaching to the program because the user launched the process that contains it. ATTACH_REASON_USER indicates that the user has explicitly requested the DE to attach to a program (or the process that contains a program). ATTACH_REASON_AUTO indicates the DE is attaching to a particular program because it is already debugging other programs in a particular process. This is also called auto-attach When this method is called, the DE needs to send these events in sequence: IDebugEngineCreateEvent2 (if it has not already been sent for a particular instance of the debug DebugEngine) IDebugProgramCreateEvent2 IDebugLoadCompleteEvent2 In addition, if the reason for attaching is ATTACH_REASON_LAUNCH, the DE needs to send the IDebugEntryPointEvent2 event. Once the DE gets the IDebugProgramNode2 object corresponding to the program being debugged, it can be queried for any private interface. Before calling the methods of a program node in the array given by pProgram or rgpProgramNodes, impersonation, if required, should be enabled on the IDebugProgram2 interface that represents the program node. Normally, however, this step is not necessary. For more information, see Security Issues.
CanTerminateProcess ( IDebugProcess2 pProcess ) : int	Determines if a process can be terminated. If this method returns S_OK, then it the IDebugEngineLaunch2::TerminateProcess method can be called to actually terminate the process.
CauseBreak ( ) : int	Requests that all programs being debugged by this debug DebugEngine (DE) to stop execution the next time one of their threads attempts to run. This method is asynchronous: an IDebugBreakEvent2 event is sent when the program next attempts to execute after this method is called.
ContinueFromSynchronousEvent ( IDebugEvent2 pEvent ) : int	Called by the session debug manager (SDM) to indicate that a synchronous debug event, previously sent by the debug DebugEngine (DE) to the SDM, was received and processed. The DE must verify that it was the source of the event represented by the pEvent parameter.
CreatePendingBreakpoint ( IDebugBreakpointRequest2 pBPRequest, IDebugPendingBreakpoint2 &ppPendingBP ) : int	Creates a pending breakpoint in the debug DebugEngine (DE). A pending breakpoint is essentially a collection of all the information needed to bind a breakpoint to code. The pending breakpoint returned from this method is not bound to code until the IDebugPendingBreakpoint2::Bind method is called. For each pending breakpoint the user sets, the session debug manager (SDM) calls this method in each attached DE. It is up to the DE to verify that the breakpoint is valid for programs running in that DE. When the user sets a breakpoint on a line of code, the DE is free to bind the breakpoint to the closest line in the document that corresponds to this code. This makes it possible for the user to set a breakpoint on the first line of a multi-line statement, but bind it on the last line (where all the code is attributed in the debug information).
DestroyProgram ( IDebugProgram2 pProgram ) : int	Informs a debug DebugEngine (DE) that the program specified has been atypically terminated and that the DE should clean up all references to the program and send a program destroy event. After this method is called, the DE subsequently sends an IDebugProgramDestroyEvent2 event back to the session debug manager (SDM). This method is not implemented (returns E_NOTIMPL) if the DE runs in the same process as the program being debugged. This method is implemented only if the DE runs in the same process as the SDM.
EnumPrograms ( IEnumDebugPrograms2 &ppEnum ) : int	Retrieves a list of all programs being debugged by a debug DebugEngine (DE).
GetEngineId ( System.Guid &pguidEngine ) : int	Gets the GUID of the debug DebugEngine (DE). Some examples of typical GUIDs are guidScriptEng, guidNativeEng, or guidSQLEng. New debug engines will create their own GUID for identification.
LaunchSuspended ( string pszServer, IDebugPort2 pPort, string pszExe, string pszArgs, string pszDir, string bstrEnv, string pszOptions, enum_LAUNCH_FLAGS dwLaunchFlags, uint hStdInput, uint hStdOutput, uint hStdError, IDebugEventCallback2 pCallback, IDebugProcess2 &ppProcess ) : int	This method launches a process by means of the debug DebugEngine (DE). Normally, Visual Studio launches a program using the IDebugPortEx2::LaunchSuspended method and then attaches the debugger to the suspended program. However, there are circumstances in which the debug DebugEngine may need to launch a program (for example, if the debug DebugEngine is part of an interpreter and the program being debugged is an interpreted language), in which case Visual Studio uses the IDebugEngineLaunch2::LaunchSuspended method. The IDebugEngineLaunch2::ResumeProcess method is called to start the process after the process has been successfully launched in a suspended state.
RemoveAllSetExceptions ( System.Guid &guidType ) : int	Removes the list of exceptions the IDE has set for a particular run-time architecture or language. The exceptions removed by this method were set by earlier calls to the IDebugEngine2::SetException method. To remove a specific exception, call the IDebugEngine2::RemoveSetException method.
RemoveSetException ( EXCEPTION_INFO pException ) : int	Removes the specified exception so it is no longer handled by the debug DebugEngine. The exception being removed must have been previously set by an earlier call to the IDebugEngine2::SetException method. To remove all set exceptions at once, call the IDebugEngine2::RemoveAllSetExceptions method.
ResumeProcess ( IDebugProcess2 pProcess ) : int	Resumes process execution. This method is called after a process has been launched with a call to the IDebugEngineLaunch2::LaunchSuspended method.
SetException ( EXCEPTION_INFO pException ) : int	Specifies how the debug DebugEngine (DE) should handle a given exception. A DE could be instructed to stop the program generating an exception at first chance, second chance, or not at all.
SetLocale ( ushort wLangID ) : int	Sets the locale of the debug DebugEngine (DE). This method is called by the session debug manager (SDM) to propagate the locale settings of the IDE so that strings returned by the DE are properly localized.
SetMetric ( string pszMetric, object varValue ) : int	This method sets a registry value known as a metric. A metric is a registry value used to change a debug DebugEngine's behavior or to advertise supported functionality. This method can forward the call to the appropriate form of the SDK Helpers for Debugging function, SetMetric.
SetRegistryRoot ( string pszRegistryRoot ) : int	Sets the registry root for the debug DebugEngine (DE). This method allows Visual Studio to specify an alternate registry root that the DE should use to obtain registry settings; for example, "HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\8.0Exp".
TerminateProcess ( IDebugProcess2 pProcess ) : int	Terminates a process. Call the IDebugEngineLaunch2::CanTerminateProcess method before calling this method.

Method Details

Attach() public method

Attaches a debug DebugEngine (DE) to a program or programs. Called by the session debug manager (SDM) when the DE is running in-process to the SDM.

There are three reasons for attaching to a program, as follows: ATTACH_REASON_LAUNCH indicates that the DE is attaching to the program because the user launched the process that contains it. ATTACH_REASON_USER indicates that the user has explicitly requested the DE to attach to a program (or the process that contains a program). ATTACH_REASON_AUTO indicates the DE is attaching to a particular program because it is already debugging other programs in a particular process. This is also called auto-attach When this method is called, the DE needs to send these events in sequence: IDebugEngineCreateEvent2 (if it has not already been sent for a particular instance of the debug DebugEngine) IDebugProgramCreateEvent2 IDebugLoadCompleteEvent2 In addition, if the reason for attaching is ATTACH_REASON_LAUNCH, the DE needs to send the IDebugEntryPointEvent2 event. Once the DE gets the IDebugProgramNode2 object corresponding to the program being debugged, it can be queried for any private interface. Before calling the methods of a program node in the array given by pProgram or rgpProgramNodes, impersonation, if required, should be enabled on the IDebugProgram2 interface that represents the program node. Normally, however, this step is not necessary. For more information, see Security Issues.

public Attach ( IDebugProgram2 rgpPrograms, IDebugProgramNode2 rgpProgramNodes, uint celtPrograms, IDebugEventCallback2 pCallback, enum_ATTACH_REASON dwReason ) : int
rgpPrograms	IDebugProgram2	An array of IDebugProgram2 objects that represent programs to be attached to. These are port programs.
rgpProgramNodes	IDebugProgramNode2	An array of IDebugProgramNode2 objects that represent program nodes, one for each program. The program nodes in this array represent the same programs as in pProgram. The program nodes are given so that the DE can identify the programs to attach to.
celtPrograms	uint	Number of programs and/or program nodes in the pProgram and rgpProgramNodes arrays.
pCallback	IDebugEventCallback2	The IDebugEventCallback2 object to be used to send debug events to the SDM.
dwReason	enum_ATTACH_REASON	A value from the ATTACH_REASON enumeration that specifies the reason for attaching these programs. For more information, see the Remarks section.
return	int

CanTerminateProcess() public method

Determines if a process can be terminated.

If this method returns S_OK, then it the IDebugEngineLaunch2::TerminateProcess method can be called to actually terminate the process.

public CanTerminateProcess ( IDebugProcess2 pProcess ) : int
pProcess	IDebugProcess2	An IDebugProcess2 object that represents the process to be terminated.
return	int

CauseBreak() public method

Requests that all programs being debugged by this debug DebugEngine (DE) to stop execution the next time one of their threads attempts to run.

This method is asynchronous: an IDebugBreakEvent2 event is sent when the program next attempts to execute after this method is called.

public CauseBreak ( ) : int
return	int

ContinueFromSynchronousEvent() public method

Called by the session debug manager (SDM) to indicate that a synchronous debug event, previously sent by the debug DebugEngine (DE) to the SDM, was received and processed.

The DE must verify that it was the source of the event represented by the pEvent parameter.

public ContinueFromSynchronousEvent ( IDebugEvent2 pEvent ) : int
pEvent	IDebugEvent2	An IDebugEvent2 object that represents the previously sent synchronous event from which the debugger should now continue.
return	int

CreatePendingBreakpoint() public method

Creates a pending breakpoint in the debug DebugEngine (DE).

A pending breakpoint is essentially a collection of all the information needed to bind a breakpoint to code. The pending breakpoint returned from this method is not bound to code until the IDebugPendingBreakpoint2::Bind method is called. For each pending breakpoint the user sets, the session debug manager (SDM) calls this method in each attached DE. It is up to the DE to verify that the breakpoint is valid for programs running in that DE. When the user sets a breakpoint on a line of code, the DE is free to bind the breakpoint to the closest line in the document that corresponds to this code. This makes it possible for the user to set a breakpoint on the first line of a multi-line statement, but bind it on the last line (where all the code is attributed in the debug information).

public CreatePendingBreakpoint ( IDebugBreakpointRequest2 pBPRequest, IDebugPendingBreakpoint2 &ppPendingBP ) : int
pBPRequest	IDebugBreakpointRequest2	An IDebugBreakpointRequest2 object that describes the pending breakpoint to create.
ppPendingBP	IDebugPendingBreakpoint2	Returns an IDebugPendingBreakpoint2 object that represents the pending breakpoint.
return	int

DestroyProgram() public method

Informs a debug DebugEngine (DE) that the program specified has been atypically terminated and that the DE should clean up all references to the program and send a program destroy event.

After this method is called, the DE subsequently sends an IDebugProgramDestroyEvent2 event back to the session debug manager (SDM). This method is not implemented (returns E_NOTIMPL) if the DE runs in the same process as the program being debugged. This method is implemented only if the DE runs in the same process as the SDM.

public DestroyProgram ( IDebugProgram2 pProgram ) : int
pProgram	IDebugProgram2	An IDebugProgram2 object that represents the program that has been atypically terminated.
return	int

EnumPrograms() public method

Retrieves a list of all programs being debugged by a debug DebugEngine (DE).

public EnumPrograms ( IEnumDebugPrograms2 &ppEnum ) : int
ppEnum	IEnumDebugPrograms2	Returns an IEnumDebugPrograms2 object that contains a list of all programs being debugged by a DE.
return	int

GetEngineId() public method

Gets the GUID of the debug DebugEngine (DE).

Some examples of typical GUIDs are guidScriptEng, guidNativeEng, or guidSQLEng. New debug engines will create their own GUID for identification.

public GetEngineId ( System.Guid &pguidEngine ) : int
pguidEngine	System.Guid	Returns the GUID of the DE.
return	int

LaunchSuspended() public method

This method launches a process by means of the debug DebugEngine (DE).

Normally, Visual Studio launches a program using the IDebugPortEx2::LaunchSuspended method and then attaches the debugger to the suspended program. However, there are circumstances in which the debug DebugEngine may need to launch a program (for example, if the debug DebugEngine is part of an interpreter and the program being debugged is an interpreted language), in which case Visual Studio uses the IDebugEngineLaunch2::LaunchSuspended method. The IDebugEngineLaunch2::ResumeProcess method is called to start the process after the process has been successfully launched in a suspended state.

public LaunchSuspended ( string pszServer, IDebugPort2 pPort, string pszExe, string pszArgs, string pszDir, string bstrEnv, string pszOptions, enum_LAUNCH_FLAGS dwLaunchFlags, uint hStdInput, uint hStdOutput, uint hStdError, IDebugEventCallback2 pCallback, IDebugProcess2 &ppProcess ) : int
pszServer	string	The name of the machine in which to launch the process. Use a null value to specify the local machine.
pPort	IDebugPort2	The IDebugPort2 interface representing the port that the program will run in.
pszExe	string	The name of the executable to be launched.
pszArgs	string	The arguments to pass to the executable. May be a null value if there are no arguments.
pszDir	string	The name of the working directory used by the executable. May be a null value if no working directory is required.
bstrEnv	string	Environment block of NULL-terminated strings, followed by an additional NULL terminator.
pszOptions	string	The options for the executable.
dwLaunchFlags	enum_LAUNCH_FLAGS	Specifies the LAUNCH_FLAGS for a session.
hStdInput	uint	Handle to an alternate input stream. May be 0 if redirection is not required.
hStdOutput	uint	Handle to an alternate output stream. May be 0 if redirection is not required.
hStdError	uint	Handle to an alternate error output stream. May be 0 if redirection is not required.
pCallback	IDebugEventCallback2	The IDebugEventCallback2 object that receives debugger events.
ppProcess	IDebugProcess2	Returns the resulting IDebugProcess2 object that represents the launched process.
return	int

RemoveAllSetExceptions() public method

Removes the list of exceptions the IDE has set for a particular run-time architecture or language.

The exceptions removed by this method were set by earlier calls to the IDebugEngine2::SetException method. To remove a specific exception, call the IDebugEngine2::RemoveSetException method.

public RemoveAllSetExceptions ( System.Guid &guidType ) : int
guidType	System.Guid	Either the GUID for the language or the GUID for the debug DebugEngine that is specific to a run-time architecture.
return	int

RemoveSetException() public method

Removes the specified exception so it is no longer handled by the debug DebugEngine.

The exception being removed must have been previously set by an earlier call to the IDebugEngine2::SetException method. To remove all set exceptions at once, call the IDebugEngine2::RemoveAllSetExceptions method.

public RemoveSetException ( EXCEPTION_INFO pException ) : int
pException	EXCEPTION_INFO	An EXCEPTION_INFO structure that describes the exception to be removed.
return	int

ResumeProcess() public method

Resumes process execution.

This method is called after a process has been launched with a call to the IDebugEngineLaunch2::LaunchSuspended method.

public ResumeProcess ( IDebugProcess2 pProcess ) : int
pProcess	IDebugProcess2	An IDebugProcess2 object that represents the process to be resumed.
return	int

SetException() public method

Specifies how the debug DebugEngine (DE) should handle a given exception.

A DE could be instructed to stop the program generating an exception at first chance, second chance, or not at all.

public SetException ( EXCEPTION_INFO pException ) : int
pException	EXCEPTION_INFO	An EXCEPTION_INFO structure that describes the exception and how to debug it.
return	int

SetLocale() public method

Sets the locale of the debug DebugEngine (DE).

This method is called by the session debug manager (SDM) to propagate the locale settings of the IDE so that strings returned by the DE are properly localized.

public SetLocale ( ushort wLangID ) : int
wLangID	ushort	Specifies the language locale. For example, 1033 for English.
return	int

SetMetric() public method

This method sets a registry value known as a metric.

A metric is a registry value used to change a debug DebugEngine's behavior or to advertise supported functionality. This method can forward the call to the appropriate form of the SDK Helpers for Debugging function, SetMetric.

public SetMetric ( string pszMetric, object varValue ) : int
pszMetric	string	The metric name.
varValue	object	Specifies the metric value.
return	int

SetRegistryRoot() public method

Sets the registry root for the debug DebugEngine (DE).

This method allows Visual Studio to specify an alternate registry root that the DE should use to obtain registry settings; for example, "HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\8.0Exp".

public SetRegistryRoot ( string pszRegistryRoot ) : int
pszRegistryRoot	string	The registry root to use.
return	int

TerminateProcess() public method

Terminates a process.

Call the IDebugEngineLaunch2::CanTerminateProcess method before calling this method.

public TerminateProcess ( IDebugProcess2 pProcess ) : int
pProcess	IDebugProcess2	An IDebugProcess2 object that represents the process to be terminated.
return	int