Debugging Applications for MS .Net and Windows

1. Debugging Applications for MS .Net and Windows Ch.9 Extending the Visual Studio .NET IDE

2. Presentation for chapter 9 of John Robbins' book "Debugging Applications for MS .Net and MS Windows" • Part of the ongoing Testing Seminar meetings • Coordinated by Dr. Fawcett • Date: Friday, February 20, 2004 • Presenter: Kanat Bolazar <kanat2@yahoo.com> • Syracuse University, Syracuse, New York

3. Overview • Visual Studio .NET • A "paragon of extensibility" • Allows anyone to integrate their window/view into the IDE • Macros • Visual Basic only • For nice, small non-UI-related tasks • Source code is visible

4. Overview (Cont.) • Add-Ins • COM components, for: • Tool (your own) windows • Adding property pages to the Options dialog box • Responding to menu commands • Any language that can produce COM may be used • Wizards • Linearized UI interaction • Least used method of extension • Not covered in the book

5. CommenTater Macro • Three useful examples come with the book: • CommenTater macro • SuperSaver add-in • SettingsMaster add-in • CommenTater macro: • Checks for missing and extra C# documentation comments • Adds TODO comments within documentation comments • Task List can be used to automatically gather and view these

6. SuperSaver and SettingsMaster Add-Ins • SuperSaver: • A useful add-in that's not too long (is readable) • Fixes a problem with how Visual Studio saves files • Allows background saving • Lets you add property pages to the Options dialog box • SettingsMaster: • Add-in to set build options • Allows batch-setting and custom-setting • Defaults to Robbins' recommended settings from chapter 2 • Robbins recommends it: • For all sizes of teams • For all manners of projects • To keep the team properly coordinated

7. Start Extending the IDE With Macros • Add-ins and macros use the same extensibility interface • This interface has "lots of quirks" • Macros are quick to write, run, easy to debug • So, they are the best tools in learning to extend Visual Studio

8. .Net Documentation for Macros • .Net Documentation • Visual Studio .NET • Developing with Visual Studio .NET • Manipulating the Development Environment • Automating Repetitive Actions By Using Macros

9. Documentation for "Object Model" • .Net Documentation • Visual Studio .NET • Developing with Visual Studio .NET • Reference • Automation and Extensibility Reference

10. Record a Macro • Records your keystrokes while you are in: • Code editors • Find/replace boxes • Solution explorer • Window activation

11. Microsoft's Sample Macros • Microsoft's sample macros are loaded in the system • Nice sample macro: MakeAddinFromMacroProj • Converts a macro (VB) to an add-in (COM) • Macro explorer • Samples • MakeAddin macro project • MakeAddinFromMacroProj macro

12. Two Ways to execute Macros: • Macro Explorer: • Lists macros that take no parameters • Select & double-click • Command Window: • Start by typing "macro"... • Let IntelliSense do the rest • Can create an alias for a long command

13. Macro Parameters and Backward Compatibility • Visual Studio .Net: • 2002 only allows one optional parameter • 2003 allows multiple optional parameters • Use VB keyword "Optional", give default value: • Sub Xyz(Optional ByVal Param As String = "") • Macro invocation: • Macro name • Space character (the only unquoted space char) • Parameters list (comma-separated, quoted for space)

14. Macro Parameters and Backward Compatibility (Cont.) • Example: • MyMacro nospace,"with space",thirdParamValue • Robbins: There's no way to pass to your macro: • A quote-delimited string with a comma in it • Book's helper function: • Macros directory • Utilities.VB • SplitParams function • splits parameters into a string array

15. Problems with Projects • Object Model: Project object • Has methods for manipulating and saving projects • VSProject: C# and Visual Basic projects • VCProject: C++ projects • Others (including CAB, Setup): Not documented • Using Project object directly • Throws many "Not implemented" exceptions • Even for simple operations such as "Save"

