.NET SIG Presentation on

1. .NET SIG Presentation on Visual Studio Tools for Office – A Primer by Anthony Maimone & Ted Ogrean

2. About Us • Anthony • Developer • Product Lead for the Office Business Applications • 5 years experience at Hyland Software • Ted • Development Manager • Product Lead for SharePoint Integrations • 6 years experience at Hyland Software

3. What are we covering? • The Basics of VSTO • Ribbon Extensibility • Office Application Specifics • Event Handling • Deployment Options • Lessons Learned

4. The Basics • Visual Studio Tools for Office (VSTO) • Create applications that extend Microsoft Office 2003, 2007, and 2010 using managed code. • Think of as a bridge between VS and Office • Visual Studio 2003, 2005, 2008, 2010 • VSTO 2003, 2005, 2005 SE, 3.0, 4.0 • We are going to stick with 3.0 and 4.0

5. The Basics • VSTO 3.0 Prerequisites • Operating System • Windows 7, Server 2003, Server 2008, Vista, XP • .NET Framework 3.5 or 3.5 Client Profile • Microsoft Office 2007 • Visual Studio 2008 • Office Primary Interop Assemblies (PIAs)

6. The Basics • VSTO 4.0 Prerequisites • Operating System • Windows XP SP 3 or greater • .NET Framework 3.5, 4, or 4 Client Profile • Microsoft Office 2007 or Office 2010 • Visual Studio 2010 • Office Primary Interop Assemblies (PIAs)

7. The Basics • VSTO compatibility and Add-in functionality

8. Demo Solution Lets see what a complete VSTO add-in based application looks like

9. The Basics • Project Types • Application • Add-ins • Document • Excel or Word Template • Excel Workbook • Word Document

10. The Basics • Project Framework • Really easy to start a new project • New Project • <Language> | Office | select Add-in from list • Create a new ribbon type class • Designer or XML • If XML, follow the Ribbon XML steps to get ribbon to load • Handle events • Begin building your ribbon and handling callbacks

11. New Project Stub Create a New VSTO Add-in for Word Demo

12. The Basics • Application Level Add-in • Accessing the Object model of the Office host application • Customizing UI of the application • Custom task panes (Excel, InfoPath, Outlook, PowerPoint, Word) • Exposing objects of your Add-in to other Office solutions • AddInBase.RequestComAddInAutomationService

13. The Basics • Application Level Add-in • Registry Keys • HKCU\Software\MS\Office\Word • HKLM\Software\MS\Office\Word • Deployment Manifest • An XML file that describes a ClickOnce Deployment • Identifies the current ClickOnce version • Application Manifest • An XML file that identifies (SxS) assemblies, bound at runtime

14. The Basics • Document Level Add-in • When the document is opened, the code extension loads. • Automate the application by using its object model. • Add controls to the surface of the document. • Manage certain aspects of the document while on a server without Microsoft Office installed. • Customize the UI of the application for the specific document • Custom Xml parts

15. Ribbon Extensibility Ribbon Designer and Ribbon XML Demo

16. Ribbon Designer • Pros • Context • Simple • Intuitive • Drag and Drop • Designer support • Similar to Win Forms • No need to type out xml • Can export to Ribbon XML • Cons • Error handling • Encourages code behind • Limited features • No Backstage access • Cannot repurpose built-in commands • Cannot define context menus

17. Ribbon XML • Pros • More Extensibility • Flexible • Faster • More Powerful • More features • Customize Quick Access Toolbar (QAT) • Context menus • Backstage (2010) • Repurpose built-in commands • Cons • Single callback file • Per Add-in • No context • Limited hooks • Tough to Debug • Need to Learn Ribbon XML

18. Office Application Specifics • Object Models • Classes and interfaces provided to interact with the Office Applications • Each model is contained in the Primary Interop Assembly or PIAs • More information on these a little later • Microsoft.Office.Interop.Word • Each applications object model is different • Contains hundreds of objects

19. Office Application Specifics • Outlook • Application Object • The highest level object representing the Outlook App • Explorer Object • The Main Outlook Window • Displays the content of a folder (mail, tasks, appt.) • Ribbon ID = Microsoft.Outlook.Explorer • Inspector Object • Represents a window that displays a single item. • 23 total items each with a different Ribbon identifier • Ex. Mail Compose, Mail Read, Contact, Distribution List, Meeting Request, Task, etc.

