Sitecore Link Resolving: Multisites, Hostname Pipes, and Target Hostname

Sitecore provides the extremely useful ability to support multiple sites within the same Sitecore instance. This allows for a single solution to include subdomains as well as entirely different domains in addition to the primary website domain. Because multisites are within the same Sitecore instance, it is easy to add internal links to a page that point to one of the other sites. By default, Sitecore should be able to handle this easily. However, I recently encountered an issue where I discovered that cross-site URLs were not resolving correctly. I added a link on to a page on, but instead of resolving to, it resolved to; instead of using the microsite’s domain, it resolved the url as a path underneath the primary home node and included the microsite home node as part of the path. By default this URL does work, but my client didn’t want users to be using the incorrect path and had in fact recently requested that I add a redirect from to, so this needed to be fixed (also, it’s wrong).

This was a new issue. Links were resolving correctly before, so what changed? Well, it turns out that I had just recently added an additional hostname for the microsite, since my client was changing the domain of this site. I wanted to make both the old and new domains work until we had fully transitioned to the new domain, so instead of replacing the old domain in the web config with the new one, I added the new domain with a pipe:

hostName=”| ”

Sitecore is able to handle pipes in the hostname property. I made this change, saw that both and worked (after adding the binding in IIS of course), and thought that was that. However, it turns out that adding the pipe made it so that Sitecore couldn’t figure out which hostname to use when resolving cross-site links, so it stopped resolving them as and instead used the main website domain.

The simple solution is to just remove the pipe, which would fix the issue, but that’s not a good solution, since although I don’t actually need both hostnames anymore, there are situations in which multiple hostnames might be needed. The solution, then, is to add the targetHostName property:

<site name=”microsite_website” hostname=”|” targetHostName=”” />

Sitecore provides this explanation for the targetHostName property:

The host name to use when generating URLs to items within this site from the context of another site. If the targetHostName attribute is absent, Sitecore uses the value of the hostName attribute instead. Used only when the value of the Rendering.SiteResolving setting is true.

So, that explains why the pipe broke it; Sitecore was using the hostName property to generate URLs, but with multiple domains, the hostName property was not a valid URL.


Author: ericastockwellalpert

.NET Developer and Sitecore MVP 2019-2020

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s