16. Problems with Projects (Cont.) • Solution: Convert to proper type • Check Kind property • Retrieve the GUID • Compare against known GUIDs • Book lists GUID for C#, VB.Net, C++, J# • Instead of Kind, we can use Project.CodeModel.Language • Warning: Documentation is wrong: • Return type is CodeModelLanguageConstants • Not the documented "vsCMLanguage"

17. Code Elements • .Net allows access to code structure • We can add, change remove code elements: • Methods, properties, documentation, etc • No need to parse code ourselves • Book's sample macro that dumps the code elements • Pretty-prints code element structure (full names) • In Macros.VB (uses: Utilities.VB) • Works for any .Net language • Only 53 lines of code (without the comment lines)

18. Code Elements (Cont.) • Traversal: • Accessing the children elements: Not consistent: • CodeElement.Members • CodeClass.Members • C++: CodeClass.Children • CodeFunction.Parameters

19. CommenTater: The Cure For The Common Potato? • C# documentation comments • You should always fill them out: • Enforces universal consistent commenting standards • IDE IntelliSense picks up its summary and param tags • Even for binary-only distibution, automatically, if: • Gathered into an XML file • Put in same directory as the binary • Resultant XML can be converted • To complete product documentation • Using "a good dose of" XSLT • Tools - Build comment Web Pages does this, but ignores exceptions, etc.

20. Creating the Standard XML Documentation for C# • Do the following for all configurations • Project Property Pages Dialog • Configuration Properties • Build • XML Documentation File • (enter file name, as in "ProjectDocs.xml")

21. Converting the XML Documentation to HTML Pages • Book's sample: • Under DocCommentsXSL directory • XSL transformation file • CSS • NDoc: • http://ndoc.sourceforge.net • HTML looks just like MSDN .Net standard docs • Your docs will hyperlink to MSDN documentation • Highly recommended by Robbins: • Add it to your automated post-build processing

22. CommenTater uses "TODO" Comments for Task List • Task List: • Right click, to view all or comments • Displays comments in your code that say "TODO" • CommenTater: • Puts TODO lines in XML documentation comments • For all/any missing XML documentation items • For extra (old params) XML documentation items

23. CommenTater Example: /// <summary> /// TODO - Add pow function summary comment /// </summary> /// <remarks> /// TODO - Add pow function remarks comment /// </remarks> /// <param name="base"> /// the base for exponentiation /// </param> /// <param name="exponent"> /// TODO - Add exponent parameter comment /// </param> /// <param name="power"> /// the power we are taking the base to. /// TODO - Remove param tag /// </param> /// <returns> /// TODO - Add return comment /// </returns> public static double pow(double base, double exponent) { … }

24. Accessing the XML Documentation Comments • CodeElement and DocComment: • CodeElement.DocComment does not exist • But DocComment exists for children of CodeElement • Getting DocComment from CodeElement: • Robbins uses a large Select...Case statement • Based on CodeElement.Kind property • In CommenTater.VB's RecurseCodeElements function • DocComment: • Is read/write • Is (and must be) fully formed XML fragment: • xml declaration line is not needed • <doc> ... </doc> is needed • &amp; &gt; &lt; instead of & > <

25. Other Issues: • Desired: Press Ctrl+Z to undo all changes to doc comments made by macro • Wrapping all changes within a single undo context did not work • Each method/property doc comment change now has its own undo context • You would need to press Ctrl+Z once per method/property changed • Directly writing function names as string into XML caused problems • Due to operator &, operator <, >, <<, >>

26. CommenTater History: • First version: • Did not set DocComment • Instead, edited code text manually • Code is kept in CommenTater.VB • At the bottom of all code • Commented out • To show work needed to insert text directly • Checked only for completely missing doc comments • Did not handle partially complete doc comments

27. CommenTater History: (Cont.) • Current version: • Sets DocComment property of the CodeElements • Handles partially completed doc comments • Marks (does not delete) extra param comments • Checks for: • summary, remarks, param, returns • Copies as is: • example, permission, exception • Reorders these parts of doc comments, in this order • Future enhancements: • Parse the function for "throw" clauses • Add a new exception entry for each such clause • Mark <exception> comments without matching "throw", to be removed