20. Office Application Specifics • Outlook continued • Context Menus • Using Ribbon XML, you have the ability to add options to the context menu • Folder, Store, Mail Item, Appointments, etc. • The Reading Pane • Allows users to view the selected item in the Explorer • We handle dragging and dropped items to a folder • Can cause problems with events • The BeforeItemMove event does not get thrown when an item is already open in the Reading Pane.

21. Office Application Specifics • Excel • Application • The Excel application itself, options that are applied currently, and current users’ objects • Workbook • A single workbook in the Excel application • Worksheet • A worksheet within a workbook. • Range • Represents a cell, row, column, selection or block of cells for manipulation within Excel.

22. Office Application Specifics • PowerPoint • Application • Represents the PowerPoint application and it’s the parent of all other objects • Control’s the PowerPoint environment • Application Events • AfterNewPresentation, PresentationClose, etc. • Presentation • Represents a presentation and all of its content • Presentation methods and properties • Save, SaveAs, FullName, Path

23. Office Application Specifics • Word • Application • Represents the Word application and is the parent of all other object • Controls the Word environment • Application events • DocumentBeforeSave, DocumentOpen, etc. • Document • Represents a document and all of its content • Document methods and properties • Close, Save, SaveAs, FullName, etc.

24. Office Application Specifics • Excel vs. PowerPoint vs. Word • Word is an SDI application • Excel and PowerPoint are MDI applications • MDI applications and task panes • Mapping of task panes for each document • Based on Window and Workbook Activate and Deactivate events • Each object model is different • Be careful not too assume that Excel, PowerPoint, and Word all behave the same • Ex. Save method looks similar, but parameters and behavior are different for each application

25. Event Handling Office Interop VSTO Unmanaged / COM Interop Managed Code Office Automation Hosts Managed Add-ins

26. Event Handling • Office Primary Interop Assemblies (PIAs) • Enables managed code to interact with Microsoft Office application’s COM-based object model • Properties • Events • Add-in load and shut down • Uses a Runtime Callable Wrapper (RCW) to handle interaction and memory model • Visual Studio creates a reference when a new Office Project is created

27. Event Handling • Office Primary Interop Assemblies (PIAs) • Included with Visual Studio • Must be installed and registered on end-user computers to run Office solutions targeting .NET 3.5 • When targeting .NET 4.0, PIAs can be embedded into your solution (Embed Interop Types property) • 32 or 64 bit are available. • AnyCPU for both • Provides Intellisense and code samples

28. Event Handling Unmanaged RCW Managed INew IUnknown IDispatch Unmanaged / COM Interop Managed Code INew

29. Event Handling • Memory Model • Managed • Nondeterministic lifetime • Follows .NET Garbage Collection rules • RCW handles marshaling multiple clients • Keeps an internal reference count • Unmanaged • Deterministic lifetime • Follows COM rules • Single reference count

30. Event Handling • Save Event • WorkbookBeforeSave( Excel.Workbook Wb, bool SaveAsUI, ref bool cancel) • DocumentBeforeSave( Word.Document Doc, ref bool SaveAsUI, ref bool Cancel) • PresentationBeforeSave( PowerPoint.Presentation Pres, ref bool Cancel) • In your best interest to NOT override or cancel the Save event. • Interfere with macros, other Add-ins, etc. • Auto Save cannot be distinguished from Save

31. Event Demo Save Event Demo

32. Deployment • MSI • Generic Windows installer • Must check prerequisites VSTO and .NET framework prior to installing Add-in

33. Deployment • ClickOnce • Create self-updating Windows-based applications • Installed and run with minimal user interaction from web, network share, or media (CD) • Major issues overcome • Updating application, impact on the user’s machine, security permissions (CAS) • Must install prerequisites through a separate installer • Created a separate MSI to check for VSTO installation

34. Deployment • VSTO deployments are generally only for the Current User • Can be made for All Users on a given machine • When installing, must use the HKLM registry path • HKLM\Software\MS\Office\Word\Addins • You need administrative privilege on the machine in order to install an All User add-in. • An all user add-in cannot be deployed through ClickOnce and must be deployed through a Windows Installer MSI. • manifest = “C:\Program Files\MyVSTOAddIn\MyVSTOAddIn.vsto|vstolocal“ • Trusting the Add-In for all users

35. Lessons Learned • Create separate add-ins for each Office application • This is the general idea behind VSTO • Be very careful of start-up and load times • Lazy initialization is your friend • If you let a COM object leave scope, do not release it. Better yet, don’t let COM objects leave local scope. • Do not release a COM object if you are not the owner. • When using a foreach loop to iterate over COM objects, release each item properly

