Ask Learn
Preview
Ask Learn is an AI assistant that can answer questions, clarify concepts, and define terms using trusted Microsoft documentation.
Please sign in to use Ask Learn.
Sign inThis browser is no longer supported.
Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support.
Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
[This documentation is preliminary and is subject to change.]
Describes Windows 7 how to create an OpenSearch Description (.osdx) file to connect external data stores to the Windows Client via the OpenSearch protocol. Federated search allows users to search a remote data store, and view the results from within Microsoft Windows Explorer.
This topic contains the following sections:
An OpenSearch Description (.osd) file for Windows federated search must abide by the following rules:
ShortName
element value (recommended)The following sample .osdx file consists of ShortName
and Url
elements, which are the minimum required child elements.
<OpenSearchDescription xmlns="https://a9.com/-/spec/opensearch/1.1/">
<ShortName>My Web Service</ShortName>
<Url format="application/rss+xml" template="https://example.com/rss.php?query={searchTerms}&start={startIndex}&cnt={count}" />
</OpenSearchDescription>
In addition to the minimum child elements, Windows federated search supports the following standard elements.
Windows uses the ShortName
element value to name the .searchconnector-ms (search connector) file that is created when the user opens the .osdx file. Windows ensures that the generated file name uses only characters allowed for Windows file names. If no ShortName
value is provided, then the .searchconnector-ms file attempts to use the file name of the .osdx file instead.
<OpenSearchDescription xmlns="https://a9.com/-/spec/opensearch/1.1/">
<ShortName>My Web Service</ShortName>
...
</OpenSearchDescription>
Windows uses the Description
element value to populate the file description shown in the Windows Explorer details pane when a user selects a .searchconnector-ms file.
<OpenSearchDescription xmlns="https://a9.com/-/spec/opensearch/1.1/">
...
<Description>Searches the example company book catalog</Description>
</OpenSearchDescription>
The .osdx file must include one Url
element and template
attribute (a Url template) that returns results in either RSS or Atom format. The format attribute must be set to application/rss+xml
for RSS formatted results, or application/atom+xml
for Atom formatted results.
<OpenSearchDescription xmlns="https://a9.com/-/spec/opensearch/1.1/">
...
<Url format="application/rss+xml" template="https://example.com/rss.php?query={searchTerms}&start={startIndex}&cnt={count}" />
</OpenSearchDescription>
If there is a version of the search results that can be viewed in a Web browser, then you should provide a Url format="text/html"
element, and template
attribute.
<<OpenSearchDescription xmlns="https://a9.com/-/spec/opensearch/1.1/">
...
<Url format="text/html" template="https://example.com/html.php?query={searchTerms}" />
</OpenSearchDescription>
If you provide a Url format="text/html"
element and template
attribute, then a button appears in the Windows Explorer command bar that allows the user to open a Web browser to view the search results when the user performs a query.
The roll-over of the query back to the data store's Web UI is important in some scenarios. For example, a user may want to view more than 100 results (the default number of items the OpenSearch provider requests). If so, then the user may also want to use search features only available on the data store's Web site, such as re-querying with a different sort order, or pivoting and filtering the query with related metadata.
The OpenSearch provider performs the following actions:
Supported Token | How Used by OpenSearch Provider |
---|---|
{searchTerms} | Replaced with the search terms the user types in the Windows Explorer search input box |
{startIndex} | Used when getting results in "pages" Replaced with the index for the first result item to return |
{startPage} | Used when getting results in "pages" Replaced with the page number of the set of search results to return |
{count} | Used when getting results in "pages" Replaced with the number of search results per page that Windows Explorer requests |
{language} | Replaced with a string that indicates the language of the query being sent |
{inputEncoding} | Replaced with a string (such "UTF-16") that indicates the character encoding of the query being sent |
{outputEncoding} | Replaced with a string (such as "UTF-16") that indicates the desired character encoding for the response from the Web service |
You may want to limit the number of results returned per request. You can opt to return a "page" of results at a time, or have the OpenSearch provider get additional pages of results either by item number or page number. For example, if you send twenty results per page, the first page you send starts at item index 1 and at page 1; the second page you send starts at item index 21 and at page 2. You can define how you want the OpenSearch provider to request items by either using the {startItem}
or the {startPage}
token in the URL template.
An item index identifies the first result item in a page of results. If you want clients to send requests using an item index, you can use the {startIndex}
token in your URL template attribute, as follows:
<Url format="application/rss+xml" template="https://example.com/rss.php?query={searchTerms}&start={startIndex}" />
The OpenSearch provider then replaces the token in the URL with a starting index value. The first request starts with the first item, as shown in the following example:
https://example.com/rss.php?query=frogs&start=1
The OpenSearch provider can get additional items by changing the {startIndex}
parameter value and issuing a new request. The provider repeats this process until it gets enough results to satisfy its limit, or reaches the end of the results. The OpenSearch provider looks at the number of items returned by the Web service in the first page of results, and sets the expected page size to that number. It uses that number to increment the {startIndex}
value for subsequent requests. For example, if the Web service returns 20 results in the first request, then the provider sets the expected page size to 20. For the next request, the provider replaces {startIndex}
with the value of 21 to get the next 20 items.
Note If a page of results returned by the Web service has fewer items than the expected page size, then the OpenSearch provider assumes it has received the last page of results and stops making requests.
A page index identifies the specified page of results. If you want clients to send requests using a page number, you can use the {startPage}
token in your URL element template attribute, as follows:
<Url format="application/rss+xml" template="https://example.com/rss.php?query={searchTerms}&page={startPage}" />
The OpenSearch provider then replaces the token in the URL with a page number parameter. The first request starts with the first page, as shown in the following example:
https://example.com/rss.php?query=frogs&page=1
Note If a page of results returned by the Web service has fewer items than the expected page size, then the OpenSearch provider assumes it has received the last page of results and stops making requests.
You may want to configure your Web service to permit a request to specify the size of the pages using some parameter in the URL. A request must be specified in the .osdx file using the {count}
token, as follows:
<Url format="application/rss+xml" template="https://example.com/rss.php?query={searchTerms}&start={startIndex}&cnt={count}" />
The OpenSearch provider can then set the desired page size, in terms of number of results per page, as shown in the following example:
https://example.com/rss.php?query=frogs&start=1&cnt=50
By default the OpenSearch provider makes requests using a page size of 50. If you want a different page size, then do not provide a {count}
token, and instead place the desired number directly in the URL template.
The OpenSearch provider determines the page size based on the number of results returned on the first request. If the first page of results received has fewer items than the count requested, then the provider resets the page size for any subsequent page requests. If subsequent page requests return fewer items, then the OpenSearch provider assumes that it has reached the end of the results.
In addition to the standard elements, Windows federated search supports the following extended elements:
Because these extended child elements are not supported in the OpenSearch v1.1 specification, they must be added using this namespace:
https://schemas.microsoft.com/opensearchext/2009/
By default Search Connectors only get up to 100 results for any given user query. This limit can be customized by including the MaximumResultCount
element within the OSD file as shown in the following example:
<OpenSearchDescription xmlns="https://a9.com/-/spec/opensearch/1.1/" xmlns:ms-ose="https://schemas.microsoft.com/opensearchext/2009/">
...
<ms-ose:MaximumResultCount>200</ms-ose:MaximumResultCount>
</OpenSearchDescription>
The above example declares the namespace prefix ms-ose
in the top-level OpenSearch Description
element, and then uses it to prefix the element name. This declaration is mandatory because MaximumResultCount
is not supported in the OpenSearch v1.1 specification.
When results are returned by the Web service as an RSS or Atom feed, the OpenSearch provider must map the item metadata in the feeds to properties that the Windows Shell can use. The following figure illustrates how the OpenSearch provider maps some of the default RSS elements.
The default mappings of RSS XML elements to Windows Shell system properties, are listed in the following table. XML paths are relative to the item element. The "media:"
prefix is defined by the Yahoo Search Namespace namespace.
RSS XML Path | Windows Shell Property (Canonical Name) |
---|---|
Link | System.ItemUrl |
Title | System.ItemName |
Author | System.Author |
pubDate | System.DateModified |
Description | System.AutoSummary |
Category | System.Keywords |
enclosure/@type | System.MIMEType |
enclosure/@length | System.Size |
enclosure/@url | System.ContentUrl |
media:category | System.Keywords |
media:content/@fileSize | System.Size |
media:content/@type | System.MIMEType |
media:content/@url | System.ContentUrl |
media:group/content/@fileSize | System.Size |
media:group/content/@type | System.MIMEType |
media:group/content/@url | System.ContentUrl |
media:thumbnail/@url | System.ItemThumbnailUrl |
Note In addition to the default mappings of standard RSS or Atom elements, you can map other Windows Shell system properties by including additional XML elements in the Windows namespace for each of the properties. You can also map elements from other existing XML namespaces such as MediaRSS, Itunes, and so forth, by adding custom property mapping in the .osdx file.
You can choose to include other XML elements within the items in your RSS feed that automatically map to Windows Shell system properties. To do so, include an element named after the Windows Shell property and prefixed with the Windows Shell system namespace. The following example illustrated the namespace declaration win=" https://schemas.microsoft.com/windows/2008/propertynamespace"
, and the inclusion of an element for the property mapping win:System.Contact.PrimaryEmailAddress
:
<rss version="2.0" xmlns:example="https://example.com/schema/2009" xmlns:win="https://schemas.microsoft.com/windows/2008/propertynamespace">
...
<item>
<title>Bill Gates</title>
<win:System.Contact.PrimaryEmailAddress>billg@microsoft.com
</win:System.Contact.PrimaryEmailAddress>
</item>
The namespace prefix used here ("win"
) is a suggestion; you can use any prefix. However, you must use the exact Windows Shell property names, and must include the exact URI:
https://schemas.microsoft.com/windows/2008/propertynamespace
About Windows Shell System Properties
There is a complete list of System Properties defined in Windows, and the value type format required for each property. The documentation for the System.FileExtension Window Shell property, for example, specifies that the value must contain the leading period (".docx" and not "docx").
Date and Time Values
The preferred date and time format is ISO-8601, for example:
2008-01-16T 19:20:30:.45+01:00
.NET developers should use the DateTime class with ToString("R")
to output the correct format.
You can customize the mapping of elements from your RSS output to Windows Shell system properties by specifying the mapping in the .osdx file.
The RSS output specifies:
The .osdx file identifies a Windows Shell property for each element name in a namespace. The property mappings that you define in your .osdx file override the default mappings, if they exist, for those specified properties.
This example RSS output identifies https://example.com/schema/2009
as the XML namespace with the prefix example. This prefix must appear again before the element email.
<rss version="2.0" xmlns:example="https://example.com/schema/2009">
...
<item>
<title>Bill Gates</title>
<example:email>billg@microsoft.com</example:email>
</item>
In the following sample .osdx file the XML element email maps to the Windows Shell property System.Contact.EmailAddress.
<OpenSearchDescription xmlns="https://a9.com/-/spec/opensearch/1.1/" xmlns:ms-ose="https://schemas.microsoft.com/opensearchext/2009/">
...
<ms-ose:ResultsProcessing format="application/rss+xml">
<ms-ose:PropertyMapList>
<ms-ose:PropertyMap sourceNamespaceURI="https://example.com/schema/2009/" >
<ms-ose:Source path="email">
<ms-ose:Property schema="https://schemas.microsoft.com/windows/2008/propertynamespace" name="System.Contact.EmailAddress" />
</ms-ose:Source>
</ms-ose:PropertyMap>
</ms-ose:PropertyMapList>
</ms-ose:ResultsProcessing>
...
</OpenSearchDescription>
There are some properties that cannot be mapped because values for them are either overridden later or not edit able. For example System.ItemFolderPathDisplay or System.ItemPathDisplayNarrow cannot be mapped because they are calculated from the URL value provided in either the link or enclosure elements.
Thumbnail image URLs may be provided for any item using the media:thumbnail url=""
element. The ideal resolution is 150x150 pixels. The largest thumbnails supported are 256x256 pixels. Providing larger images takes more bandwidth for no extra benefit to the user.
Windows provides a shortcut menu named Open file location for result items. If the user selects that menu item, the "parent" URL for the selected item is opened. If the URL is a Web URL, such as https://..., such as the Web browser is opened and navigated to that URL. Your feed should provide a custom URL for each item to ensure that Windows opens a valid URL. This can be accomplished by including the URL within an element inside the item's XML, as illustrated in the following example:
<rss version="2.0" xmlns:example="https://example.com/schema/2009" xmlns:win="https://schemas.microsoft.com/windows/2008/propertynamespace">
...
<item>
<title>Bill Gates</title>
<link>https://example.com/pictures.aspx?id=01</link>
<win:System.ItemFolderPathDisplay>https://example.com/pictures_list.aspx
</win:System.ItemFolderPathDisplay>
</item>
...
If this property is not explicitly set in the item's XML, then the OpenSearch provider sets it to the parent folder of the URL of the item. In the example above, the OpenSearch provider would have used the link value, and set the System.ItemFolderPathDisplay Windows Shell property value to "https://example.com/"
.
Some Windows Explorer view layouts are defined by property description lists, or proplists. A proplist is a semicolon-delimited list of properties, such as "prop:System.ItemName; System.Author"
, that is used to control how your results appear in Windows Explorer.
The UI areas of Windows Explorer that can be customized using proplists are illustrated in the following figure:
Each area of Windows Explorer has an associated set of proplists, which themselves are specified as properties. You can specify custom proplists for individual items in your result sets or for all items in a set of results.
UI Area to Customize | Windows Shell property that Implements the Customization |
---|---|
Content view mode (when searching) | System.Proplist.ContentViewModeForSearch |
Content view mode (when browsing) | System.Proplist.ContentViewModeForBrowse |
Tile view mode | System.Proplist.TileInfo |
Details pane | System.Proplist.PreviewDetails |
Infotip (item's hover tool tip) | System.Proplist.Infotip |
To specify a unique proplist for an individual item:
In your RSS output, add a custom element representing the proplist you want to customize. For example, this sample sets the list for the details pane:
<win:System.Proplist.PreviewDetails>prop:System.ItemName;System.Author</win:System.Proplist.PreviewDetails>
To apply a property to every item in the search results without modifying the RSS output, specify a proplist within a ms-ose:PropertyDefaultValues
element in the .osdx file:
<ms-ose:ResultsProcessing format="application/rss+xml">
<ms-ose:PropertyDefaultValues>
<ms-ose:Property schema="https://schemas.microsoft.com/windows/2008/propertynamespace" name="System.PropList.ContentViewModeForSearch">prop:~System.ItemNameDisplay;System.Photo.DateTaken;~System.ItemPathDisplay;~System.Search.AutoSummary;System.Size;System.Author;System.Keywords</ms-ose:Property>
</ms-ose:PropertyDefaultValues>
</ms-ose:ResultsProcessing>
The list of properties specified in the System.Proplist.ContentViewModeForSearch and System.Proplist.ContentViewModeForBrowse proplists determines what is shown in Content view mode. For more information about property lists, see PropList.
The properties are laid out according to the numbers shown in the following layout pattern:
If we use the following list of properties,
prop:~System.ItemNameDisplay;System.Author;System.ItemPathDisplay;~System.Search.AutoSummary;System.Size;System.Photo.DateTaken;System.Keywords
Then we see the following display:
Note For the best readability, the properties shown in the right-most column should be labeled.
Only one of the flags defined in the proplists documentation applies to the display of items in Content View mode layouts:"~"
. In the previous examples, the Explorer view labels some of the properties, such as Tags: animals; zoo; lion
. That is the default behavior when you specify a property in the list. For example, the proplist has "System.Author"
which is displayed formatted as "Authors: value"
. When you want to hide the property label, place a "~"
in front of the property name. For example, if the proplist has "~System.Size"
, the property is displayed as just a value, and without the label.
When the user selects a result item in Windows Explorer and the preview pane is open, the content of the item is previewed.
The content to show in the preview is specified by a URL, which is determined as follows:
It is possible to use a different URL for the preview than for the item itself. This means that if you provide different URLs for the link URL, and the enclosure or media:content URL
, Windows Explorer uses the link URL for previews of the item but uses the other URL for file type detection, opening, downloading, and so forth.
How Windows Explorer determines what URL to use:
When users right-click an item, the Open file location menu option appears. This command takes the user to the container for or location of that item. For example, on a SharePoint search, selecting this option for a file in a document library would open the document library root in the Web browser.
When a user clicks Open file location Windows Explorer attempts to find a parent container, as follows:
Ask Learn is an AI assistant that can answer questions, clarify concepts, and define terms using trusted Microsoft documentation.
Please sign in to use Ask Learn.
Sign in