Searching for a Single Asset

Frequently, we will know precisely which asset we need. It could be a hard-coded reference, a reference input by the user, a reference retrieved from the database, or a reference to an asset related to something in the current context. However, searching for an asset that doesn't exist (or can't be found), is not visible in the current publishing mode, or the user doesn't have sufficient rights to view will return a null reference. Since CMS doesn't require the use of unique names when we are creating assets, it is possible to make a request for more than one asset with the same name. Ambiguous searches also result in a null reference.

The GetByGuid method is the most efficient search, and an asset's GUID is always unique (even historically). Since CMS doesn't require the use of unique names when we are creating assets, the path and URL are not guaranteed to resolve to a unique asset. An asset's GUID does not change if the object is moved to a different container in the hierarchy. If possible, GetByGuid should be used instead of the GetByPath or GetByUrl methods.

Returning a Single Asset

The following sections cover how the GetByGuid, GetByPath, and GetByUrl methods can be used to return a single asset.

GetByGuid

Since our Scratchpad (see the Scratchpad sidebar in Chapter 24 for details) has only a limited set of assets at this point, the first Searches example is something of a self-fulfilling prophecy. It does demonstrate that we can search for an asset given that we know its GUID and that GUIDs are assigned to all assets we create. We will be searching for a posting, but we could just as easily search for a channel, a template, a template gallery, a resource, or a resource gallery. We only need to know the GUID of the asset we want, and GUID is an available read-only property on all assets. Be aware, the GUID string must include braces, hyphens, 32 characters grouped in five alphanumeric sections (8-4-4-4-12), and generally uses the following format: { xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}.

