Invoke applications directly in Internet Explorer

  • Article

The DirectInvoke feature in Internet Explorer on Windows 8 enables applications to register their MIME Types for direct invocation from a URL. When IE encounters a file type that it doesn't handle natively, it can use a handler application, rather than downloading the file.

Introduction

Using DirectInvoke, handler applications have control over how their files are downloaded and enables smart techniques specific to the application's requirements. For example, Microsoft Office maintains a local cache of documents on a user’s machine. When a user attempts to download a Office document in Windows Internet Explorer, DirectInvoke calls Office using the target URL, rather than downloading the file. Office checks its cache and only downloads the file if it isn't already in the cache. This behavior can provide significant bandwidth savings, especially when handling large, media-rich documents.

Requirements for DirectInvoke

DirectInvoke requires the following:

  • The handler application must register with the handle HTTP and Secure Hypertext Transfer Protocol (HTTPS)URLs.
  • In some cases, servers require additional context (cookies, sign-in information, and so on), which the handler application might not be able to supply.
  • Servers must send the X-MS-InvokeApp HTTP response header to declare that the file is downloadable by referencing the URL alone.
  • The handler application must be the default handler for that MIME type.
  • Windows prompts the user to launch the application.

DirectInvoke in action

When the user clicks on a file that has a DirectInvoke application associated with it, the following prompt is displayed.

or

The user has the option to either Open or Cancel, but not save the file using the browser itself. Clicking Open opens the file in the default application, and Cancel cancels the download. The user can save the file after it's been opened in the corresponding application.

Configure your server for DirectInvoke

Servers must send one of these HTTP response headers to opt-in to DirectInvoke.

Header Description
X-MS-InvokeApp: 1 The server is requesting that a DirectInvoke configured application be used.
X-MS-InvokeApp: 1; RequireReadOnly The server is requesting that a DirectInvoke configured application be used and requires that the file opens in read-only mode.

 

As a best practice, servers should include the correct MIME type of the file in the Content-Type HTTP response header. Any filename specified in the Content-Disposition HTTP response header is displayed in the consent dialog prompt for user approval, but not passed to the application.

Configure your application for DirectInvoke

The handler application must be set as the default for the MIME type in Windows. The handler application declares through the registry that it supports receipt of HTTP/HTTPSURLs.

Note  Applications in Windows app using JavaScript or Windows Store apps don't need to be registered, as they are registered and enabled by default.

 

The application can declare support using existing SupportedProtocols mechanism for its verbs. HKCR\Applications\<app.exe>\SupportedProtocols or HKCR\CLSID\<verb handler clsid>\SupportedProtocols can be populated using values that identify the Uniform Resource Identifier (URI) protocol schemes (such as mailto:\\ ) that the application supports or * to indicate all protocols.

For example, here's Windows Media Player’s verbs registration:

HKCR\CLSID\{45597c98-80f6-4549-84ff-752cf55e2d29}\SupportedProtocols
    rtspt    REG_SZ
    rtspu    REG_SZ
    rtsp    REG_SZ
    mms    REG_SZ
    http    REG_SZ

This register entry is the recommended approach to opt-in to DirectInvoke behavior. The application can also set the legacy UseURL registry key to indicate that the application can accept a URL on the command line as shown here:

HKEY_LOCAL_MACHINE or HKEY_CURRENT_USER
  SOFTWARE
    Microsoft
      Windows
        CurrentVersion
          App Paths
            file.exe
              (Default)
              UseUrl

How it works

The process starts when a user clicks a link to a file, and the browser navigates to that URL.

The server responds with several things in a header:

  • The MIME type of the file is specified using a Content-Type response header.
  • The server requests that the client directly invokes the default application using the X-MS-InvokeApp: 1 or X-MS-InvokeApp: 1; RequireReadOnly response headers.

On the client side, IE detects that DirectInvoke is requested by the response header. IE determines the default handler application for the MIME type on the user’s system by examining shell registration. If the application is registered to support DirectInvoke behavior, IE prompts the user for permission to open the file using the default application.

If the user clicks Open, IE uses ShellExecute to start the registered application and pass the URL. The application will start using its default verb unless RequireReadOnly is specified to open the file as read only.

If the DirectInvoke conditions aren't met, IE falls back depending on the environment. In Internet Explorer for the desktop, if a legacy MIME handler exists, it will be used to open the file. If a link is clicked in Internet Explorer in the new Windows UI, the file is downloaded.

Handling header conflicts

The content-disposition: attachment HTTP response header can be in conflict with an InvokeApp header. We recommend that servers send only one of these headers. In the event of a conflict, the content-disposition header has priority over the InvokeApp header. This is because the historical intent of the content-disposition header is to bypass any special MIME handling and offer the file for download.

Creating a link to your app

Windows 8 integration