Fluent URL Building

Flurl's URL builder is best explained with an example:

using Flurl;

var url = "http://www.some-api.com"
    .AppendPathSegment("endpoint")
    .SetQueryParams(new {
        api_key = _config.GetValue<string>["SomeApiKey"],
        max_results = 20,
        q = "Don't worry, I'll get encoded!"
    })
    .SetFragment("after-hash");

The example above (and most on this site) uses an extension method off String to implicitly create a Url object. You can do exactly the same explicitly if you prefer:

var url = new Url("http://www.some-api.com").AppendPathSegment(...

As of 3.0, all extension methods available on String are also available on System.Uri. In either case, you can use the builder methods and convert back to the original representation (using ToString() or ToUri()) in single fluent call chain.

In addition to the object notation above, SetQueryParams also accepts any collection of key-value pairs, Tuples, or a Dictionary object. These alternatives are particularly useful for parameter names that are not valid C# identifiers. There's also a SetQueryParam (singular) if you want to set them one by one. In any case, these methods overwrite any previously set values of the same name, but you can set multiple values of the same name by passing a collection:

var url = "http://www.mysite.com".SetQueryParam("x", new[] { 1, 2, 3 });
Assert.AreEqual("http://www.mysite.com?x=1&x=2&x=3", url)

Builder methods and their overloads are highly discoverable, intuitive, and always chainable. A few destructive methods are also included, such as RemoveQueryParam, RemovePathSegment, and ResetToRoot.

Parsing

In addition to building URLs, Flurl.Url is effective at decomposing an existing one:

var url = new Url("https://user:pass@www.mysite.com:1234/with/path?x=1&y=2#foo");
Assert.AreEqual("https", url.Scheme);
Assert.AreEqual("user:pass", url.UserInfo);
Assert.AreEqual("www.mysite.com", url.Host);
Assert.AreEqual(1234, url.Port);
Assert.AreEqual("user:pass@www.mysite.com:1234", url.Authority);
Assert.AreEqual("https://user:pass@www.mysite.com:1234", url.Root);
Assert.AreEqual("/with/path", url.Path);
Assert.AreEqual("x=1&y=2", url.Query);
Assert.AreEqual("foo", url.Fragment);

Although similar to the parsing capabilities of System.Uri, Flurl aims to be more compliant with RFC 3986, and more true to the actual string provided, and therefore differs in the following ways:

Url.QueryParams is a special collection type that maintains order and allows duplicate names, but is optimized for the typical case of unique names:

var url = new Url("https://www.mysite.com?x=1&y=2&y=3");
Assert.AreEqual("1", url.QueryParams.FirstOrDefault("x"));
Assert.AreEqual(new[] { "2", "3" }, url.QueryParams.GetAll("y"));

Mutability

A Url is effectively a mutable builder object that implicitly converts to a string. If you need an immutable URL, such as a base URL as a member variable of a class, a common pattern is to type it as a String:

public class MyServiceClass
{
    private readonly string _baseUrl;

    public Task CallServiceAsync(string endpoint, object data) {
        return _baseUrl
            .AppendPathSegment(endpoint)
            .PostAsync(data); // requires Flurl.Http package
    }
}

Here the call to AppendPathSegment creates a new Url object. The result is that _baseUrl remains unmodified, and you've added no additional "noise" compared to if you had declared it as a Url.

Another way to get around the mutable nature of Url when needed is to use the Clone() method:

var url2 = url1.Clone().AppendPathSegment("next");

Here you get a new Url object based on another, so you can modify it without changing the original.

Encoding

Flurl takes care of encoding characters in URLs but takes a different approach with path segments than it does with query string values. The assumption is that query string values are highly variable (such as from user input), whereas path segments tend to be more "fixed" and may already be encoded, in which case you don't want to double-encode. Here are the rules Flurl follows:

In some cases, you might want to set a query parameter that you know to be already encoded. SetQueryParam has optional isEncoded argument:

url.SetQueryParam("x", "don%27t%20touch%20me", true);

While the official URL encoding for the space character is %20, it's very common to see + used in query parameters. You can tell Url.ToString to do this with its optional encodeSpaceAsPlus argument:

var url = "http://foo.com".SetQueryParam("x", "hi there");
Assert.AreEqual("http://foo.com?x=hi%20there", url.ToString());
Assert.AreEqual("http://foo.com?x=hi+there", url.ToString(true));

Utility Methods

Url also contains some handy static methods, such as Combine, which is basically a Path.Combine for URLs, ensuring one and only one separator character between parts:

var url = Url.Combine(
    "http://foo.com/",
    "/too/", "/many/", "/slashes/",
    "too", "few?",
    "x=1", "y=2"
// result: "http://www.foo.com/too/many/slashes/too/few?x=1&y=2"

And to help you avoid some of the notorious quirks associated with the various URL encoding/decoding methods in .NET, Flurl provides some "quirk-free" alternatives:

Url.Encode(string s, bool encodeSpaceAsPlus); // includes reserved characters like / and ?
Url.EncodeIllegalCharacters(string s, bool encodeSpaceAsPlus); // reserved characters aren't touched
Url.Decode(string s, bool interpretPlusAsSpace);