| Migration Guide |
The .NET Framework includes its own implementation of URI templates through its own UriTemplate class. The reference implementation of this class does not use the same syntax as RFC 6570, and also does not provide many of the advanced features described in the RFC. The URI Template Library is intended to reduce the effort required to migrate existing code that uses the .NET Framework, but syntax and functionality differences may require code changes. This page includes a partial list of migration issues developers may face when switching to this library.
This topic contains the following sections.
Template SyntaxSeveral aspects of URI Templates are affected by syntax differences between the .NET Framework implementation and RFC 6570. The needed changes are grouped into path segments syntax and query parameters. In addition to the syntax changes, there are differences in the behavior of the template matching operation. This will require additional consideration for code making use of the Match operation.
Path Variables
In most cases, expansion variables which appear in the path portion of a .NET Framework URI template are directly compatible with RFC 6570. The exception to this rule is templates which use an asterisk (*) to indicate the "rest of the path". RFC 6570 provides a special syntax called a reserved expansion which provides a similar feature. The following specific example appears in the documentation for the .NET Framework UriTemplate class.
weather/*
In this library, the equivalent to this template would be the following, where var can be any variable name.
weather/{+var}If code requires access to individual path segments, such as existing code making use of the WildcardPathSegments property, an alternative syntax called a path segment expansion may be used in combination with a composite value modifier instead of the reserved expansion. The following example shows the use of the path segment expansion to match the rest of the path.
weather{/segments*} Important |
|---|
While the reserved expansion is capable of matching both the path component of the URI and the query string, a path segment expansion will only match the path component. To include the ability to match query parameters when using the path segment expansion, see the Additional Query Parameters section below. |
Query Parameters
In the .NET Framework, the syntax for declaring query parameters for the template expansion operation differs from RFC 6570. In addition, during the matching operation the .NET Framework has implicit support for arbitrary query parameters which are not declared in the template itself. Each of these issues needs to be addressed when migrating to this library.
Additional Query Parameters
Support for additional query parameters during template matching is accomplished by adding including a query expansion with a composite value modifier. For templates which do not already contain a query expansion, this is as simple as adding {?params*} to the end of the template. For templates which do include a query expansion, the new variable must be added at the end of the list. A template ending with {?foo,bar} would thus become {?foo,bar,params*}.
Summary
The following table summarizes the changes required to make .NET URI Templates compatible with RFC 6570, using the examples provided in the documentation for the .NET Framework UriTemplate class.
.NET Framework | RFC 6570 (Binding) | RFC 6570 (Matching) |
|---|---|---|
"weather/WA/Seattle" | "weather/WA/Seattle" | "weather/WA/Seattle{?params*}" |
"weather/{state}/{city}" | "weather/{state}/{city}" | "weather/{state}/{city}{?params*}" |
"weather/*" | "weather/{+rest}" | "weather{/rest*}{?params*}", if "weather" matches -or- "weather/{rest0}{/rest1*}{?params*}", if "weather/" matches but "weather" does not |
"weather/{state}/{city}?forecast=today" | "weather/{state}/{city}?forecast=today" | "weather/{state}/{city}{?forecast,params*}" |
"weather/{state}/{city}?forecast={day}" | "weather/{state}/{city}{?forecast}" | "weather/{state}/{city}{?forecast,params*}" |
Template BindingThis library contains additional differences regarding the way parameters are inserted into templates to produce a bound URI.
Bind By Position
This library does not contain an equivalent to the BindByPosition(Uri, String) method. Any calls which use this method must be converted to use BindByName when migrating existing code to this library.
Relative Resolution
For the various BindByName methods which take a base address as a parameter, this library uses the Uri(Uri, Uri) constructor to implement the resolution of relative addresses against a base address. While the .NET Framework's URI Template implementation behaves in a manner "similar" to Combine, the behavior of this library is consistent with RFC 3986 §5.2. As a result, this library differs from the .NET Framework's implementation in two key instances.
 Note |
|---|
In the following description, the Query property of the base address is assumed to be empty. |
When the URI Template starts with a leading / character. In this case, the AbsolutePath property of the base address is removed from the base address during the resolution process.
When the AbsolutePath property of the base address is not empty, and does not end with a / character. In this case, the last path segment is removed from the base address during the resolution process. In other words, everything after the last / character is ignored.