Table of Contents

Class Url

Namespace
Trellis.Primitives
Assembly
Trellis.Primitives.dll

Represents a URL value object with format validation. Ensures that URLs are valid and well-formed for web and API scenarios.

[JsonConverter(typeof(ParsableJsonConverter<Url>))]
public class Url : ScalarValueObject<Url, string>, IComparable<ValueObject>, IComparable, IEquatable<ValueObject>, IConvertible, IFormattable, IScalarValue<Url, string>, IParsable<Url>
Inheritance
Url
Implements
Inherited Members
Extension Methods

Examples

Basic usage:

var url = Url.TryCreate("https://example.com/path");
// Returns: Success(Url("https://example.com/path"))

var withQuery = Url.TryCreate("https://api.example.com/search?q=test");
// Returns: Success(Url("https://api.example.com/search?q=test"))

var invalid = Url.TryCreate("not-a-url");
// Returns: Failure(Error.InvalidInput with detail "URL must be a valid absolute HTTP or HTTPS URL.")

Remarks

Url is a domain primitive that encapsulates URL validation and provides:

  • URI format validation using .NET's Uri class
  • Support for HTTP and HTTPS schemes
  • Type safety preventing mixing of URLs with other strings
  • Immutability ensuring URLs cannot be changed after creation
  • IParsable implementation for .NET parsing conventions
  • JSON serialization support for APIs and persistence
  • Activity tracing for monitoring and diagnostics

Validation rules:

  • Must be a valid absolute URI
  • Scheme must be HTTP or HTTPS
  • Must have a valid host

Common use cases:

  • Website URLs in user profiles
  • API endpoints configuration
  • Webhook URLs
  • Image and resource links
  • Redirect URLs

Properties

Host

Gets the host of the URL.

public string Host { get; }

Property Value

string

IsSecure

Gets whether the URL uses HTTPS.

public bool IsSecure { get; }

Property Value

bool

Path

Gets the path of the URL.

public string Path { get; }

Property Value

string

Port

Gets the port of the URL.

public int Port { get; }

Property Value

int

Query

Gets the query string of the URL (including the leading '?').

public string Query { get; }

Property Value

string

Scheme

Gets the scheme of the URL (http or https).

public string Scheme { get; }

Property Value

string

Methods

GetEqualityComponents(ref EqualityComponents)

Adds the components used for equality comparison. By default, adds only the wrapped Value.

protected override void GetEqualityComponents(ref EqualityComponents components)

Parameters

components EqualityComponents

The sink that collects this value object's equality components.

Examples

// Custom equality for Temperature - round to 2 decimal places
protected override void GetEqualityComponents(ref EqualityComponents components)
{
    components.Add(Math.Round(Value, 2));
}

Remarks

Override this method to customize equality comparison. For example, to compare email addresses case-insensitively or to round decimal values.

Parse(string?, IFormatProvider?)

Parses the string representation of a URL to its Url equivalent.

public static Url Parse(string? s, IFormatProvider? provider)

Parameters

s string
provider IFormatProvider

Returns

Url

ToUri()

Gets the underlying Uri object.

public Uri ToUri()

Returns

Uri

TryCreate(string?, string?)

Attempts to create a Url from the specified string. If fieldName is not provided, validation errors use "url" as the field name.

public static Result<Url> TryCreate(string? value, string? fieldName = null)

Parameters

value string

The URL string to validate.

fieldName string

Optional field name for validation error messages. If not provided, defaults to "url".

Returns

Result<Url>

Success with the Url if the string is a valid HTTP/HTTPS URL; otherwise Failure with Error.InvalidInput.

TryParse(string?, IFormatProvider?, out Url)

Tries to parse a string into a Url.

public static bool TryParse(string? s, IFormatProvider? provider, out Url result)

Parameters

s string
provider IFormatProvider
result Url

Returns

bool
Edit this page