Build item and media URLs

Abstract

Use an API to build URLs for items and media items.

You can build the URL Sitecore uses for an item programmatically, and can build URLs for both items and media this way. You control the way the API build the URLs by using the ItemUrlBuilderOptions and MediaUrlBuilderOptions classes for item and media items, respectively. You can control things like language embedding, absolute or relative path, using display name or item name, and more.

Build an item URL

The Sitecore.Abstractions.BaseLinkManager class provides a public API to render item URLs:

public abstract string GetItemUrl(Item item, ItemUrlBuilderOptions options);

where

Item is the item you generate a URL for.
ItemUrlBuilderOptions is the specification for generating the URL.

You use the ItemUrlBuilderOptions specification to control how Sitecore builds the URL. The class extends the Sitecore.Links.UrlBuilders.UrlBuilderOptions class that contains the common properties you use to control how Sitecore generates URLs for both items and media items.

The tables below describe the properties of these two classes.

The UrlBuilderOptions class

Property	Description
`bool? AlwaysIncludeServerUrl`	Specifies whether the server URL is always included.
`Language Language`	Specifies the language. The default is `Context.Language`.
`LanguageEmbedding? LanguageEmbedding`	Specifies if and how Sitecore embeds language in the URL.
`LanguageLocation? LanguageLocation`	Specifies if Sitecore puts the language in the URL path or a query string.
`bool? LowercaseUrls`	Specifies if Sitecore renders lowercase URL.
`bool? EncodeNames`	Specifies if Sitecore encodes names in the URL.
`bool? UseDisplayName`	Specifies if Sitecore uses the display name when it generates URL.

The ItemUrlBuilderOptions class

Property	Description
`bool? AddAspxExtension`	Specifies if Sitecore adds the `.apsx` extension to the URL.
`bool? SiteResolving`	Specifies if Sitecore enables site resolving.
`SiteContext Site`	Specifies the the site.
`bool? ShortenUrls`	Specifies if Sitecore shortens URLs.

The default Sitecore implementation of the BaseLinkManager class uses the Sitecore.Links.LinkProvider class. The LinkProvider class uses the ItemUrlBuilder class to generate item URLs. You can inject a custom URL builder by patching the <links/itemUrlBuilder> configuration node.

The ItemUrlBuilder class has a single constructor that takes one parameter of type DefaultItemUrlBuilderOptions, the specification used by Sitecore as a fallback for null or non-provided values of the ItemUrlBuilderOptions specification.

The DefaultItemUrlBuilderOptions parameter has the same set of properties as the ItemUrlBuilderOptions options, except that these properties cannot be null.

The following example shows how you can patch the configuration:

<!-- URL BUILDERS -->
    <links>
        <urlBuilder>
            <alwaysIncludeServerUrl>false</alwaysIncludeServerUrl>
            <languageEmbedding>asNeeded</languageEmbedding>
            <languageLocation>filePath</languageLocation>
            <lowercaseUrls>false</lowercaseUrls>
            <encodeNames>true</encodeNames>
            <useDisplayName>false</useDisplayName>
        </urlBuilder>
        <itemUrlBuilder type="Sitecore.Links.UrlBuilders.ItemUrlBuilder, Sitecore.Kernel">
            <param desc="defaultOptions" type="Sitecore.Links.UrlBuilders.DefaultItemUrlBuilderOptions, Sitecore.Kernel">
                <alwaysIncludeServerUrl ref="links/urlBuilder/alwaysIncludeServerUrl" />
                <languageEmbedding ref="links/urlBuilder/languageEmbedding" />
                <languageLocation ref="links/urlBuilder/languageLocation" />
                <lowercaseUrls ref="links/urlBuilder/lowercaseUrls" />
                <encodeNames ref="links/urlBuilder/encodeNames" />
                <useDisplayName ref="links/urlBuilder/useDisplayName" />
                <addAspxExtension>false</addAspxExtension>
                <siteResolving>true</siteResolving>
                <shortenUrls>true</shortenUrls>
            </param>
        </itemUrlBuilder>
    </links>

The following table describes the configuration nodes and the value of these nodes:

