Table of Contents

Class PhoneNumber

Namespace
Trellis.Primitives
Assembly
Trellis.Primitives.dll

Represents a phone number value object with E.164 format validation. Ensures that phone numbers follow international standards for telephony.

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

Examples

Basic usage:

var phone = PhoneNumber.TryCreate("+14155551234");
// Returns: Success(PhoneNumber("+14155551234"))

var invalid = PhoneNumber.TryCreate("555-1234");
// Returns: Failure(ValidationError("Phone number must be in E.164 format (e.g., +14155551234)."))

Remarks

PhoneNumber is a domain primitive that encapsulates phone number validation and provides:

  • E.164 format validation (international phone number standard)
  • Type safety preventing mixing of phone numbers with other strings
  • Immutability ensuring phone numbers cannot be changed after creation
  • IParsable implementation for .NET parsing conventions
  • JSON serialization support for APIs and persistence
  • Activity tracing for monitoring and diagnostics

E.164 format rules:

  • Starts with a '+' sign
  • Country code (1-3 digits)
  • Subscriber number (up to 12 digits)
  • Maximum total length: 15 digits (excluding the '+' sign)
  • Minimum total length: 8 digits (excluding the '+' sign)

Common use cases:

  • Contact information in entities
  • SMS notification recipients
  • Two-factor authentication
  • Customer support systems

Note: Opinionated Implementation - If you need different phone number formats (e.g., with extensions like +1-415-555-1234 ext. 123), create your own PhoneNumber value object using the ScalarValueObject<TSelf, T> base class.

Methods

GetCountryCode()

Gets the country code portion of the phone number.

public string GetCountryCode()

Returns

string

The country code (digits after + and before subscriber number).

Parse(string?, IFormatProvider?)

Parses the string representation of a phone number to its PhoneNumber equivalent.

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

Parameters

s string
provider IFormatProvider

Returns

PhoneNumber

TryCreate(string?, string?)

Attempts to create a PhoneNumber from the specified string.

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

Parameters

value string

The phone number string to validate.

fieldName string

Optional field name to use in validation error messages.

Returns

Result<PhoneNumber>

Success with the PhoneNumber if the string is in E.164 format; otherwise Failure with a ValidationError.

TryParse(string?, IFormatProvider?, out PhoneNumber)

Tries to parse a string into a PhoneNumber.

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

Parameters

s string
provider IFormatProvider
result PhoneNumber

Returns

bool