How to: Debug an Existing Extension
An extension that has been running correctly could start failing. You should determine what is causing the failure and make the necessary changes to the extension to prevent the failure. This topic shows you how to determine whether the failure is caused by the extension and how to run the extension in the Microsoft Visual Studio 2008 debugger so that you can determine where the failure occurs.
Looking for the Failure
If Forefront Identity Manager Synchronization Service (FIM Synchronization Service) is not running correctly, the first place you should look to find the source of the failure is in the Operations window in the Synchronization Service Manager. This view displays a summary of the management agent run profiles that have been successfully run.
To view the Operations window
- On the Synchronization Service Manager toolbar, click Operations.
In the Operations window, you can see which management agent run profile failed. If the management agent run profile that failed uses an extension, you must debug the extension.
Loading an Existing Extension into the Debugger
You can use the Visual Studio 2008 debugger to step through each line of the source code to see exactly what is happening in the extension. To perform source-level debugging on an extension, install a debug build of the extension assembly and have the proper source code available. If the Visual Studio 2008 project files are available, you can debug the extension as shown in How to: Attach the Visual Studio Debugger to the Process. If the project files are not available, but the source files and a debug build of the extension assembly are available, you can still perform source-level debugging on the extension by following these steps.
To load the extension into the debugger
Open Visual Studio 2008. Ensure that all projects are closed.
Click Tools, and then click Debug Processes.
In the Processes window, set the following options:
Transport: Set to Default.
Name: Set to the FIM Synchronization Service server name.
Show system processes: Clear the check box.
Show processes in all sessions: Select the check box.
In the Available Processes list, click miiserver.exe, and click Attach. The extension must be configured to run in-process. The Attach to Process dialog box appears.
In the Choose the program types that you want to debug list, select the Common Language Runtime check box and clear all other check boxes. This step is important because it affects what happens when the debugger is stopped or detached. If Native is selected, the FIM Synchronization Service server process must be terminated to stop debugging.
In the Attach to Process dialog box, click OK.
In the Processes window, set When debugging is stopped: to Detach from this process.
Click Close in the Processes window. The debugger is now attached to the miiserver.exe process.
Open the extension source files that you want in Visual Studio and add any desired breakpoints. The breakpoints display a question mark (?) character until the extension assembly is actually loaded. For more information about breakpoints, see Setting Breakpoints.
You can now debug the extension normally. For more information about debugging an extension, see the following topics:
Debugging an Unhandled Exception
When a module does not handle an exception, a dialog box prompts you to debug the module that did not handle the exception and displays a list of the installed debuggers to use for debugging. If you choose to debug the module, the module is loaded into the chosen debugger. This is known as just-in-time debugging. You can use this feature to debug an extension that has not handled an exception even though the extension was not running in the debugger at the time of the exception.
You can use just-in-time debugging to obtain run state information at the time that the exception occurred. This helps to troubleshooting the problem. You may be able to determine the exact cause of the exception after the fact, but you can obtain valuable debugging information, such as how to duplicate the exception, from this.
See Also
Concepts
How to: Attach the Visual Studio Debugger to the Process
Testing and Debugging Rules Extensions
Creating Rules Extensions
Rules Extensions Examples