Orchardcore Phone Numbers

Orchard Core Phone Numbers - Prompt Templates

Normalize and Validate Phone Numbers

You are an Orchard Core expert. Generate code and configuration for the CrestApps Phone Numbers services. This infrastructure module provides parsing, validation, E.164 normalization, region lookup, country-code lookup, and phone-number time-zone lookup.

Guidelines

• Install CrestApps.OrchardCore.PhoneNumbers in the web/startup project.
• Enable CrestApps.OrchardCore.PhoneNumbers; it is marked dependency-only and normally activates through a dependent feature.
• Resolve IPhoneNumberService rather than parsing numbers with string manipulation.
• Store normalized phone numbers in E.164 format for comparisons, indexes, DNC lists, and external APIs.
• Supply an ISO 3166-1 alpha-2 region when input has no leading +.
• Do not infer a country from a local number without an explicit region context.
• Preserve user-facing formatting separately when required; E.164 is a canonical storage and transport value.
• Use GetTimeZones only with an E.164 number and allow for zero, one, or multiple IANA time-zone ids.
• This feature is a service module, not a content part or content field by itself.
• Add verification data through CrestApps.OrchardCore.PhoneNumbers.Verifications, not this module.
• All recipe JSON must be wrapped in { "steps": [...] }.
• All C# classes must use the sealed modifier, except for View Models.

Feature Overview

Enable Phone Number Services

{
  "steps": [
    {
      "name": "Feature",
      "enable": [
        "CrestApps.OrchardCore.PhoneNumbers"
      ],
      "disable": []
    }
  ]
}

The feature has EnabledByDependencyOnly = true. Enabling DNC Registry or Phone Number Verifications activates it automatically; explicitly enabling it is useful for a custom module that consumes IPhoneNumberService.

IPhoneNumberService Operations

An E.164 number includes +, country calling code, and subscriber number, for example +17024993350.

Normalize at the Boundary

Normalize as soon as user input reaches your application. Store the normalized value when parsing succeeds, and show a validation error otherwise.

using CrestApps.OrchardCore.PhoneNumbers;

namespace MyCompany.OrchardCore.Contacts;

public sealed class ContactPhoneNormalizer
{
    private readonly IPhoneNumberService _phoneNumberService;

    public ContactPhoneNormalizer(IPhoneNumberService phoneNumberService)
    {
        _phoneNumberService = phoneNumberService;
    }

    public bool TryNormalize(string input, string regionCode, out string e164Number)
    {
        return _phoneNumberService.TryFormatToE164(input, regionCode, out e164Number);
    }
}

For a local number such as 702-499-3350, pass US. For a number that already begins with +, a region can be omitted when calling the service.

Do not strip non-digits yourself before invoking the service. Formatting characters, prefixes, and regional numbering rules must be interpreted by the phone-number service.

Validate Input

Use IsValidNumber when only validity is required:

if (!_phoneNumberService.IsValidNumber(model.PhoneNumber, model.RegionCode))
{
    ModelState.AddModelError(nameof(model.PhoneNumber), "Enter a valid phone number.");
}

Prefer TryFormatToE164 when the valid result also needs to be stored. It avoids a second parse and gives the comparison key required by DNC and verification workflows.

Region and Calling-Code Lookups

GetRegionCode returns the ISO 3166-1 alpha-2 region for an E.164 number or null when unavailable. GetCountryCode returns the numeric calling code for a known region and 0 when the region is unknown.

var regionCode = _phoneNumberService.GetRegionCode("+17024993350");
var callingCode = _phoneNumberService.GetCountryCode("US");
var regions = _phoneNumberService.GetSupportedRegions();

Treat the returned region as phone-number metadata, not an address or residency assertion. Numbers can be ported and countries can share calling codes.

Phone-Number Time Zones

GetTimeZones returns IANA identifiers associated with an E.164 number:

var timeZones = _phoneNumberService.GetTimeZones("+17024993350");

A result can be empty if it cannot be determined. It can also contain multiple entries where a calling range spans zones. Ask the user to choose when precise scheduling depends on one location. Do not silently treat a phone-number time zone as the account or tenant time zone.

Persistence Pattern

Store raw input only when it is necessary for auditing or editor display. Use E.164 as the index and unique-comparison value:

public sealed class ContactPhoneRecord
{
    public string DisplayNumber { get; set; } = string.Empty;

    public string NormalizedPhoneNumber { get; set; } = string.Empty;

    public string RegionCode { get; set; } = string.Empty;
}

Normalize and validate NormalizedPhoneNumber before a record is saved. Do not include a local number and its region in a global unique index because the same digits represent different numbers in different regions.

Integrations

Phone Numbers itself does not manage external verification providers, send SMS, create a content type, or supply an admin page.

Handling Failures

Avoid These Patterns

• Do not use a fixed string length as validation.
• Do not assume US for every local number.
• Do not convert an E.164 number to an integer because it loses + and can overflow.
• Do not use a phone number’s region as proof of a customer’s country.
• Do not persist an external provider’s formatted display string as the comparison key.
• Do not call external verification APIs when local parsing is all that is requested.