Home

API reference for Ada.Url, WHATWG URL parsing for .NET.

Every example on these pages was run against the published package, and the outputs shown are what it printed. Current version: 0.1.1.

dotnet add package Ada.Url

All types are in the Ada.Url namespace.

Which type to use

You need	Use	Allocates
A yes or no, a normalised URL, a hostname or an origin	AdaUrl static methods	Nothing
Several properties from one URL, or to modify it	AdaUrl instance (ref struct)	Nothing
A URL stored in a field, cached, or used across await	AdaUrlHandle	One object per URL
A query string	AdaSearchParams	Nothing
Punycode conversion of a domain	AdaIdna	Only the string overloads
Native version, input size limit	AdaLibrary	Nothing
Byte offsets of each part	AdaUrlComponents	Nothing

Rules that apply everywhere

UTF-8 first. ReadOnlySpan<byte> is the main input type. Use u8 literals or Encoding.UTF8.GetBytes. Overloads taking ReadOnlySpan<char> or string exist and pay one transcode.

Returned spans are borrowed. Every ReadOnlySpan<byte> a getter returns points into native memory owned by the URL. It stays valid until the URL is changed or disposed. Copy what you need before calling any setter:

using var url = AdaUrl.Parse("https://example.com/a"u8);
string host = Encoding.UTF8.GetString(url.Hostname); // copied, safe to keep
url.TrySetHostname("example.org"u8);                 // any span read before this is now invalid

Dispose what you parse. AdaUrl, AdaUrlHandle and AdaSearchParams own native memory. Use a using declaration. The static methods need nothing.

Try methods do not throw. They return false for invalid input or a buffer that is too small. Parse methods throw FormatException for invalid input.

Not thread safe for mutation. Reading one instance from several threads is fine. A setter running concurrently with anything else is a use after free.

Buffers

Methods named Try...(input, Span<byte> destination, out int written) write into your buffer and return false when it is too small. false also means invalid input, so check CanParse first if you need to tell the two apart. 256 bytes covers ordinary URLs. For arbitrary input, rent a buffer sized from the input:

// Percent encoding can triple a byte, so this is a starting size, not a guarantee.
byte[] rented = ArrayPool<byte>.Shared.Rent(input.Length * 3 + 16);
try
{
    if (AdaUrl.TryNormalize(input, rented, out int written))
        Use(rented.AsSpan(0, written));
}
finally
{
    ArrayPool<byte>.Shared.Return(rented);
}