Click or drag to resize
Template Expansion

Template expansion is the process of expanding a URI Template according to specific values for its variables. This is the core operation defined by RFC 6570 and the primary feature provided by this library. The binding operation itself is implemented by the BindByName methods; this page describes a high-level overview of the behavior of these methods with respect to RFC 6570.

Creating Templates

URI Template instances are created by calling UriTemplate(String) with the template in the form described RFC 6570 (Level 4). URI Templates are parsed at the time they are constructed to ensure they meet the syntax requirements described in RFC 6570 and identify expression expansions for efficient binding. The following examples show the templates described in the Remarks section of the .NET Framework UriTemplate documentation, converted to RFC 6570 syntax.

  • "weather/WA/Seattle"

  • "weather/{state}/{city}"

  • "weather/{+rest}"

  • "weather/{state}/{city}?forecast=today"

  • "weather/{state}/{city}{?forecast}"

The following example demonstrates the basic construction and binding of a template instance.

C#
Copy
UriTemplate template = new UriTemplate("weather/{state}/{city}{?forecast}");

Dictionary<string, string> parameters = new Dictionary<string, string>
{
    { "state", "WA" },
    { "city", "Seattle" },
    { "forecast", "today" }
};

Uri boundAddress = template.BindByName(parameters);
Console.WriteLine(boundAddress);
// Output:
// weather/WA/Seattle?forecast=today

By specifying a base address in addition to the parameters, an absolute URI is produced by the expansion operation.

C#
Copy
UriTemplate template = new UriTemplate("weather/{state}/{city}{?forecast}");

Dictionary<string, string> parameters = new Dictionary<string, string>
{
    { "state", "WA" },
    { "city", "Seattle" },
    { "forecast", "today" }
};

Uri baseAddress = new Uri("http://www.example.com");
Uri boundAddress = template.BindByName(baseAddress, parameters);
Console.WriteLine(boundAddress);
// Output:
// http://www.example.com/weather/WA/Seattle?forecast=today

Best Practices

Due to the heavy use of regular expressions within this library, several "best practices" should be followed to maximize the overall performance.

Use shared template instances

Instances of the UriTemplate class are safe for use in multi-threaded applications. If a single template string will be used multiple times for expansion or matching, a static variable should be initialized with the template and reused each time it is needed.

Use the "portable" library only when necessary

The Portable Class Library for the .NET Framework does not support the creation of compiled regular expressions. In particular, the Compiled flag is not available. To maximize performance, use the net40-client build instead.

Note Note

When installing this library using the NuGet Package Manager within Visual Studio, this best practice rule is followed by default.

Template Parameters

Template parameters fall into three categories; using the terminology of RFC 6570, these are strings, lists, and associative arrays. The following table shows the relation between these values and their corresponding .NET types.

RFC 6570

.NET Framework

String

Any object which is not considered a list or associative array.

List

Any IEnumerable which is not considered an associative array, with the exception of String.

Associative array

Any IDictionaryTKey, TValue or IDictionary.

The rules for binding variables within a template are fully described in RFC 6570. For this library, the following behavior is provided which is only relevant to a .NET implementation.