Replace the Button1_Click function of our Scratchpad template file with the following code:

 private void Button1_Click(object sender, System.EventArgs e) {   //1. Grab the current CMS Context   CmsHttpContext cmsContext = CmsHttpContext.Current;   //2. Find this Posting using the Context current Posting's GUID   //   We must cast the result of a Searches object as a Posting   Posting cmsPostingFound =     cmsContext.Searches.GetByGuid(cmsContext.Posting.Guid)     as Posting;   //3. Check if Posting was found   if(cmsPostingFound != null)   {     //4. Check if the current Posting is equal to Posting found     if(cmsContext.Posting.Equals(cmsPostingFound))     {       //5. Assign the display name of the Posting       Label1.Text = "<b>Posting Found by GUID:</b> " +         cmsPostingFound.Path.ToString();     }   } } 

The second line of code actually does the search. It looks for a CMS asset that has the same GUID as the current Posting object, casts the object search result as a Posting object, and assigns it to a variable called cmsPostingFound, which is declared as a Posting object. We are referencing the current Posting object's GUID so we can be sure that the formatting of the GUID will be correct, but this value is just a string and can be provided in many other ways.

Build the solution and then refresh the Scratchpad posting in Internet Explorer, or browse to it and click the Button. The page should reload and look similar to Figure 28-1.

Figure 28-1. Find current posting Searches example

GetByPath

Locating an asset with the GetByPath method is very similar to using the GetByGuid method. In fact, we will only alter the second line in the code from our first example. However, there are several factors to consider when using this method. GetByPath is less efficient than GetByGuid and may degrade site performance. Unlike with GetByGuid, if an asset is moved to a different container in the hierarchy (the path changes), the search will no longer find the asset. It is also possible to make a request that has an ambiguous search result (two assets with exactly the same path), resulting in a null reference.

This method requires us to provide a root relative or absolute path to an asset; relative paths will result in an exception. An asset's path always begins with a slash mark (the root), followed by the containers it is in (if any) separated by slash marks (/), and ending with its name. Containers can optionally contain a slash mark at the end of the path. So, as we saw in the result of the first example, the path to our Scratchpad posting should be /Channels/Scratch/Scratchpad. If we were just looking for the channel, we could use either /Channels/Scratch or /Channels/Scratch/.

Note that the user only needs read rights to the requested asset for Searches to find it. Assets that the asset itself contains may not be available to the user.

If an invalid path string is given, an exception will result.

Replace the Button1_Click function of our Scratchpad template file with the following code:

 private void Button1_Click(object sender, System.EventArgs e) {   //1. Grab the current CMS Context   CmsHttpContext cmsContext = CmsHttpContext.Current;   //2. Find this Posting using the Context current Posting's Path   //   We must cast the result of a Searches object as a Posting   Posting cmsPostingFound =     cmsContext.Searches.GetByPath(cmsContext.Posting.Path)     as Posting;   //3. Check if Posting was found   if(cmsPostingFound != null)   {     //4. Check if the current Posting is equal to the Posting found     if(cmsContext.Posting.Equals(cmsPostingFound))     {       //5. Assign the display name of the Posting       Label1.Text = "<b>Posting Found By Search Path:</b> " +         cmsPostingFound.Path.ToString();     }   } } 

Yeah, that was like cheating. Replacing line 2 with either of the following code snippets should also yield the same result:

 Posting cmsPostingFound =   cmsContext.Searches.GetByPath("/Channels/Scratch/Pad")   as Posting; 

or let the user type the path into the TextBox:

 Posting cmsPostingFound =   cmsContext.Searches.GetByPath(TextBox1.Text.ToString())   as Posting; 

Build the solution and then refresh the Scratchpad posting in Internet Explorer, or browse to it and click the Button. The page should reload and look the same as Figure 28-1. We just arrived at the same Posting object that was returned using a different Searches method.

GetByUrl

The GetByUrl method can only retrieve URL-based assets: Posting objects and Channel objects. CMS can reference these assets using two different types of URLs.

• Hierarchical URLs: The hierarchical URL to our Scratchpad posting looks like this: /Scratch/Scratchpad.htm. The possibility of using short, simple URLs is a differentiator for CMS in the marketplace. Most CMS systems require long URLs that are very difficult for users to type and remember. Note the use of the ".htm" suffix in the URL. Since our template is an ASPX page and the posting content is in a SQL Server database, when the request is made of IIS, the CMS ISAPI filter is working behind the scenes to transform this hierarchical URL into the GUID-based QueryString we see in the address bar of the browser when the posting it represents is rendered.

• GUID-based URLs: The GUID-based URL to our Scratchpad posting looks something like this: /NR/exeres/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. Of course, the actual alphanumeric values of the GUID would be used instead of the x's shown here. The braces that were required in formatting the GUID for retrieval using the GetByGuid method are noticeably absent.

It is evident why this method is not very efficient and only intended to be used by search engines and site-indexing software. URLs must be resolved by the CMS engine before the assets can be retrieved. Hence, as you might expect, hierarchical URLs can only return a Channel object or a Posting object that is in a Published state, whereas GUID-based URLs can return a Channel object or a Posting object regardless of its publishing state. It is also probably evident that GetByGuid and GetByPath can retrieve some assets that GetByUrl can't. To get a template, a template gallery, a resource, or a resource gallery, we must use a Searches method other than GetByUrl.

Replace the Button1_Click function of our Scratchpad template file with the following code:

 private void Button1_Click(object sender, System.EventArgs e) {   //1. Grab the current CMS Context   CmsHttpContext cmsContext = CmsHttpContext.Current;   //2. Find this Posting using the Context current Posting's URL   //   We must cast the result of a Searches object as a Posting   Posting cmsPostingFound =     cmsContext.Searches.GetByUrl(cmsContext.Posting.Url)     as Posting;   //3. Check if Posting was found   if(cmsPostingFound != null)   {     //4. Check if the current Posting is equal to Posting found     if(cmsContext.Posting.Equals(cmsPostingFound))     {       //5. Assign the display name of the Posting       Label1.Text = "<b>Posting Found by URL:</b> " +         cmsPostingFound.Path.ToString();     }   } } 

Replacing line 2 with either of the following code snippets should also yield the same result:

 //Hierarchical URL   Posting cmsPostingFound =     cmsContext.Searches.GetByUrl("/Scratch/pad.htm")     as Posting; 

or:

 //GUID-based URL (use the actual URL for your Scratchpad posting)   Posting cmsPostingFound =     cmsContext.Searches.GetByUrl(       "/NR/exeres/D8D8026A-8F0B-4804-BBC6-69387182BEA3")     as Posting; 

Build the solution and then refresh the Scratchpad posting in Internet Explorer, or browse to it and click the Button. The page should reload and look the same as Figure 28-1. Again, we just arrived at the same Posting object that was returned using a different Searches method.