28. Visual Studio .Net Ate My Exception! • Visual Studio .Net is quite silent about exceptions thrown by your macros. • This can make debugging your macro very hard. • In Exceptions Dialog box: • Exceptions • Common Language Runtime Exceptions • When The Exception is Thrown: • Break Into The Debugger (select this) • This causes many more stops, but it's better than ignored exceptions

29. Add-Ins • Add-ins allow you to: • Add your own tool windows and dialog boxes to the IDE • Add your own command bars (menus and toolbars) to the IDE • Add custom property pages to the Options dialog box (for your tools)

30. Add-Ins are Hard to Use • Developing and debugging is much more difficult with add-ins than with macros • Learn the interface using macros first

31. Add-Ins are COM Objects • Managed languages support COM • You can write add-ins in Visual Basic.Net or C# • You can use OLE/COM Object Viewer to view properties of the .Net extensibility model • You can also use the “extensibility browser” in Unsupported Tools add-in

32. Sample Add-Ins • See: • http://msdn.microsoft.com/vstudio/downloads/samples/automation.asp • This page contains all the add-ins Microsoft has released • Many add-ins are written in multiple languages • Some advanced ones are only in C++

33. Sample C++ Add-Ins • Code is rife with: • Magic macros • That do error handling through gotos • That rely on assumed names • This is how not to program • Automatic macro  add-in converter macro also produces similar horrible code

34. The SuperSaver Add-In • Saves in the background as you work • Trims end-of-line whitespace • Originally appeared in BugSlayer column in MSDN Magazine • The book’s version is completely different • Went through seven completely unique versions

35. Using Regular Expressions • Original: “[ \t]+$”  “” • Removed active line’s tabulation • Modified: “{[^ \t]+}{[ \t]+$}”  “\1” • Didn’t work with Document.ReplacePattern • Find-replace macro… • Modified user entered values in find dialog • Wrapped in save-restore to avoid this.

36. Special Cases Cause Errors • In form designer view, find-replace (Find.Execute) threw Exceptions • Catch and ignore them! • Read-only files cause trouble • Conditional call to SafeFindObject • Virgin (newly created unsaved) files: Save As dialog pops up, but call doesn’t block. • Turn it on/off for these files

37. Undocumented Features • Must restore active document after find-replace • DTE.ActiveWindow returns all active Windows (for all the IDE Windows) • Robbins had to do some digging to get the “active document caption string”, to restore the active document after find-replace.

38. Dialog, then Exception • For virgin files, Save As dialog box pops up • If you click Cancel, an Exception is thrown • Document.Save throws a COMException: • “User pressed Escape out of save dialog” • Robbins: This is how not to write code that throws exceptions

39. SuperSaver: Pain in the Neck • There were too many problems associated with: • Special cases • Undocumented features • Unexpected behavior • Incomplete or buggy implementation

40. SettingsMaster Add-In • Problem-free implementation • One of the most useful tools Robbins has ever written. • Allows setting all options for a project • Ensures settings are correct • Not already available in Visual Studio .Net! • Good tool to synchronize development teams’ environments

41. Schema • Configurations • ProgLanguage • Configuration • ConfigName • Properties • Property • PropertyName • PropertyType • PropertyValue

42. Schema Parts • ProgLanguage: Unique GUID • Configuration: Build configuration • ConfigName: Debug, Release • Properties have name, type, value: <PropertyName>IncrementalBuild </PropertyName> <PropertyType>Boolean </PropertyType> <PropertyValue>1</PropertyValue>

43. Schema for C++ • Configurations • ProgLanguage • Configuration • ConfigName • Tools • Tool • ToolName • Properties • …

44. Desired Future Enhancements • Configuration editor • Event handler to automatically update project settings • Saving existing configuration values • Display changes made by SettingsMaster in the Output window

45. Summary • Start with Visual Basic macros • Use macros for most extensions • Add-ins are COM extensions • Add-ins are much harder to develop and test