---
title: "Build item and media URLs"
slug: "build-item-and-media-urls"
abstract: "Use an API to build URLs for items and media items."
---
# Build item and media URLs

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:

```text
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.<br><br>> [!note]<br>> Language embedding set as described here is overruled by the language embedding configuration selected in the [site settings](https://doc.sitecore.com/xmc/en/users/xm-cloud/en/manage-sites.html#UUID-573cc3fc-ab88-ce55-c2c1-73acef232445_section-idm234507300031205). |
| `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:

```csharp
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:

```text
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&amp;h=300&amp;w=200`:

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

```