I'm a fan of strong typing in .NET as you gain compile time validation of code, Visual Studio Intellisense support, not to mention less mucking around with type conversion or dealing with (usually inconsistently) entering strings for page names and configuration setting keys inline. Visual Studio provides intellisense and some degree of validation for pages (i.e. urls) within a project when using Design Mode, but using those urls in code, e.g..
you're out of luck as there isn't any validation unless you write it yourself.
Perhaps a better syntax is to access urls within your project from a property somewhere, like so:
This way, we reference a static variable or constant to retrieve the url we want to redirect the browser to. If the variable is spelt wrong, the project won't compile and we can fix the error. Being a member within the project means we're provided with intellisense support as well.
However, maintaining variables or constants for your pages can be tedious. If you change the name of a page from "MyPage.aspx" to "MyMovedPage.aspx" the actual value of the variable "MyDir_MyPage" would also need to be updated. Once again, unless you have some automated tests to validate the page exists, the project will compile, but the if you forgot to update the reference, you'll get the wrong url.
To get around these limitations, and to help lessen the maintenance within your project, we can use a build provider to generate a static class containing all the page's in our project. Once that's done, we get:
So now we'll be able to use the following code, and know that if we change something, we'll get notified when when we build if something is amis.
We'll look at the code for the build provider a little later, first lets look at what it will generate.
Using the previous example, the code the build provider generates looks something along the lines of...
Once we've added the assembly reference to our project, we can add the relevant configuration information to the web.config.
Here I've chosen to associate files with the ".hrefs" extension with my HrefBuildProvider. You could easily choose another extension, as it's simply a mapping for a file extension found within the App_Code folder and the build provider.
Now we can create a file with that extension in the App_Code folder (let's use "Site.hrefs" for now, but you could use any name. You could even have multiple .hrefs files with different class names, one for aspx pages, another for your images, javascript and css files :), and add the following configuration - then tailor to suit your preferences.
Apart from the juicy code, which is coming next, that's it. Now you'll have intellisense for your file locations and compile time checking. It's worth noting that the generated class from the build provider will regenerate when the .hrefs file is modified, or you rebuild. If you want to see the generated class (it's stored in the "Temporary ASP.NET Files" folder), I'd suggest simply to right click on "Href" from your code, and choose, "Go to definition" - it will bring up the temporary file for you to peruse.
Rather than walking through the step by step of creating a build provider, I'll just point you to a couple of other articles on the subject if you wish to learn more, then I can just display the fully commented source code for the class below :)
using System;
using System.CodeDom;
using System.Collections.Generic;
using System.IO;
using System.Text.RegularExpressions;
using System.Web.Compilation;
using System.Web.Hosting;
using System.Xml;
namespace CSharpVitamins.Compilation
{
/// <summary>
/// Generates a static class for urls within an ASP.NET project
/// </summary>
public class HrefBuildProvider : BuildProvider
{
#region Fields
/// <summary>
/// Path to the web root for determining urls within the site
/// </summary>
string _basePath;
/// <summary>
/// Whether to convert urls to lowercase - based on your preference
/// </summary>
bool _useLowerCaseUrls;
/// <summary>
/// Whether to include the extension of the file in the name
/// of the member
/// </summary>
bool _includeExtension;
/// <summary>
/// Whether to create the root class as 'partial', allowing
/// additional members to be added to the resultant class.
/// </summary>
bool _makePartial;
/// <summary>
/// Maximum recurring depth for the project - 1 for top level,
/// 2 for first level of subfolders etc...
/// </summary>
int _maxDepth = 100;
/// <summary>
/// Namespace the generated class will be placed within.
/// Leave empty to add to the global namespace e.g. global::Href
/// </summary>
string _namespace;
/// <summary>
/// The name of the main class e.g. Href
/// </summary>
string _className;
/// <summary>
/// Current depth of recursion
/// </summary>
int _depth = 0;
/// <summary>
/// Predicate to determine if a file should be included
/// </summary>
Predicate<FileSystemInfo> isValidFile;
/// <summary>
/// Predicate to determine if a folder should be included
/// </summary>
Predicate<FileSystemInfo> isValidFolder;
#endregion
#region GenerateCode
/// <summary>
/// Initialises settings from the BuildProvider file, and
/// generates the appropriate code.
/// </summary>
/// <param name="assemblyBuilder"></param>
public override void GenerateCode(AssemblyBuilder assemblyBuilder)
{
// init settings from xml source file
init();
// create root class e.g. global::Href
CodeTypeDeclaration root = createStaticClass(_className, _makePartial);
addSummary(root, "Provides access to urls within the project.");
build(new DirectoryInfo(_basePath), root);
CodeNamespace ns = new CodeNamespace();
ns.Types.Add(root);
// leave blank for global::namespace
if (!string.IsNullOrEmpty(_namespace))
ns.Name = _namespace;
CodeCompileUnit unit = new CodeCompileUnit();
unit.Namespaces.Add(ns);
assemblyBuilder.AddCodeCompileUnit(this, unit);
}
#endregion
#region build
/// <summary>
/// Iterates over the given directory, adding the files as members to
/// the parent type, then recurse down the folder tree until the max
/// depth is reached.
/// </summary>
/// <param name="dir">The directory to process</param>
/// <param name="parent">Parent class to add members too.</param>
void build(DirectoryInfo dir, CodeTypeDeclaration parent)
{
if (_depth >= _maxDepth)
return;
++_depth;
/// 'members' keeps a record of the number of times a
/// member name is repeated within the parent type/class.
/// Pass this to 'ensureUniqueMemberName' to get the name
/// with an index number appended to the end e.g. the second
/// occurrence of "MyProperty" becomes "MyProperty1"
Dictionary<string, int> members = new Dictionary<string, int>();
///
/// process files:
/// iterate over files and add the member
/// public const string MyfileName = "~/myfileName.aspx";
///
FileInfo[] files = dir.GetFiles();
foreach (FileInfo file in files)
{
if (isValidFile(file))
{
CodeMemberField field = new CodeMemberField();
field.Name = getName(file);
field.Type = new CodeTypeReference(typeof(string));
field.Attributes = MemberAttributes.Public | MemberAttributes.Const;
field.InitExpression = getInitExpression(getUrl(file));
addSummary(field, getUrl(file, false));
ensureUniqueMemberName(members, field);
parent.Members.Add(field);
}
}
///
/// process subfolders:
/// iterate over folders and add a nested class
///
DirectoryInfo[] subfolders = dir.GetDirectories();
foreach (DirectoryInfo folder in subfolders)
{
if (isValidFolder(folder))
{
CodeTypeDeclaration nested = createStaticClass(getName(folder), false);
addSummary(nested, "Provides access to urls under: {0}", getUrl(folder, false).TrimStart('~'));
ensureUniqueMemberName(members, nested);
build(folder, nested);
/// .ctor will have already been added to members
/// so only add to parent if there are additional
/// members present
if (nested.Members.Count > 1)
parent.Members.Add(nested);
}
}
--_depth;
}
#endregion
#region init
/// <summary>
/// Initialises settings from the config file.
/// </summary>
/// <example>
///
/// Sample configuration - all nodes and elements are optional, but the file
/// needs a root node to load as an xml document.
/// <?xml version="1.0" encoding="utf-8" ?>
/// <settings
/// namespace=""
/// className="Href"
/// maxDepth="100"
/// lowercaseUrls="true"
/// includeExtension="false">
///
/// <files include="\.(aspx|html)$" exclude="\.htm$" />
/// <folders include="" exclude="App_|Bin|Templates" />
/// </settings>
///
/// </example>
void init()
{
_basePath = HostingEnvironment.ApplicationPhysicalPath;
XmlDocument xml = new XmlDocument();
using (Stream stream = VirtualPathProvider.OpenFile(base.VirtualPath))
xml.Load(stream);
/// code below uses syntax,
/// xml["elementName"] ?? xml.CreateElement( "elementName" );
/// as a lazy initialisation technique, rather than checking for
/// the node and performing alternate initialisation - this keeps
/// it within the same reading context.
///
/// general settings
///
XmlElement settings = xml["settings"] ?? xml.CreateElement("settings");
_maxDepth = int.Parse(getAttributeValue(settings, "maxDepth", "100"));
_useLowerCaseUrls = bool.Parse(getAttributeValue(settings, "lowercaseUrls", "false"));
_includeExtension = bool.Parse(getAttributeValue(settings, "includeExtension", "false"));
_makePartial = bool.Parse(getAttributeValue(settings, "makePartial", "false"));
_namespace = getAttributeValue(settings, "namespace");
_className = getAttributeValue(settings, "className", "Href");
///
/// files settings
///
XmlElement files = settings["files"] ?? xml.CreateElement("files");
isValidFile = createFilter(
getAttributeValue(files, "include", @"\.aspx$"),
getAttributeValue(files, "exclude")
);
///
/// folders settings
///
XmlElement folders = settings["folders"] ?? xml.CreateElement("folders");
isValidFolder = createFilter(
getAttributeValue(folders, "include"),
getAttributeValue(folders, "exclude", "App_|Bin")
);
}
#endregion
#region getAttributeValue
/// <summary>
///
/// </summary>
/// <param name="parent"></param>
/// <param name="name"></param>
/// <param name="default"></param>
/// <returns></returns>
static string getAttributeValue(XmlElement parent, string name, string @default)
{
XmlAttribute attribute = parent.Attributes[name];
return null == attribute ? @default : attribute.Value.Trim();
}
/// <summary>
///
/// </summary>
/// <param name="parent"></param>
/// <param name="name"></param>
/// <returns></returns>
static string getAttributeValue(XmlElement parent, string name)
{
return getAttributeValue(parent, name, null);
}
#endregion
#region createFilter
/// <summary>
/// Creates a Predicate for filtering based on the given regex patterns
/// </summary>
/// <param name="includePattern"></param>
/// <param name="excludePattern"></param>
/// <returns></returns>
static Predicate<FileSystemInfo> createFilter(string includePattern, string excludePattern)
{
Regex include = null, exclude = null;
if (!string.IsNullOrEmpty(includePattern))
include = new Regex(includePattern,
RegexOptions.Compiled | RegexOptions.IgnoreCase);
if (!string.IsNullOrEmpty(excludePattern))
exclude = new Regex(excludePattern,
RegexOptions.Compiled | RegexOptions.IgnoreCase);
return createFilter(include, exclude);
}
/// <summary>
/// Creates a Predicate for filtering based on the given regex
/// </summary>
/// <param name="include"></param>
/// <param name="exclude"></param>
/// <returns></returns>
static Predicate<FileSystemInfo> createFilter(Regex include, Regex exclude)
{
if (null != include && null != exclude)
return delegate(FileSystemInfo info) { return include.IsMatch(info.FullName) && !exclude.IsMatch(info.FullName); };
else if (null != include)
return delegate(FileSystemInfo info) { return include.IsMatch(info.FullName); };
else if (null != exclude)
return delegate(FileSystemInfo info) { return !exclude.IsMatch(info.FullName); };
else
return delegate(FileSystemInfo info) { return true; };
}
#endregion
#region getInitExpression
/// <summary>
/// Returns the given value surrounded with quotes.
/// </summary>
/// <param name="value"></param>
/// <returns></returns>
static CodeSnippetExpression getInitExpression(string value)
{
return new CodeSnippetExpression(string.Concat("\"", value, "\""));
}
#endregion
#region getName
/// <summary>
/// Gets the normalised/escaped member name for the given file
/// </summary>
/// <param name="file"></param>
/// <returns></returns>
string getName(FileSystemInfo file)
{
string name = Path.GetFileNameWithoutExtension(file.Name);
if (_includeExtension)
name += file.Extension.Replace('.', '_');
name = Regex.Replace(name, @"[^a-z0-9_]*", string.Empty,
RegexOptions.Compiled | RegexOptions.IgnoreCase);
// Ensure pascal casing of the name - not really required
//name = TextHelper.PascalCase( name );
// Escape names not starting with a letter
if (name.Length > 0 && !char.IsLetter(name[0]))
name = "_" + name;
// Escape C# keywords
// included in separate library, omitted here for clarity
//name = CodeHelper.CSharp.EscapeWord(name);
return name;
}
#endregion
#region getUrl
/// <summary>
/// Gets the url of the file, relative to the app root
/// </summary>
/// <param name="file"></param>
/// <returns></returns>
string getUrl(FileSystemInfo file)
{
return getUrl(file, true);
}
/// <summary>
/// Gets the url of the file, relative to the app root
/// </summary>
/// <param name="file"></param>
/// <param name="allowNormalisation">When true, allows lowercasing of the
/// url and stripping of default.aspx</param>
/// <returns></returns>
string getUrl(FileSystemInfo file, bool allowNormalisation)
{
string url = file.FullName.Substring(_basePath.Length);
if (allowNormalisation)
{
if (_useLowerCaseUrls)
url = url.ToLower();
if (url.EndsWith("default.aspx", StringComparison.OrdinalIgnoreCase))
url = url.Substring(0, url.Length - 12);
}
return string.Concat("~/", url.Replace("\\", "/"));
}
#endregion
#region addSummary
/// <summary>
/// Adds a summary doc comment to the type's comment collection
/// </summary>
/// <param name="type"></param>
/// <param name="format"></param>
/// <param name="args"></param>
void addSummary(CodeTypeMember type, string format, params object[] args)
{
addSummary(type.Comments, format, args);
}
/// <summary>
/// Adds a summary doc comment to the collection
/// </summary>
/// <param name="comments"></param>
/// <param name="format"></param>
/// <param name="args"></param>
void addSummary(CodeCommentStatementCollection comments, string format, params object[] args)
{
comments.Add(new CodeCommentStatement("<summary>", true));
comments.Add(new CodeCommentStatement(string.Format(format, args), true));
comments.Add(new CodeCommentStatement("</summary>", true));
}
#endregion
#region createStaticClass
/// <summary>
/// Creates a static class type with the given name
/// </summary>
/// <param name="name"></param>
/// <param name="partial"></param>
/// <returns></returns>
static CodeTypeDeclaration createStaticClass(string name, bool partial)
{
CodeTypeDeclaration type = new CodeTypeDeclaration(name);
type.TypeAttributes |= System.Reflection.TypeAttributes.Sealed;
type.Attributes = MemberAttributes.Public | MemberAttributes.Static;
type.IsClass = true;
type.IsPartial = partial;
CodeConstructor ctor = new CodeConstructor();
ctor.Attributes = MemberAttributes.Private;
type.Members.Add(ctor);
return type;
}
#endregion
#region ensureUniqueMemberName
/// <summary>
/// Ensures a unique name within the dictionary to get the name
/// with an index number appended to the end e.g. the second
/// occurrence of "MyProperty" becomes "MyProperty1"
/// </summary>
/// <remarks>A caveat of this method is where you may have two members
/// like MyPage.aspx, MyPage.html as well as MyPage1.aspx. A conflict
/// will occur giving duplicate members i.e. in the same order MyPage,
/// MyPage1 and MyPage1 a second time. The likelihood of such conflicts
/// is possible, with one possible solution to recurse using
/// ensureUniqueMemberName with the newly generated name, or enumerate
/// the parent type's Members to see whether there will be a conflict.
/// </remarks>
/// <param name="members">Dictionary containing the name of the members
/// in the current namespace as the key + the number of appearances as
/// the value.</param>
/// <param name="type">The next member to add to the current namespace.</param>
static void ensureUniqueMemberName(Dictionary<string, int> members, CodeTypeMember type)
{
string key = type.Name;
int count;
if (members.TryGetValue(key, out count))
{
type.Name = string.Concat(key, ++count);
members[key] = count;
}
else
{
members[key] = 0;
}
}
#endregion
}
}