36. Lessons Learned • Be explicit with your code. Each “.” may create another reference that needs to be released • Example (VB) • var app = new Application(); • app.Workbooks.Add(); • app.Visible = true; • app.Quit() • app.Workbooks creates a RCW reference that we cannot release.

37. Lessons Learned • Office PIAs do not always clean up event interfaces • Can lead to Office application not closing properly • Major issue with Terminal Services or Citrix • Created our own Interop project for each version • Referenced each Office Interop • Excel, PowerPoint, Word • Extended each set of events and events provider • Properly release each COM Object passed as a parameter • Fixed our issues with event interfaces not properly being cleaned.

38. Lessons Learned • Converting Ribbon Designer to Ribbon XML • Follow the rules in the new ribbon file. • After copying over your handlers or click events • Change from private to public • Change parameters to proper Ribbon XML • Generally to IRibbonControl control

39. Lessons Learned • VSTO_SUPPRESSDISPLAYALERTS • Environment variable, set to 0 (zero) • Displays VSTO errors as a message box • Extremely useful when debugging. • VSTO_LOGALERTS • Environment variable, set to 1 (one) • Writes the errors to a log file • Exists in the folder with the deployment manifest or %Temp% • Add-in name.vsto.log

40. Lessons Learned • After upgrading from VSTO 4.0 to 4.0 SP1, our add-ins are failing to load? • If you generate your own installer files, you specify how to write the manifest key to the registry. • manifest = “C:\Program Files\MyVSTOAddIn\MyVSTOAddIn.vsto|vstolocal“ • In SP1, that path changed to be • “file:///C:Program Files\...”

41. Links • VSTO 3.0 - http://www.microsoft.com/download/en/details.aspx?id=23656 • VSTO 4.0 http://www.microsoft.com/download/en/details.aspx?id=20479 • Office Development in VSTO - http://msdn.microsoft.com/en-us/office/hh133430 • Office Development in Visual Studio 2010 - http://msdn.microsoft.com/en-us/library/d2tx7z6d.aspx • Features Available by Office Application and Project Type - http://msdn.microsoft.com/en-us/library/aa942839(v=VS.100).aspx– • Outlook 2010 User Interface - http://msdn.microsoft.com/en-us/library/ee692172.aspx#OfficeOLExtendingUI_Explorer • Custom Task Panes Overview - http://msdn.microsoft.com/en-us/library/aa942864.aspx -

42. Links • Word Object Model Overview - http://msdn.microsoft.com/en-us/library/kw65a0we.aspx • Excel Object Model Overview - http://msdn.microsoft.com/en-us/library/wss56bz7.aspx • PowerPoint 2010 Developer Reference - http://msdn.microsoft.com/en-us/library/ff746846.aspx • Outlook 2010 Object Model - http://msdn.microsoft.com/en-us/library/ms268893.aspx • ClickOnce Security and Deployment - http://msdn.microsoft.com/en-us/library/t71a733d.aspx • Walkthrough: Creating your first Word Add-in http://msdn.microsoft.com/en-us/library/cc442946.aspx

43. Links • Office Fluent User Interface Control Identifiers - http://www.microsoft.com/download/en/details.aspx?id=6627 • RequestCOMAddinAutomationService - http://msdn.microsoft.com/en-us/library/microsoft.office.tools.addinbase.requestcomaddinautomationservice.aspx • Deploying your VSTO add-in to All Users - http://blogs.msdn.com/b/vsto/archive/2010/03/08/deploying-your-vsto-add-ins-to-all-users-saurabh-bhatia.aspx • VSTO SP1 Fastpath issue - http://blogs.msdn.com/b/vsod/archive/2011/06/14/vsto-4-0-sp1-will-cause-a-vsto-addin-to-not-find-its-config-file.aspx

44. Links • Customizing the 2007 Office Fluent Ribbon for Developers 1/3 - http://msdn.microsoft.com/en-us/library/aa338202(v=office.12).aspx • Deploying a Customized Ribbon and Quick Access Toolbar - http://msdn.microsoft.com/en-us/library/ee704589.aspx • Customizing Context Menus for Office 2010 - http://msdn.microsoft.com/en-us/library/ee691832.aspx • Customizing the Office 2010 Backstage View - http://msdn.microsoft.com/en-us/library/ee815851.aspx

45. Questions?

46. time to make a difference.