Transcript 'Time to Make a Difference' PowerPoint Template

.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
VSTO 3.0
VSTO 4.0
Developed against Office 2007
Document-level
Application-level
Word, Excel
Word, Excel, Outlook,
PowerPoint, Visio,
InfoPath, Project,
SharePoint 2007
Workflows
Word, Excel
Word, Excel, Outlook,
PowerPoint, Visio,
InfoPath, Project
Developed against Office 2010
Document-level
Application-level
—
—
Word, Excel
Word, Excel,
Outlook,
PowerPoint, Visio,
InfoPath, Project
.NET version
Available as
.NET 3.5
Built into
Visual Studio
2008
Professional
and above
.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
• <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
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
VSTO
Unmanaged /
COM Interop
Managed Code
Office Automation
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
Managed
RCW
IUnknown
Unmanaged /
COM Interop
INew
IDispatch
INew
Managed Code
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 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/enus/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/enus/library/ee692172.aspx#OfficeOLExtendingUI_Explorer
• Custom Task Panes Overview - http://msdn.microsoft.com/enus/library/aa942864.aspx -
Links
• Word Object Model Overview - http://msdn.microsoft.com/enus/library/kw65a0we.aspx
• Excel Object Model Overview - http://msdn.microsoft.com/enus/library/wss56bz7.aspx
• PowerPoint 2010 Developer Reference http://msdn.microsoft.com/en-us/library/ff746846.aspx
• Outlook 2010 Object Model - http://msdn.microsoft.com/enus/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
Links
• Office Fluent User Interface Control Identifiers http://www.microsoft.com/download/en/details.aspx?id=6627
• RequestCOMAddinAutomationService http://msdn.microsoft.com/enus/library/microsoft.office.tools.addinbase.requestcomaddinaut
omationservice.aspx
• Deploying your VSTO add-in to All Users http://blogs.msdn.com/b/vsto/archive/2010/03/08/deployingyour-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-sp1will-cause-a-vsto-addin-to-not-find-its-config-file.aspx
Links
• Customizing the 2007 Office Fluent Ribbon for Developers 1/3 http://msdn.microsoft.com/enus/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
Questions?
time to make a difference.