Embed Size (px)
Citation preview
Getting Started
Add-in Express for IE and .NET Add-in Express™ 2010 for Internet Explorer and .NET
page 2
Add-in Express™ 2010 for Internet Explorer and .NET
Revised on 19-Dec-10
Copyright © Add-in Express Ltd. All rights reserved.
Add-in Express, ADX Extensions, ADX Toolbar Controls, Afalina, AfalinaSoft and Afalina Software are trademarks or registered trademarks of Add-in Express
Ltd. in the United States and/or other countries. Microsoft, Outlook, and the Office logo are trademarks or registered trademarks of Microsoft Corporation in the
United States and/or other countries. Borland and the Delphi logo are trademarks or registered trademarks of Borland Corporation in the United States and/or
other countries.
THIS SOFTWARE IS PROVIDED "AS IS" AND ADD-IN EXPRESS LTD. MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED. BY
WAY OF EXAMPLE, BUT NOT LIMITATION, ADD-IN EXPRESS LTD. MAKES NO REPRESENTATIONS OR WARRANTIES OF MERCHANTABILITY OR
FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF THE LICENSED SOFTWARE, DATABASE OR DOCUMENTATION WILL NOT
INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.
Add-in Express for IE and .NET Table of Contents
page 3
Table of Contents
Add-in Express™ 2010 for Internet Explorer and .NET ..................................................... 2
Introduction ........................................................................................................................... 6
Why Add-in Express?........................................................................................................................................... 7
System Requirements .......................................................................................................................................... 8
Technical Support ................................................................................................................................................ 9
What's new in version 2010 ............................................................................................................................... 10
Installing and Activating .................................................................................................................................... 11 Activation Basics ............................................................................................................................................................ 11 Setup Package Contents ................................................................................................................................................ 12
Getting Started .................................................................................................................... 13
Add-ons for Internet Explorer ........................................................................................................................... 14 Creating a Project ........................................................................................................................................................... 14 Add-in Express Project Structure ................................................................................................................................. 16 IEModule .......................................................................................................................................................................... 16 Customizing the Internet Explorer UI at a Glance ........................................................................................................ 19 Custom Toolbar Buttons and Menu Items .................................................................................................................... 21
Comparing the Ways .................................................................................................................................................... 21 IE Command ................................................................................................................................................................ 21 Adding a Custom Toolbar Button ................................................................................................................................. 22 Adding a Custom Menu Item ........................................................................................................................................ 23 Adding Custom Controls onto the Standard IE Toolbar ................................................................................................ 24 Adding a Custom Item to the Main Menu ..................................................................................................................... 25
Custom Toolbars ............................................................................................................................................................ 26 Custom Explorer Bars .................................................................................................................................................... 29 Custom Context Menu Commands ............................................................................................................................... 32 Intercepting Keyboard Shortcuts .................................................................................................................................. 32 Handling HTML Events ................................................................................................................................................... 33 How Your Add-on Loads into IE .................................................................................................................................... 34
Shims ........................................................................................................................................................................... 34 Add-in Express Loader ................................................................................................................................................. 34
How Your Add-on Works ................................................................................................................................................ 35 IE Module Basics .......................................................................................................................................................... 35 Tabbing ........................................................................................................................................................................ 36 Windowing and Threading ............................................................................................................................................ 36 Instancing ..................................................................................................................................................................... 37 Messaging .................................................................................................................................................................... 38
Deploying Your Add-on ..................................................................................................................................... 40 Setup Project Wizard ...................................................................................................................................................... 40 Creating a Setup Project Manually ................................................................................................................................ 42
Add a New Setup Project ............................................................................................................................................. 42 File System Editor ........................................................................................................................................................ 42 Primary Output ............................................................................................................................................................. 42 Project-dependent Resources ...................................................................................................................................... 44 Add-in Express Loader and Manifest ........................................................................................................................... 44 MSHTML Interop Assembly ......................................................................................................................................... 45 Custom Actions ............................................................................................................................................................ 45
Add-in Express for IE and .NET Table of Contents
page 4
Dependencies .............................................................................................................................................................. 45 PostBuildEvent ............................................................................................................................................................. 45 Prerequisites ................................................................................................................................................................ 45 IE Bar only .................................................................................................................................................................... 46 Deploy .......................................................................................................................................................................... 47
Web-based Deployment and Update ............................................................................................................................. 48 On the Development PC .............................................................................................................................................. 49 On the Target PC ......................................................................................................................................................... 52
Add-in Express Tips and Notes ........................................................................................................................ 54 Common stuff ................................................................................................................................................................. 54
What are interop assemblies? ...................................................................................................................................... 54 Deploying and Debugging ............................................................................................................................................. 54
Debugging .................................................................................................................................................................... 54 Deploying – Shadow Copy ........................................................................................................................................... 54 How Do I Find the PublicKeyToken of My Add-in? ....................................................................................................... 55 Deploying Localized IE Add-ons................................................................................................................................... 55 Version_info.xml ........................................................................................................................................................... 55
Finally .............................................................................................................................................................................. 55
Add-in Express for IE and .NET Why Add-in Express?
page 5
Introduction
Add-in Express for Internet Explorer and .NET is a development tool designed to
simplify and speed up the development of add-ons for Internet Explorer 6 and 7 in
Visual Studio 2005 and Visual Studio 2008 through the consistent use of the RAD
paradigm. It provides a number of specialized components that allow the developer to
walk through the interface-programming phase to the functional programming phase
with a minimal loss of time.
Add-in Express for IE and .NET Why Add-in Express?
page 6
Why Add-in Express?
The Microsoft IE SDK gives developers the ability to extend Internet Explorer with Browser Extensions. This term
includes features such as shortcut menu extensions, custom toolbars, Explorer bars, and Browser Helper
Objects (BHOs). Further on, we will use the term "add-on" instead of Browser Extensions.
When creating IE add-ons with Add-in Express, you overcome the basic problem – building your solutions into
the IE application. Based on the True RAD paradigm, Add-in Express saves the time that you would have to
spend on research, prototyping, and debugging numerous issues when creating an add-on for IE in Visual
Studio.
Add-in Express provides you with simple tools for creating version-neutral, secure, isolated, managed, and
deployable extensions for Internet Explorer.
Managed IE add-ons
You develop them in every programming language available for Visual Studio .NET.
Isolated IE add-ons
Add-in Express loads add-ons into separate application domains. Therefore, they do not have a chance to break
down Internet Explorer.
Version-neutral IE add-ons
The Add-in Express programming model and its core are version-neutral. That is, you can develop one add-on
that will work in both Internet Explorer 6 and 7.
Deployable IE add-ons
Add-in Express automatically supplies you with a setup project making your solution ready-to-deploy.
Add-in Express for IE and .NET System Requirements
page 7
System Requirements
Supported Visual Studio Editions
Visual Studio .NET 2010
Visual Studio .NET 2008 Team System
Visual Studio .NET 2008 Professional Edition
Visual Studio .NET 2008 Standard Edition
Visual Studio .NET 2005 Team System
Visual Studio .NET 2005 Professional Edition
Visual Studio .NET 2005 Standard Edition
RemObjects Chrome 1.53 and higher
.NET Framework
.NET Framework 2.0, 3.0, 3.5, 4.0
Supported Languages
Visual Basic .NET 2010
Visual Basic .NET 2008
Visual Basic .NET 2005
Visual C# 2010
Visual C# 2008
Visual C# 2005
Visual C++ .NET 2010
Visual C++ .NET 2008
Visual C++ .NET 2005
Internet Explorer
Internet Explorer 6.x
Internet Explorer 7.x (32-bit and 64-bit)
Internet Explorer 8.x (32-bit and 64-bit)
Add-in Express for IE and .NET Technical Support
page 8
Technical Support
Add-in Express is developed and supported by the Add-in Express Team, a branch of Add-in Express Ltd.
The Add-in Express web site at www.add-in-express.com provides a wealth of information and software
downloads for Add-in Express developers, including the HOWTOs section with sample projects answering most
common "how to" questions.
For technical support through the Internet, e-mail us at [email protected] or use our forums. We are
actively participating in these forums.
Add-in Express for IE and .NET What's new in version 2010
page 9
What's new in version 2010
Support for Windows 7
Support for Visual Studio 2010
Support for .NET Framework 4.0
Support for 64-bit versions of IE 7 and IE 8
Updated project wizard
New setup project wizard
Support for localized setup projects
Add-in Express for IE and .NET Installing and Activating
page 10
Installing and Activating
There are two main points in the Add-in Express installation. First off, you have to specify the development
environments in which you are going to use Add-in Express. Second, you need to activate the product. What
follows below is a brief guide on activation.
Activation Basics
During the registration process, the registration wizard prompts you to enter your license key. The key is a 30
character alphanumeric code shown in six groups of five characters each (for example, AXN6M-GBFTK-3UN78-
MKF8G-T8GTY-NQS8R). Keep the license key in a safe location and do not share it with others. This product
key forms the basis for your ability to use the software.
For purposes of product activation only, a non-unique hardware identifier is created from general information that
is included in the system components. At no time are files on the hard drive scanned, nor is personally
identifiable information of any kind used to create the hardware identifier. Product activation is completely
anonymous. To ensure your privacy, the hardware identifier is created by what is known as a "one-way hash".
To produce a one-way hash, information is processed through an algorithm to create a new alphanumeric string.
It is impossible to calculate the original information from the resulting string.
Your product key and a hardware identifier are the only pieces of information required to activate the
product. No other information is collected on your PC or sent to the activation server.
If you choose the Automatic Activation Process option of the activation wizard, the wizard attempts to establish
an online connection to the activation server, www.activatenow.com. If the connection is established, the wizard
sends both the license key and the hardware identifier over the Internet. The activation service generates an
activation key using this information and sends it back to the activation wizard. The wizard saves the activation
key to the registry.
If an online connection cannot be established (or you choose the Manual Activation Process option), you can
activate the software using your web-browser. In this case, you will be prompted to enter the product key and a
hardware identifier on a web page, and will get an activation key in return. This process finishes with saving the
activation key to the registry.
Activation is completely anonymous; no personally identifiable information is required. The activation key can be
used to activate the product on that computer an unlimited number of times. However, if you need to install the
product on several computers, you will need to perform the activation process again on every PC. Please refer
to your end-user license agreement for information about the number of computers you can install the software
on.
Add-in Express for IE and .NET Installing and Activating
page 11
Setup Package Contents
The Add-in Express 2010 for Internet Explorer and .NET setup program installs the following folders on your PC:
Bin – binary files
Docs – documentation
Images – icons
Interop Assemblies – version-neutral interops
Redistributables – redistributable files
Sources – source code (see the note below).
Where is the Add-in Express source code?
Please note that the source code of Add-in Express is or is not delivered depending on the product
package you purchased. See the Feature Matrix page on our web site for details.
Add-in Express for IE and .NET setup program installs the following text files on your PC:
licence.txt – EULA
readme.txt – short description of the product, e-mail addresses and such
whatsnew.txt – this file describes the latest information on the product features added and bugs fixed.
Add-in Express for IE and .NET Getting Started
page 12
Getting Started
In this chapter, we guide you through the following steps of developing Add-in Express projects:
Creating an Add-in Express project
Adding Add-in Express components to the designer
Building, registering, and debugging the Add-in Express project
Tuning up the Add-in Express loader based setup project
Deploying your project to a target PC
The UI described in this document is created by the add-on available for download at
C# - http://www.add-in-express.com/files/howtos/cs/custom-ie-ui-vs2005-cs.zip
VB - http://www.add-in-express.com/files/howtos/vb/custom-ie-ui-vs2005-vb.zip
Add-in Express for IE and .NET Creating a Project
page 13
Add-ons for Internet Explorer
Creating a Project
Add-in Express adds several project templates to the Extensibility folder of the New Project dialog. To see the
dialog, choose the “File | New | Project…” menu.
As you can see, there are IE Add-on, IE Bar and IE Toolbar project templates in this dialog. They produce
projects that differ in small details such as type names. You can't create IE toolbars in the IE Bar project and vice
versa, you can't create IE bars in the IE Toolbar project. IE Add-on allows combining toolbars and IE bars in one
project. However, the most essential difference lies in their deployment. The only IE extension type that is
installable by a standard user is IE Bar. All other project types require administrative privileges when your
solution is installed on the target PC.
To create a project, select an appropriate project template icon and click OK. This invokes the Add-in Express
project wizard (see below).
Add-in Express for IE and .NET Creating a Project
page 14
The project wizard allows selecting the programming language and interop assemblies to be used in your
project. Selecting a programming language is of course a straightforward action. Choosing the correct interop
requires understanding. The following table illustrates this option in more detail:
The Interop Assemblies option IE version installed on the
development PC
IE versions supported by the
add-on
Version-neutral (IE 6 and higher) IE6, IE7, or IE8 IE6, IE7, and IE8
For the currently installed IE version IE6 IE6, IE7, and IE8
For the currently installed IE version IE7 IE7 and IE8
For the currently installed IE version IE8 IE8
To access properties or methods defined in a newer IE version, you use late binding (see
Type.InvokeMember in MSDN). To use constants defined in a newer IE version, you must know them; we
suggest using the .NET Reflector to obtain constants defined in newer versions of IE . As to events, the IE
module provides all events; just use an appropriate one.
The second window of the project wizard allows choosing between using the existing .SNK file or creating a new
one.
Add-in Express for IE and .NET Add-in Express Project Structure
page 15
Add-in Express Project Structure
A newly created Add-in Express solution is shown on the screenshot:
Let's walk through the files.
The files in the Loader folder (adxloader.dll, adxloader64.dll
and adxloader.dll.manifest) get your add-on to load into
Internet Explorer. You use the manifest to tune this process.
See Add-in Express Loader.
The files in the Resources folder are just sample icons for
toolbar buttons. They are pre-added to Icons.resx (see
Adding a Custom Toolbar Button). They serve as
placeholders only and you need to replace them with actual
icons in your add-on.
IEModule.vb – the heart of the project; provides properties,
methods and events relating to the add-on and its UI. See
IEModule.
MyIEAddon1.snk – a strong-name key file.
IEModule
IEModule is the core part of the add-on. From some point of view, it is the add-on itself. It specifies the name of
your add-on and stores components that represent toolbars, toolbar buttons, menu items, context menu items,
and Explorer bars created by your add-on. In addition, it is a
container for other components required for the add-on to
function. Finally, it communicates with the IE application to
provide you with a complete set of IE events such as
BeforeNavigate2 and DownloadComplete.
You access the module's designer and code via the context
menu in the Solution Explorer window.
The designer surface of the IEModule provides a context menu revealing a number of commands; you
use these commands to add Add-in Express components to the module.
For a newly created project, the module contains the code shown below. Pay attention to the IEApp and
HTMLDocument properties; you will certainly use them in your code.
Add-in Express for IE and .NET IEModule
page 16
Imports System
Imports System.Runtime.InteropServices
Imports System.ComponentModel
Imports System.Windows.Forms
Imports IE = Interop.SHDocVw
'Add-in Express for Internet Explorer Module
<ComVisible(True), GuidAttribute("93B606AD-8D34-4EA0-BC5B-4B8EAAB5D297")> _
Public Class IEModule
Inherits AddinExpress.IE.ADXIEModule
#Region " Component Designer generated code. "
'Required by designer
Private components As System.ComponentModel.IContainer
'Required by designer - do not modify
'the following method
Private Sub InitializeComponent()
Me.components = New System.ComponentModel.Container()
'
'IEModule
'
Me.ModuleName = "MyIEAddon1"
End Sub
#End Region
#Region " Add-in Express automatic code "
'Required by Add-in Express - do not modify
'the methods within this region
Public Overrides Function GetContainer() As _
System.ComponentModel.IContainer
If components Is Nothing Then
components = New System.ComponentModel.Container
End If
GetContainer = components
End Function
<ComRegisterFunctionAttribute()> _
Public Shared Sub RegisterIEModule(ByVal t As Type)
AddinExpress.IE.ADXIEModule.RegisterIEModuleInternal(t)
End Sub
<ComUnregisterFunctionAttribute()> _
Public Shared Sub UnregisterIEModule(ByVal t As Type)
Add-in Express for IE and .NET IEModule
page 17
AddinExpress.IE.ADXIEModule.UnregisterIEModuleInternal(t)
End Sub
<ComVisible(True)> _
Public Class IECustomContextMenuCommands
Inherits AddinExpress.IE.ADXIEModule.ADXIEContextMenuCommandDispatcher
End Class
<ComVisible(True)> _
Public Class IECustomCommands
Inherits AddinExpress.IE.ADXIEModule.ADXIECommandDispatcher
End Class
#End Region
Public Sub New()
MyBase.New()
'This call is required by the Component Designer
InitializeComponent()
End Sub
Public Sub New(ByVal container As IContainer)
MyBase.New(container)
container.Add(Me)
'This call is required by the Component Designer
InitializeComponent()
End Sub
Public ReadOnly Property IEApp() As IE.WebBrowser
Get
Return CType(Me.IEObj, IE.WebBrowser)
End Get
End Property
Public ReadOnly Property HTMLDocument() As mshtml.HTMLDocument
Get
Return CType(Me.HTMLDocumentObj, mshtml.HTMLDocument)
End Get
End Property
End Class
Add-in Express for IE and .NET Customizing the Internet Explorer UI at a Glance
page 18
Customizing the Internet Explorer UI at a Glance
See Custom Toolbar Buttons and Menu Items.
See Custom Toolbars.
See Adding a Custom Item to the Main Menu
Add-in Express for IE and .NET Customizing the Internet Explorer UI at a Glance
page 19
See Custom Explorer Bars
See Custom Context Menu Commands
Add-in Express for IE and .NET Custom Toolbar Buttons and Menu Items
page 20
Custom Toolbar Buttons and Menu Items
Comparing the Ways
Adding a Toolbar Control onto the Command Bar
Provider IE6 IE7 IE8 Other aspects See
IE No Yes Yes You can add a button and/or
menu item. No dropdowns,
toggle buttons
IE Command, Adding a
Custom Toolbar Button
Add-in Express No Yes The
controls
are
mapped
to the
Tools
menu
Buttons, dropdowns, toggle
buttons
Adding Custom Controls onto
the Standard IE Toolbar
Adding a Menu Item to the Main Menu
Who provides IE6 IE7 IE8 Other aspects See
IE Yes Yes Yes You can add a button and/or
menu item. No checked menu
items. No icons for menu items.
IE Command, Adding a
Custom Menu Item
Add-in Express Yes Yes Yes Icons for menu items, checked
menu items
Adding Custom Controls onto
the Standard IE Toolbar
IE Command
A command is a custom button on its built-in toolbar called Command Bar (see the screenshot below) and/or a
corresponding menu item on either of two IE menus: Tools and Help.
Add-in Express for IE and .NET Custom Toolbar Buttons and Menu Items
page 21
To create a new command, in the Properties window for the IE
module, use the collection designer of the Commands property of the IE
module.
Note that Internet Explorer 6 supports adding custom items to the
Tools and Help menus only.
Adding a Custom Toolbar Button
In the Commands property editor, you add an item and specify its
properties. Note that every item allows creating a button and/or menu
item for the Help or Tools menu at the same time. To create a
custom toolbar button (IE7 and IE8 only), make sure that the
ShowInToolbar property is set to true.
The toolbar button must refer to two .ico files providing large and normal images for the active and default
(inactive) button states (see Toolbar Button Style Guide on MSDN). Note that Add-in Express creates a new
project with two sample images. You can think of them as of placeholders. That is, you need to add your images
to the resource file and specify them in appropriate properties of a command item.
The DefaultVisible property specifies if the button appears on the Internet Explorer toolbar by default. If the
user has customized the toolbar, the button will not appear on the toolbar automatically. The toolbar button will
be added to the choices in the Customize Toolbar dialog box and will appear if the toolbar is reset.
Add-in Express for IE and .NET Custom Toolbar Buttons and Menu Items
page 22
Adding a Custom Menu Item
You use the item created in Adding a Custom Toolbar Button to add a custom menu item to the IE Help or Tools
menu. To prevent showing the button in IE7 and IE8, set the ShowInToolbar property shown in the screenshot
below to false.
Add-in Express for IE and .NET Custom Toolbar Buttons and Menu Items
page 23
The only property required to display a menu item is Caption. The HelpText property specifies a string shown
in the Status Bar when you hover the mouse over the custom menu item (see below).
It is not possible to show an icon for the menu item created by an IE command. But see Adding a Custom Item
to the Main Menu.
Adding Custom Controls onto the Standard IE Toolbar
IE7 and IE8 allow adding buttons only on the Command Bar toolbar. Add-in Express enables IE7 developers to
show buttons, toggle buttons and dropdowns on the toolbar (for IE8, see the note below). You choose the Add
Commands command of the IE module in the context menu of its designer surface. This adds an
Add-in Express for IE and .NET Custom Toolbar Buttons and Menu Items
page 24
ADXIECommands component to the module; you add your controls to the editor of its Controls collection (see
the screenshots below).
You specify two ImageLists (just drop them onto the module) in the LargeImages and NormalImages
properties of the ADXIECommands component. You can use any image formats in these ImageLists; normal
images must be 16x16, large ones must be 20x20. The transparency color of the images is the color of the
bottom left pixel.
In IE8, the top level items specified in the ADXIECommands component are mapped to appropriate
items in the Tools menu.
Adding a Custom Item to the Main Menu
Add-in Express allows customizing any top-level item in the IE main menu. You choose the Add Main Menu
command of the IE module in the context menu of its designer surface; the command adds an ADXIEMainMenu
Add-in Express for IE and .NET Custom Toolbars
page 25
component onto the module. You select the component and, in the Properties window, activate the editor for its
Items property. Then you add your controls to the editor:
The settings above produce controls in the Edit menu; the screenshot is available in Error! Reference source
not found..
When IE creates its main menu, ADXIEMainMenu receives the OnCreateMenu event. Then all top-level menu
items receive the OnCreatePopupMenu event. Also, just before a menu item is created and shown, it receives
the OnCreateMenuItem event.
When showing an icon in the main menu of IE6, IE7, and IE8, the checked items displayed in the same
popup will lose their style in Vista. This doesn't relate to context menus in IE8.
It's not possible to create a custom top-level menu item.
Custom Toolbars
You start with adding a toolbar class to your project: choose Project | Add New Item in the menu and find the
class template in the Add-in Express Items / Internet Explorer branch.
Add-in Express for IE and .NET Custom Toolbars
page 26
This adds an empty toolbar component, a descendant of UserControl, to your project. Additionally, the
component provides a complete set of IE events such as BeforeNavigate2 as well as toolbar-related events
such as OnBeforeShow.
To bind the toolbar to your add-on, choose
the Toolbars property of the IE module,
and add an item (see the screenshot
below):
Add-in Express for IE and .NET Custom Toolbars
page 27
The properties of the item (ADXIEToolbarItem) allow you to specify whether the gripper (see Creating an
Internet Explorer-style Toolbar at MSDN) should be shown, the initial position of the toolbar, toolbar title, text of
the menu item bound to the toolbar, as well as the toolbar control itself. A resulting toolbar may have the
following look:
The ADXIEToolbar class, an ancestor of all toolbars, provides the following events listed in the order reflecting
the life-cycle of the toolbar:
Add-in Express for IE and .NET Custom Explorer Bars
page 28
OnConnect
OnBeforeShow
OnBeforeShowEx – allows you to prevent the IE bar from being shown
OnActivate
OnDeactivate
OnBeforeHide
OnBeforeHideEx – allows you to cancel hiding the IE bar
OnDisconnect
In addition, ADXIEToolbar provides the OnHeightAdjust event.
Custom Explorer Bars
Your IE bar may look like this:
The newly created IE bar has the command button (unavailable in IE6) and/or menu item; the user shows/hides
the bar by clicking on either of them.
The ideology of creating Explorer bars is similar to that of toolbars; you add a component derived from
UserControl to your project, then you add an item to the Bars collection of the IE module and bind the
component to the item.
Let's start: choose Project | Add New Item in the menu and find the corresponding class template in the Add-in
Express Items / Internet Explorer branch.
Add-in Express for IE and .NET Custom Explorer Bars
page 29
This adds a descendant of ADXIEBar representing an Internet Explorer bar to your project.
Now you add an item to the Bars collection of the IE module and specify its properties. The most important one
is BarType; it binds a bar component to the bar item (ADXIEBarItem). The absolute minimum of properties
required for your explorer bar to show up also includes Title and MenuText; these properties specify the IE
bar title and the caption of the menu item shown in the View | Explorer Bar menu. You can also choose whether
to show the bar vertically or horizontally and specify the maximal width or height of vertical and horizontal bars
respectively. The properties having "ToolButton" in their names, such as AddToolButton and
ToolButtonDefaultVisible, control the visibility and other aspects of the button that shows/hides the
Explorer bar; the button is added to the Command Bar toolbar of IE.
Add-in Express for IE and .NET Custom Explorer Bars
page 30
Here are ADXIEBar events listed in the order corresponding to the life cycle of the explorer bar:
OnConnect
OnBeforeShow
OnBeforeShowEx – allows you to prevent the IE bar from being shown
OnActivate
OnDeactivate
OnBeforeHide
OnBeforeHideEx – allows you to cancel hiding the IE bar
OnDisconnect
Because ADXIEBar is a descendant of UserControl, you can react to, say, resizing of the IE bar.
Add-in Express for IE and .NET Custom Context Menu Commands
page 31
Custom Context Menu Commands
To create a custom context menu item, add an item to the ContextMenu collection of the IEModule and
specify the item's properties: caption and contexts available for the context menu item.
Naturally, you need to handle the Click event of the context menu item.
Pay attention to the Contexts and ExtendedContexts properties of top-level context menu items; you can
use these properties for refining the context-sensitivity of your context menu items. Say, if you choose Anchor in
the Contexts property, you will be able to choose Anchor and Link in ExtendedContexts. In the same
fashion, you can limit your context menu items to any given HTML control type(s).
When IE creates its context menu for the first time, the OnCreateContextMenu event of the IE module is
raised; you can use this event for any sort of initialization. Before a given context menu item is created, it
receives the OnCreateContextMenuItem event; at this moment you can change its visibility, caption, position,
etc.
Intercepting Keyboard Shortcuts
The Add Keyboard Shortcut command of the IE module available in the context menu of its designer surface
adds an ADXIEKeyboardShortcut to the module. The component allows specifying the key combination that
will generate the OnAction event of the component only if the Enabled property of the component is true and
the HandleShortcuts property of the module is true. If the shortcut is specified in IE, the action related to the
shortcut will not be executed.
Add-in Express for IE and .NET Handling HTML Events
page 32
Handling HTML Events
Use the Add HTML Events command to add an
ADXIEHTMLDocEvents to the module. In the SupportedEvents
property of the component, select HTML control type(s) the events of
which the component will intercept. Then add event handlers to
appropriate events of the component. Every such event (OnClick is
an example) provides the eventObject parameter the use of which
is demonstrated in the code below:
Private Sub AdxiehtmlDocEvents1_OnClick( _
ByVal sender As System.Object, _
ByVal eventObject As System.Object, _
ByVal e As _
AddinExpress.IE.ADXCancelEventArgs) _
Handles AdxiehtmlDocEvents1.OnClick
'System.Diagnostics.Debugger.Launch()
Dim eventObj As mshtml.IHTMLEventObj2 = _
CType(eventObject, mshtml.IHTMLEventObj2)
Dim elem As mshtml.IHTMLElement = _
Me.HTMLDocument.elementFromPoint(eventObj.clientX, eventObj.clientY)
If elem IsNot Nothing Then
If TypeOf elem Is mshtml.IHTMLAnchorElement Then
Dim anchor As mshtml.IHTMLAnchorElement = _
CType(elem, mshtml.IHTMLAnchorElement)
Dim window As MyWindow = New MyWindow(Me.ParentHandle)
If System.Windows.Forms.MessageBox.Show(window, _
"You've clicked the link labelled '" _
+ elem.innerText _
+ "' and pointing to a page at " _
+ anchor.hostname + "." + vbCrLf + vbCrLf + _
"Do you want to continue?", _
Me.ModuleName, MessageBoxButtons.YesNo) _
= MsgBoxResult.No _
Then
e.Cancel = True
End If
End If
End If
End Sub
The MyWindow type above is a simple class implementing the System.Windows.Forms.IWin32Window
interface (see the code below). The window handle for MyWindow is supplied by the ParentHandle property of
the module that returns the handle (hwnd) of the tab window. Note that you must show messages in this way;
otherwise in IE8 RC1 installed on Windows 7 Beta, a message box is displayed below the IE window.
Add-in Express for IE and .NET How Your Add-on Loads into IE
page 33
Public Class MyWindow
Implements System.Windows.Forms.IWin32Window
Dim theHandle As IntPtr
Public Sub New(ByVal aHandle As System.IntPtr)
theHandle = aHandle
End Sub
Public ReadOnly Property Handle() As System.IntPtr _
Implements System.Windows.Forms.IWin32Window.Handle
Get
Return theHandle
End Get
End Property
End Class
How Your Add-on Loads into IE
Shims
Internet Explorer is unmanaged while an Add-in Express based add-on is a managed class library. Therefore,
there must be some software located between IE and your add-on; the software, or the shim, follows the rules
for IE add-ons and, at appropriate moment, loads the .NET Framework and starts the add-on.
Add-in Express Loader
An Add-in Express based IE add-on is supplied with a special precompiled shim - Add-in Express Loader. The
loader supplied as 32-bit and 64-bit DLLs (adxloader.dll, adxloader64.dll) is designed to fulfill the following basic
tasks: it loads the .NET Framework, creates a unique AppDomain for the add-on, and loads the add-on into the
AppDomain. Advanced options are provided to the developer by the manifest file (adxloader.dll.manifest) that
may have the following look:
<?xml version="1.0" encoding="utf-8"?>
<configuration>
<assemblyIdentity name=" MyIEAddon1, PublicKeyToken=f9f39773da5c568a" />
<loaderSettings generateLogFile="true" shadowCopyEnabled="true"
privileges="administrator" configFileName=" MyIEAddon1.dll.config" >
<logFileLocation>C:\MyLog.txt</logFileLocation>
</loaderSettings>
</configuration>
Add-in Express for IE and .NET How Your Add-on Works
page 34
The loader allows generating a log file containing useful information about errors on the add-in loading stage.
The file is located here: My Documents\Add-in Express\adxloader.log. Also, you can disable the Shadow Copy
feature of the Add-in Express Loader, which is enabled by default (see Deploying – Shadow Copy). The
privileges attribute accepts the "user" string indicating that the installer generated by an Add-in Express
based setup project can be run with non-administrator privileges. The only user-installable IE extension type is
IE Bar. All other project types require using the "administrator" string for this attribute.
When an Add-in Express based project is being built, the loader files are copied from the Loader folder of your
project to the output directory of the setup project(s).
How Your Add-on Works
IE Module Basics
The version of IE is available in IEVersion. IEObj provides the IE application COM object. For the currently
loaded mshtml.HTMLDocument, see HTMLDocument (HTMLDocumentObj). Note that COM objects (and all
classes defined in mshtml are COM classes) can't cross the process boundaries; so you need to create a
method returning information provided by a COM object rather than using the COM object directly in your code.
You use Bars and Toolbars properties to get a collection of <Item> objects (ADXIEBarItem or
ADXIEToolBarItem); every <Item> object provides access to an <Obj> property (BarObj or ToolBarObj),
which returns an appropriate Add-in Express class type (ADXIEBar or ADXIEToolbar).
For instance, the code below demonstrates calling a public method defined in an ADXIEBar from the IE module:
'VB.NET
Dim barItem As AddinExpress.IE.ADXIEBarItem = Me.Bars(0)
Dim barObj As AddinExpress.IE.ADXIEBar = barItem.BarObj
Dim theBar As MyIEAddon1.MyIEBar1 = CType(aBar, MyIEAddon1.MyIEBar1)
theBar.MyMethod()
//C#
AddinExpress.IE.ADXIEBarItem barItem = this.Bars[0];
AddinExpress.IE.ADXIEBar barObj = barItem.BarObj;
MyIEAddon1.MyIEBar1 theBar = barObj as MyIEAddon1.MyIEBar1;
theBar.MyMethod();
Tabbing
The IsTabbedBrowsingEnabled property of the IE module informs you whether tabbing is enabled or not.
When the user opens a tab, the OnTabCreated and then OnTabActivated events are raised. At appropriate
Add-in Express for IE and .NET How Your Add-on Works
page 35
moments OnTabMoved and OnTabClosed occur. You can activate any given tab programmatically only if
ADXIEModule.IsQuickTabsEnabled is true; this means that the Quick Tabs feature in IE7 and IE8 is
enabled. To activate a tab, you call TabActivate; this causes OnTabChanging and OnTabChanged events to
fire. In IE6, you use the OnConnect event of the module to get to know when a window is opened and use the
HTML Events component (Handling HTML Events) to handle the OnActivate event of the Window HTML
element.
Note that all tab-related methods work asynchronously. The tab-related methods are TabActivate, TabFirst,
TabLast, TabNext and TabPrevious methods that activate the current, first, last, next and previous tabs
respectively. Another tab-related method is TabClose. It closes the current tab (also asynchronously).
Windowing and Threading
IE opens its windows in separate threads. Once an IE window is opened, IE creates an instance of your module,
toolbar, or IE bar; the instance fires the OnConnect event; the instance fires the OnDisconnect event when
the current tab (window in IE6) is closing. You can identify an instance of the IE module by the ID of the thread
that opens that window. Note that ADXIEBar and ADXIEToolbar provide the Module property that you can
cast to your module type. Below you will find how different IE versions open their windows.
IE6 opens IE windows in several threads running within several processes.
IE7 may open several main windows in the same or in different processes if tabbing is enabled and depending
on the way you open IE windows; each main window contains tab windows running in threads of their own.
IE8 may open several main windows. Each of them runs in several threads of the same process and contains
tab windows that run in threads of their own if tabbing is enabled and depending on the way you open IE
windows as well on the operating system that you use.
And here are some useful properties:
Process ID - ADXIEModule.ProcessID
Thread ID - ADXIEModule.ThreadID
IE main window - ADXIEModule.MainWindowHandle, ADXIEBar.MainWindowHandle,
ADXIEToolbar.MainWindowHandle
IE tab window - ADXIEModule.ParentHandle, ADXIEBar.ParentHandle,
ADXIEToolbar.ParentHandle; in IE6, this property returns the same value as MainWindowHandle
Tabbing is enabled - ADXIEModule.IsTabbedBrowsingEnabled
IE Module - ADXIEBar.Module, ADXIEToolbar.Module
See also Handling HTML Events for the code that uses ADXIEModule.ParentHandle to show a message
box.
Add-in Express for IE and .NET How Your Add-on Works
page 36
Instancing
In whatever way a tab (or window in IE6) is opened, this creates a new instance of the add-on (ADXIEModule).
This also creates new instances of toolbars, IE bars, main menu items, and context menu items; all of them work
in the same thread. The only thing that works in another thread or even process (IE8) is the commands that you
add on the Command Bar toolbar (IE7 and IE8 only); an instance of the commands is created for every main IE
window (ADXIEModule.MainWindowHandle).
So, your IE module is created for every IE tab. The total number of module instances is available in the
GetModuleCount property. You can access any module instance using either GetModuleByIndex or
GetModuleByThread; make sure that you supply these methods with proper values provided by
GetModuleIndex and ThreadID.
You can call any public property or method of any module instance even if it runs in other process. This is
implemented via Remoting. For that reason, such calls are synchronous.
Mshtml-related classes cannot cross process boundaries; you need to create a method that returns the
needed information instead.
The sample code below demonstrates using a method defined in the module in order to get the URL of the
HTML document opened in the current tab (window in IE6). The method is invoked from an Explorer bar; the
resulting value is used to fill in a ListBox on the IE bar.
'...
Public Class MyIEBar1
Inherits AddinExpress.IE.ADXIEBar
Friend WithEvents ListBox1 As System.Windows.Forms.ListBox
Friend WithEvents Button1 As System.Windows.Forms.Button
'...
Private Sub Button1_Click(ByVal sender As System.Object, _
ByVal e As System.EventArgs) Handles Button1.Click
'System.Diagnostics.Debugger.Launch()
Me.ListBox1.Items.Clear()
Dim theModule As MyIEAddon1.IEModule = _
CType(Me.Module, MyIEAddon1.IEModule)
For i As Integer = 0 To theModule.GetModuleCount - 1
Dim aModule As MyIEAddon1.IEModule = _
CType(theModule.GetModuleByIndex(i), MyIEAddon1.IEModule)
Me.ListBox1.Items.Add(aModule.GetURL())
Next
End Sub
End Class
Add-in Express for IE and .NET How Your Add-on Works
page 37
'...
Public Class IEModule
Inherits AddinExpress.IE.ADXIEModule
'...
Friend Function GetURL() As String
Return Me.HTMLDocument.url
End Function
End Class
Messaging
The SendMessage, SendMessageToInstance and SendMessageToAll methods provide an asynchronous
way to invoke the functionality of the current, specified or of all instances of a module, toolbar, or Explorer bar.
This is implemented by sending a custom window message to a hidden add-on, toolbar, or IE bar window via the
Win32 API. For that reason, SendMessageToInstance provides the nativeHandle parameter, a proper
value for which is obtained using the NativeWindowHandle property (available for ADXIEModule, ADXIEBar,
and ADXIEToolbar). You can also use the FindNativeWindows method provided by ADXIEModule,
ADXIEBar, and ADXIEToolbar. This method allows finding hidden windows that belong to the same main
window or process in IE. On the receiver side, you filter incoming messages (there will be a huge lot of non-
related window messages!) and invoke the functionality required in the OnSendMessage event.
Note that you may need to use SendMessage (it sends messages to the current IE module) because some
things aren't possible to do in a given event.
The code below demonstrates using SendMessageToAll to keep the same state of a checkbox through all
instances of an IE bar.
Friend Class MessageConstants
'window messages
Public Shared ReadOnly WM_USER As Integer = 1024
'custom
Public Shared ReadOnly WM_CHECKED As Integer = WM_USER + 10000
Public Shared ReadOnly WM_UNCHECKED As Integer = WM_USER + 10001
End Class
'...
Public Class MyIEBar1
Inherits AddinExpress.IE.ADXIEBar
Friend WithEvents CheckBox1 As System.Windows.Forms.CheckBox
Private IsProgrammaticChange As Boolean = False
'...
Private Sub CheckBox1_CheckedChanged( _
ByVal sender As System.Object, ByVal e As System.EventArgs) _
Add-in Express for IE and .NET How Your Add-on Works
page 38
Handles CheckBox1.CheckedChanged
'System.Diagnostics.Debugger.Launch()
If IsProgrammaticChange Then Exit Sub
'do my stuff
If Me.CheckBox1.Checked Then
Me.SendMessageToAll(MessageConstants.WM_CHECKED, _
IntPtr.Zero, IntPtr.Zero)
Else
Me.SendMessageToAll(MessageConstants.WM_UNCHECKED, _
IntPtr.Zero, IntPtr.Zero)
End If
End Sub
Private Sub MyIEBar1_OnSendMessage( _
ByVal e As AddinExpress.IE.ADXIESendMessageEventArgs) _
Handles MyBase.OnSendMessage
If e.Message = MessageConstants.WM_CHECKED Then
IsProgrammaticChange = True
Me.CheckBox1.Checked = True
IsProgrammaticChange = False
ElseIf e.Message = MessageConstants.WM_UNCHECKED Then
IsProgrammaticChange = True
Me.CheckBox1.Checked = False
IsProgrammaticChange = False
End If
End Sub
End Class
Add-in Express for IE and .NET Setup Project Wizard
page 39
Deploying Your Add-on
You create conventional .MSI installers using the Add-in
Express Setup Project Wizard that generates localized
setup projects (see also Creating a Setup Project
Manually. In addition, Add-in Express supports a simple
technology of Web-based Deployment and Update of IE
extensions.
Setup Project Wizard
You start the setup project wizard via the context menu of
your add-on project. (see the figure at the right). The
wizard allows specifying all sorts of description strings as
well as the location and localization of the setup project.
Add-in Express for IE and .NET Setup Project Wizard
page 40
Clicking on Finish adds the following setup project to the solution. Let's walk through the files.
AddinExpress.IE.dll is the Add-in Express assembly.
The loader files (adxloader.dll, adxloader64.dll and
adxloader.dll.manifest) are taken from the Loader
folder of your add-on project (see also Add-in
Express Project Structure).
adxregistrator.exe is a custom action executable that
registers and unregisters the add-on.
Interop.SHDocVw.dll and Microsoft.mshtml.dll are
interop assemblies.
Note that ieframe.dll and AddinExpress.IE.tlb are
excluded.
Add-in Express for IE and .NET Creating a Setup Project Manually
page 41
Creating a Setup Project Manually
You can always create a setup project with the Add-in Express project wizard when starting a new project.
Nevertheless, if you need to create a setup project manually, use the following step-by-step guide.
Add a New Setup Project
Right-click the solution item in the Solution Explorer window and choose Add | New Project.
In the Add New Project dialog, select the Setup Project item and click OK. This adds a new setup project to the
solution.
File System Editor
Right-click the newly added setup project item and choose View | File System in the context menu.
Primary Output
Right-click the Application Folder item and choose Add | Project Output
Add-in Express for IE and .NET Creating a Setup Project Manually
page 42
In the Add Project Output Group dialog, select the Primary output and Localized resources items of your add-
on project and click OK.
This adds the following entries to the Application Folder of your setup project.
Add-in Express for IE and .NET Creating a Setup Project Manually
page 43
Select AddinExpress.IE.tlb and, in the Properties window, set the Exclude property to True. Also, exclude
ieframe.dll in the same way.
Exclude all TLBs and OLBs
Always exclude all .TLB and .OLB files from the setup project except for .TLBs that you create
yourself.
Project-dependent Resources
Now you add all resources (e.g. assemblies, DLLs or any resources) required for your project.
Add-in Express Loader and Manifest
Add the adxloader.dll, adxloader64.dll and adxloader.dll.manifest files from the Loader subfolder of the add-in
project directory to the Application Folder of the setup project.
Add-in Express for IE and .NET Creating a Setup Project Manually
page 44
MSHTML Interop Assembly
Add Microsoft.mshtml.dll from the Interop Assemblies folder of the Add-in Express install folder to the Application
Folder in the setup project.
Custom Actions
Add the adxregistrator.exe file from the Redistributables folder of the Add-in Express install folder to
Application Folder.
Open the Custom Actions editor and add a new action to the Install, Rollback, Uninstall sections. Choose
adxregistrator.exe as an item for the custom actions.
Add the following values to the Arguments properties of the following custom actions:
Install
/install="MyIEAddon1.dll" /privileges=admin
Rollback
/uninstall="MyIEAddon1.dll" /privileges=admin
Uninstall
/uninstall="MyIEAddon1.dll" /privileges=admin
Please replace the "MyIEAddon1.dll" strings above with the file name of your add-on. See also IE Bar only.
Dependencies
Right click on the Detected Dependencies section of the setup project and choose Refresh Dependencies. Also,
exclude all dependencies that are not required for your setup.
PostBuildEvent
Set this property of the setup project as follows:
{Add-in Express folder}\Bin\adxpatch.exe" "$(BuiltOuputPath)" /UAC=On
Prerequisites
Right click on the setup project and open the Properties dialog.
Click on the Prerequisites button and, in the Prerequisites dialog, check all needed prerequisites.
Add-in Express for IE and .NET Creating a Setup Project Manually
page 45
You can choose the „Download prerequisites from the same location as my application‟ option to distribute all
prerequisites with the add-in installation package.
IE Bar only
IE Bar is the only IE extension type installable by a standard user. For your IE bar to be installed by a standard
user, you need to change the setup project as follows:
PostBuildEvent
{Add-in Express folder}\Bin\adxpatch.exe" "$(BuiltOuputPath)" /UAC=Off
DefaultLocation
Right-click the setup project item in the Solution Explorer window, choose View | File System in the context
menu, click Application Folder and set the DefaultLocation property as follows:
[AppDataFolder][Manufacturer]\[ProductName]
Add-in Express for IE and .NET Creating a Setup Project Manually
page 46
Custom Actions
Install
/install="MyIEBar1.dll" /privileges=user
Rollback
/uninstall="MyIEBar1.dll" /privileges=user
Uninstall
/uninstall="MyIEBar1.dll" /privileges=user
Please replace the "MyIEBar1.dll" strings above with the file name of your IE bar.
Deploy
Rebuild the setup project. Copy all setup files to the target PC and run the .msi file to install the add-in. However,
to install prerequisites, you will need to run setup.exe.
Add-in Express for IE and .NET Web-based Deployment and Update
page 47
Web-based Deployment and Update
Add-in Express provides support for web-based deployment and update of IE extensions. Unlike ClickOnce, it
allows the user to have administrative as well as non-administrative privileges when installing your solutions on
the target PC.
Add-in Express provides the Publish dialog that you use to specify the following:
the .MSI file generated by a setup project for your add-on, toolbar, or IE bar project
prerequisites (optional)
the installation URL where all versions of the add-on will be located.
The information above is used to generate three files:
setup.exe is an unmanaged executable, which is generated (using MSBUILD.EXE) only if the
prerequisites are specified. It downloads and installs the prerequisites from the installation URL/Language
ID/Version.
an automatically generated executable called
downloader; it downloads the .MSI file from the
installation URL/Language ID/Version and runs it. It
is started either by setup.exe (when it finishes
/installing prerequisites) or by the user (if no
prerequisites are required). The name of the
downloader is set to the name of your add-on
project, say "myaddon.exe". You can't change
this if you use prerequisites.
version_info.xml, an XML file describing add-on
versions available to the user and their installation URLs (see also Version_info.xml).
The user can only install your add-on after you actually publish the installer – just place setup.exe (if it exists) or
the downloader executable on a web server, CD, network, etc.
To create an update for your add-on, you generate another .MSI and publish it via the Publish dialog. The dialog
updates version_info.xml, generates setup.exe and downloader, and puts them into an appropriate folder
(Installation URL/Language ID/Version). Then you upload the files onto the web server specified in
version_info.xml for the previous add-on version.
When the code of your add-on calls the CheckForUpdates method, the version_info.xml is downloaded via
HTTP and parsed. If there are no updates, the method returns an empty string. If new updates are available, the
Add-in Express for IE and .NET Web-based Deployment and Update
page 48
method returns either the URL for setup.exe (if it exists) or the URL of the downloader for the latest update
available. Note that you can specify an arbitrary URL to be returned by CheckForUpdates. This allows
implementing custom update logics, welcome pages, information pages, etc.
On the Development PC
Step #1 – Publish Dialog
Publishing means preparing files and information required for the technology.
Build a setup project for your add-on, toolbar, or IE bar and click the Publish Add-in Express Project item in the
Build menu of your project.
Then you fill in the following textboxes:
Installer Path – the path to the .MSI file built by the setup project of your IE add-on solution
Installation URL – the URL of the root Web directory containing all versions of your add-on
Icon File – a .ICO containing an icon for the downloader UI (optional)
Certificate File – a .PFX providing the downloader certificate
Add-in Express for IE and .NET Web-based Deployment and Update
page 49
Step #2 – Prerequisites
Click the Prerequisites button and choose prerequisites required for your add-on.
Note that for a clean PC, installing .NET Framework 2.0 and Windows Installer 3.1 is a must.
Step #3 - Preferences
Clicking the Preferences button in the Publish dialog opens the following dialog:
The value specified in the "Download page for
updates" textbox is saved in the version_info.xml,
which is queried by the CheckForUpdates method.
This allows you to implement custom update logics. If
this field isn't set, CheckForUpdates returns either
the URL for setup.exe (if it exists) or the URL of the
downloader for the latest update available
Step #4 – Generating Installer
When everything is ready, you click the Publish button.
This generates a folder hierarchy that allows storing
installers for any number of versions for any number of
Add-in Express for IE and .NET Web-based Deployment and Update
page 50
languages. The folder hierarchy is located in the Publish folder of your add-on project:
The folders and their contents are given in the following table:
Folder name Folder name description Folder files
Publish Pre-defined name Version_info.xml (see also
Version_info.xml)
1033 The folder name is set to the
language identifier of the .MSI file
None
1.0.0 The folder name is set to version of
the .MSI file
Setup.exe
The downloader
The .MSI
prerequisites Pre-defined name None
The file name of the downloader is set to the name of your project. The downloader can be renamed only if you
don't use prerequisites.
Step #5 – Publishing
Just copy Version_info.xml and folders under the Publish folder to the web server (or to another location) to
make it available via the URL specified in the Installation URL field of the Publish dialog.
Add-in Express for IE and .NET Web-based Deployment and Update
page 51
On the Target PC
Installing
The user [downloads and] runs setup.exe, which installs prerequisites that were specified when creating the
installer. Note that depending on the IE extension type the user may be required to have the administrative
privileges; only IE Bar projects can be installed by a standard user. When the prerequisites are installed,
setup.exe downloads and runs the downloader. The downloader opens the following window illustrating the
progress of downloading the .MSI file:
Note that the Icon File field in the Publish dialog (see Step #1 – Publish Dialog) defines the icon for this window.
When the .MSI is downloaded, the downloader runs it and if the "Quiet mode during install" flag (see Step #3 -
Preferences) is cleared, the .MSI installer shows its GUI. When the setup process is complete, the downloader
closes its window.
Updating: Developer’s Perspective
You must provide a way for the user to invoke CheckForUpdates. Any control such as a main menu item,
toolbar button, etc. will do. In the code of the corresponding event handler, you must call the
CheckForUpdates method of your module (IEModule, IEBarModule, IEToolbarModule).
CheckForUpdates downloads and parses version_info.xml using the URL specified in the Installation URL field
at Step #1 – Publish Dialog. If version_info.xml contains several updates, CheckForUpdates will return the
URL for the most recent add-on version (the one that has the highest version number). The URL to return is
determined as follows:
If a web page was specified in Step #3 - Preferences, CheckForUpdates returns the URL of the web
page.
If the "Create setup program…" flag was set in Step #2 – Prerequisites, CheckForUpdates returns the
URL of the corresponding setup.exe.
Otherwise, CheckForUpdates returns the URL of the downloader for the update.
In all other circumstances, CheckForUpdates returns an empty string.
Before you start the process, you need to know if the current user has appropriate privileges for uninstalling the
current add-on version (and installing the new add-on version): call the IsUpdatable method of your module.
The following table describes the return values of the method.
Add-in Express for IE and .NET Web-based Deployment and Update
page 52
Environment The value returned by IsUpdatable
IE Bar project on Windows XP True
All other project types on Windows XP False if the user is a standard user; True if the user
is an administrator
Any project type on Windows Vista and Windows 7 True
You can also use IsNetworkDeployed (a method of your module) to check if the current add-on version was
deployed via the web.
Before starting the process, you may also want to warn the user that it will require closing all instances of
Internet Explorer.
Finally, you call IEApp.Navigate providing the appropriate URL as a parameter.
Updating: User’s Perspective
Setup.exe installs prerequisites, downloads the corresponding downloader and starts it. The downloader
uninstalls the current add-on version, requests the user to close all IE instances, downloads the .MSI file and
starts it. When the .MSI is installed (or when the installation process fails), the downloader closes.
Uninstalling
Uninstall the add-on in the usual way, via Control Panel.
Add-in Express for IE and .NET Add-in Express Tips and Notes
page 53
Add-in Express Tips and Notes
Common stuff
What are interop assemblies?
Interop Assemblies provide the compiler with early-binding information on the host application objects, their
properties, and methods. All IE versions are almost 100% backward compatible and you can use interops from
IE6 to work with IE7 and IE8. Note, in this case, you can access IE7 features using late binding (see the
InvokeMember method in MSDN). Obviously, you cannot expect an add-on developed with, say, IE7 interops
to work with IE6 because IE6 does not have some events and properties introduced in IE7.
Deploying and Debugging
Debugging
Specify the path to iexplore.exe in the Start external program field on the Debug tab of your project properties.
Specify an URL in Command line arguments, for instance, "about:blank". Close IE and run your project.
Deploying – Shadow Copy
The Add-in Express loader uses the ShadowCopy-related properties and methods of the AppDomain class.
When you run your add-on, IE loads the Add-in Express loader DLL referenced in the registry. The loader does
the following:
It finds your add-on DLLs in the DLL Cache. If there are no add-on DLLs in the cache, it copies all
assemblies to the cache (including dependencies). The cache folder is located in C:\Documents and
Settings\<user name>\Local Settings\Application Data\assembly\dl<number>. If all add-on DLLs (including
dependencies) already exist in the cache, it compares their versions. If the versions are not the same, it
copies new DLLs to the cache.
It loads the add-on DLLs from the cache.
You can see how the add-on versioning influences the add-on loading.
This approach (it is built into .NET, as you can see) allows replacing add-on DLLs when the add-on is loaded.
The disadvantage is numerous files located in the cache. As far as we know, Microsoft doesn't provide a solution
for this problem. You may think you can remove these files in an add-on‟s uninstall custom action. However, this
will remove the files from the current profile only.
Add-in Express for IE and .NET Add-in Express Tips and Notes
page 54
How Do I Find the PublicKeyToken of My Add-in?
It can be found in the setup project (that must be already built) - click on your add-in primary output in the setup
project and, in the Properties window, expand the KeyOutput property and see the PublicKeyToken property
value.
Deploying Localized IE Add-ons
IE add-ons are localizable in the same way as any Windows Forms application. But pay attention to the
deployment of localized resources – see http://msdn.microsoft.com/en-us/library/y99d1cd3(VS.80).aspx.
Version_info.xml
Version_info.xml contains information about add-on versions available for installation. It may resemble the
following:
<?xml version="1.0" encoding="utf-8"?>
<application name="myaddon">
<product language="1033">
<version name="1.0.0" installationUrl="http://127.0.0.1/myaddon/"
productCode="{8D0C0293-D91D-40A4-AC5F-5DC640E7784A}" updateType="bootstrapper">
<files bootstrapper="MyAddonSetup">
<file>myaddonsetup.msi</file>
</files>
<preferences>
<showInstallUI>true</showInstallUI>
<showUninstallUI>false</showUninstallUI>
<webPage>
</webPage>
</preferences>
</version>
</product>
</application>
Finally
If your questions are not answered here, please see the HOWTOs section on www.add-in-express.com. We
update these pages regularly.
