Url - Bit.Butil

When System.Uri is the better tool For ordinary parsing it usually is - it needs no interop call. Come here when the answer has to match what the browser will do: WHATWG and RFC 3986 disagree on trailing dots in a host, on how far .. may climb, and on which characters get percent-encoded. And come here for URLPattern, which has no .NET counterpart.

Parse and resolve

IsSupported / CanParse / Parse / Resolve

Parse splits a URL into the components the browser sees. CanParse asks the same question without the exception a constructor would throw. Resolve applies a relative reference to a base, including the scheme-relative and over-climbing cases.

@inject Bit.Butil.Url url

if (await url.CanParse("https://example.com:8080/docs/a") is false) return;

var parts = await url.Parse("https://example.com:8080/docs/a?x=1#top");
// parts.Origin, parts.Pathname, parts.Search, ...

var absolute = await url.Resolve("../b", "https://example.com/docs/a");
// "https://example.com/b"

Live sample

parse output

Results will appear here when you interact with the samples.

Query strings

ParseQuery / BuildQuery / GetQueryValues / SetQuery / AppendQuery / RemoveQuery / SortQuery

ParseQuery returns a flat list rather than a map, because a query string may repeat a name - ?tag=a&tag=b is two parameters, and a map would drop one. The whole-URL edits save re-assembling the parts by hand; SortQuery is the one to reach for when two URLs that differ only in parameter order should produce the same cache key.

var parameters = await url.ParseQuery("?tag=a&tag=b&page=2");
var values = await url.GetQueryValues("?tag=a&tag=b", "tag");   // ["a", "b"]

var query = await url.BuildQuery([new("q", "a b&c"), new("tag", "x")]);
var replaced = await url.SetQuery(current, [new("page", "1")]);

var next = await url.AppendQuery(current, [new("page", "3")]);
var clean = await url.RemoveQuery(current, "utm_source", "utm_medium");
var key = await url.SortQuery(current);

Live sample

query output

Results will appear here when you interact with the samples.

Match a route

IsPatternSupported / IsPatternValid / TestPattern / MatchPattern

URLPattern is a route matcher: :name captures a segment, * is a wildcard, and {} groups can be made optional with ?. TestPattern answers yes or no; MatchPattern also hands back what each parameter captured. A path-only pattern needs a base URL to resolve against.

var match = await url.MatchPattern("/books/:id", "https://example.com/books/42",
                                   baseUrl: "https://example.com");

var id = match?.Groups["id"];   // "42"

Live sample

pattern output

Results will appear here when you interact with the samples.

API reference

Member

Signature

Description

IsSupported

ValueTask<bool> IsSupported()

True when the runtime exposes URL. Returns default (false) during prerender/SSR instead of throwing.

CanParse

ValueTask<bool> CanParse(string url, string? baseUrl = null)

Whether the browser can parse this URL, without the exception the constructor would throw.

Parse

ValueTask<UrlParts?> Parse(string url, string? baseUrl = null)

Splits a URL into its components as the browser parsed it. Null when it doesn't parse.

Resolve

ValueTask<string?> Resolve(string url, string baseUrl)

Resolves a possibly relative reference against a base, the way the browser's own resolver does.

ParseQuery

ValueTask<UrlQueryParameter[]> ParseQuery(string query)

Parses a query string into its parameters, in order, keeping repeats.

BuildQuery

ValueTask<string> BuildQuery(UrlQueryParameter[] parameters)

Builds a query string, percent-encoding each parameter the way the browser does. No leading '?'.

GetQueryValues

ValueTask<string[]> GetQueryValues(string query, string key)

Every value of one repeated parameter, in order.

SetQuery

ValueTask<string?> SetQuery(string url, UrlQueryParameter[] parameters)

Replaces a URL's whole query string.

AppendQuery

ValueTask<string?> AppendQuery(string url, UrlQueryParameter[] parameters)

Appends parameters, keeping any already there - including one of the same name.

RemoveQuery

ValueTask<string?> RemoveQuery(string url, params string[] keys)

Removes every parameter with any of these names.

SortQuery

ValueTask<string?> SortQuery(string url)

Sorts a URL's query parameters by name - for a cache key or a signature.

IsPatternSupported

ValueTask<bool> IsPatternSupported()

True when the runtime exposes URLPattern. Newer than the rest of this class.

IsPatternValid

ValueTask<bool> IsPatternValid(string pattern, string? baseUrl = null)

Whether the pattern itself compiles - a malformed pattern otherwise looks like 'no match'.

TestPattern

ValueTask<bool> TestPattern(string pattern, string url, string? baseUrl = null)

Whether a URL matches a pattern.

MatchPattern

ValueTask<UrlPatternMatch?> MatchPattern(string pattern, string url, string? baseUrl = null)

Matches a URL against a pattern and returns what the named parameters captured. Null when it doesn't match.