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

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

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

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

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)

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)

The Basics VSTO compatibility and Add-in functionality VSTO/VSTO runtime version Developed against Office 2007Developed against Office 2010.NET versionAvailable as Document-levelApplication-levelDocument-levelApplication-level VSTO 3.0Word, Excel Word, Excel, Outlook, PowerPoint, Visio, InfoPath, Project, SharePoint 2007 Workflows ——.NET 3.5 Built into Visual Studio 2008 Professional and above VSTO 4.0Word, Excel Word, Excel, Outlook, PowerPoint, Visio, InfoPath, Project Word, Excel Word, Excel, Outlook, PowerPoint, Visio, InfoPath, Project.NET 3.5 or 4.0 Built into Visual Studio 2010 Professional and above

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

The Basics Project Types –Application Add-ins –Document Excel or Word Template Excel Workbook Word Document

The Basics Project Framework –Really easy to start a new project –New Project | 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

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

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

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

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

Ribbon Extensibility Ribbon Designer and Ribbon XML Demo

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

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

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

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.

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.

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.

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

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.

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

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

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

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

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

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

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

Event Demo Save Event Demo

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

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

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 1.You need administrative privilege on the machine in order to install an All User add-in. 2.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“ 3.Trusting the Add-In for all users

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

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.

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.

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

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

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\...”

Links VSTO VSTO Office Development in VSTO - us/office/hh133430http://msdn.microsoft.com/en- us/office/hh Office Development in Visual Studio Features Available by Office Application and Project Type - – Outlook 2010 User Interface - us/library/ee aspx#OfficeOLExtendingUI_Explorerhttp://msdn.microsoft.com/en- us/library/ee aspx#OfficeOLExtendingUI_Explorer Custom Task Panes Overview - us/library/aa aspx - us/library/aa aspx

Links Word Object Model Overview - us/library/kw65a0we.aspxhttp://msdn.microsoft.com/en- us/library/kw65a0we.aspx Excel Object Model Overview - us/library/wss56bz7.aspxhttp://msdn.microsoft.com/en- us/library/wss56bz7.aspx PowerPoint 2010 Developer Reference Outlook 2010 Object Model - us/library/ms aspxhttp://msdn.microsoft.com/en- us/library/ms aspx ClickOnce Security and Deployment Walkthrough: Creating your first Word Add-in

Links Office Fluent User Interface Control Identifiers RequestCOMAddinAutomationService - us/library/microsoft.office.tools.addinbase.requestcomaddinaut omationservice.aspx us/library/microsoft.office.tools.addinbase.requestcomaddinaut omationservice.aspx Deploying your VSTO add-in to All Users - your-vsto-add-ins-to-all-users-saurabh-bhatia.aspx your-vsto-add-ins-to-all-users-saurabh-bhatia.aspx VSTO SP1 Fastpath issue - will-cause-a-vsto-addin-to-not-find-its-config-file.aspx will-cause-a-vsto-addin-to-not-find-its-config-file.aspx

Links Customizing the 2007 Office Fluent Ribbon for Developers 1/3 - us/library/aa338202(v=office.12).aspx us/library/aa338202(v=office.12).aspx Deploying a Customized Ribbon and Quick Access Toolbar Customizing Context Menus for Office Customizing the Office 2010 Backstage View -

Questions?

time to make a difference.