Configuration node	Value
`alwaysIncludeServerUrl`	Specifies if Sitecore always adds the current server URL to generated URLs. The default is `false`.
`languageEmbedding`	Specifies if Sitecore embeds the language name in the URLs it generates. The options are: `asNeeded` \| `always` \| `never`. The default is `asNeeded`.
`languageLocation`	Specifies if Sitecore puts the language in the URL path or a query string. The options are `filePath` \| `queryString`. The default is `filePath`.
`lowercaseUrls`	Specifies if Sitecore lowercases the URLs it generates. The default is `false`.
`encodeNames`	Specifies if Sitecore encodes the names in the URLs it generates. The default is `true`.
`useDisplayName`	Specifies if Sitecore uses the item display name. The default is `false`.
`addAspxExtension`	Specifies if Sitecore adds the `.aspx` extension to the URLs it generates. The default is `false`.
`siteResolving`	Specifies if Sitecore resolves site information when it renders item URLs. The default is `true`.
`shortenUrls`	Specifies if Sitecore shortens the URLs it generates. The default is `true`.

Example

If you have this item: /sitecore/content/home/sample item, and the item has English and Danish versions, then the following code will generate URLs similar to http://{HOST}/en/Sample Item for the English version and http://{HOST}/da/Sample Item for the Danish version:

linkManager.GetItemUrl(sampleItem, new ItemUrlBuilderOptions
                {
                    AlwaysIncludeServerUrl = true,
                    LanguageEmbedding = LanguageEmbedding.Always,
                    LanguageLocation = LanguageLocation.FilePath
                });

Build a media item URL

The Sitecore.Abstractions.BaseMediaManager class provides a public API to render media URLs:

public virtual string GetMediaUrl(MediaItem item, MediaUrlBuilderOptions options);

where

MediaItem is the media item you generate a URL for
MediaUrlBuilderOptions is the specification for generating the media URL.

You use the MediaUrlBuilderOptions specification to control the way Sitecore builds the URL. The class extends the Sitecore.Links.UrlBuilders.UrlBuilderOptions class that contains the common properties you use to control how Sitecore generates URLs for both items and media items.

The tables below describe the properties of these two classes.

The UrlBuilderOptions class

Property	Description
`bool? AlwaysIncludeServerUrl`	Specifies whether the server URL is always included.
`Language Language`	Specifies the language. The default is `Context.Language`.
`LanguageEmbedding? LanguageEmbedding`	Specifies if and how Sitecore embeds language in the URL.
`LanguageLocation? LanguageLocation`	Specifies if Sitecore puts the language in the URL path or a query string.
`bool? LowercaseUrls`	Specifies if Sitecore renders lowercase URL.
`bool? EncodeNames`	Specifies if Sitecore encodes names in the URL.
`bool? UseDisplayName`	Specifies if Sitecore uses the display name when it generates URL.

The MediaUrlBuilderOptions class

Property	Description
`bool? AbsolutePath`	Specifies if Sitecore renders a media link with an absolute path.
`bool? AllowStretch`	Specifies if Sitecore allows the media to be stretched as it is rendered.
`bool? AlwaysAppendRevision`	Specifies if Sitecore always appends the media item revision.
`bool? DisableBrowserCache`	Specifies if Sitecore sets a header values that prevents the browser from caching the media item.
`bool? DisableMediaCache`	Specifies if Sitecore sets a property that prevents the browser from caching the media item in the media cache.
`bool? IgnoreAspectRatio`	Specifies if Sitecore ignores the aspect ratio when resizing media.
`bool? IncludeExtension`	Specifies if Sitecore includes an extension in the URL. it generates.
`bool? Thumbnail`	Specifies if the media item is a thumbnail.
`bool? UseDefaultIcon`	Specifies if Sitecore uses the default icon for the media item.
`bool? UseItemPath`	Specifies if Sitecore uses the item path when it builds a media URL.
`int? Height`	Specifies the height of the media item.
`int? MaxHeight`	Specifies the maximum height of the media item.
`int? Width`	Specifies the width of the media item.
`int? MaxWidth`	Specifies the maximum width of the media item.
`float? Scale`	Specifies the scale of the media item.
`string DefaultIcon`	Specifies the default icon.
`string RequestExtension`	Specifies the request media extension.
`string VirtualFolder`	Specifies the virtual folder of the media item.
`string ItemRevision`	Specifies the item revision of the media item.
`Color? BackgroundColor`	Specifies the background color.

Example

If you have a media item: /sitecore/media library/Images/myImage, then the following code generates a URL similar to http://{HOST}/-/media/Images/myImage.ashx?bc=White&h=300&w=200:

mediaManager.GetMediaUrl(mediaItem, new MediaUrlBuilderOptions
                {
                    AlwaysIncludeServerUrl = true,
                    BackgroundColor = Color.White,
                    Height = 300,
                    Width = 200
                });