MobileParserTool 1.0.5

MobileParserTool

MobileParserTool is a C# library designed to validate and parse mobile phone numbers, as well as provide information about country codes. The project targets .NET 8.0 and leverages the libphonenumber-csharp library for phone number parsing and validation.

Installation

dotnet add package MobileParserTool

Key Features

✅ Validate single or multiple phone numbers ✅ Auto-detect country from phone number ✅ Handles whitespaces automatically ✅ Returns international format without + prefix (e.g., 233535688331) ✅ Support for 245+ countries ✅ Batch validation with different country codes

Key Components

1. Interfaces

• IMobileNumberParser: Defines methods for:
  • Validating mobile number → IsMobileNumberValid.
  • Validating mobile numbers → AreMobileNumberValid.
  • Validating mobile numbers with the same country code → AreMobileNumberValidForACountryCode.
  • NEW: Parsing phone number with auto-detection → ParsePhoneNumber.
  • Validating country code → IsCountryCodeValid.
  • Retrieving country codes → GetCountryCodes.
  • Getting country names → GetCountryName.

2. Providers

• MobileNumberParser:
  Implements the IMobileNumberParser interface and includes methods to:
  • Validate mobile numbers.
  • Retrieve a list of supported country codes.
  • Check if a country code is valid.
  • Get the country name from a country code.

3. Project Configuration

• Configured using a .csproj file, which specifies:
  • Target framework: .NET 8.0.
  • Package references.
  • Other project properties.

Dependencies

• libphonenumber-csharp:
  A library for parsing, formatting, and validating international phone numbers.

• Microsoft.Extensions.DependencyInjection:
  A library for dependency injection in .NET applications.

Registering the Service

Add the following line to your service configuration (e.g., in Program.cs):

builder.Services.AddMobileParserTool();

Usage Examples

1. Single Phone Number Validation

// Returns international format without + prefix (e.g., 233535688331)
var phone = "0535688331";
var countryCode = "GH";

if (mobileNumberParser.IsMobileNumberValid(phone, countryCode, out var correctNumber))
{
    Console.WriteLine($"Valid: {correctNumber}"); // Output: 233535688331
}
else
{
    Console.WriteLine("Invalid phone number");
}

2. NEW: Parse Phone Number (Auto-detect Country)

// Automatically detects country from phone number
// Works best with international format (+233535688331 or 233535688331)
var result = mobileNumberParser.ParsePhoneNumber("+233535688331");

if (result.IsValid)
{
    Console.WriteLine($"International Format: {result.InternationalFormat}"); // 233535688331
    Console.WriteLine($"Country Code: {result.CountryCode}");                 // GH
    Console.WriteLine($"Dialing Code: +{result.DialingCode}");               // +233
}
else
{
    Console.WriteLine($"Error: {result.Error}");
}

3. Multiple Phone Number Validation (Different Country Codes)

var numberList = new PhoneNumberCheckListRequest
{
    PhoneNumbers = new List<PhoneNumberPayload>
    {
        new PhoneNumberPayload
        {
            PhoneNumber = "0535688331",
            ShortCountryName = "GH"
        },
        new PhoneNumberPayload
        {
            PhoneNumber = "+1-202-555-0173",
            ShortCountryName = "US"
        },
    }
};

var validateListOfNumbers = mobileNumberParser.AreMobileNumberValid(numberList);

foreach (var item in validateListOfNumbers.CheckLists)
{
    if (item.IsValid)
    {
        Console.WriteLine($"Valid: {item.DerivedPhoneNumber}");
    }
}

4. Multiple Phone Number Validation (Same Country Code)

var request = new PhoneNumberSingleCountryCodeCheckListRequest
{
    ShortCountryName = "GH",
    PhoneNumber = new[] { "0535688331", "0594646651" }
};

var validateListOfNumbers = mobileNumberParser.AreMobileNumberValidForACountryCode(request);

foreach (var item in validateListOfNumbers.CheckLists)
{
    Console.WriteLine($"Original: {item.OriginalPhoneNumber}");
    Console.WriteLine($"Formatted: {item.DerivedPhoneNumber}");
    Console.WriteLine($"Valid: {item.IsValid}");
}

5. Whitespace Handling

// All these formats work correctly - whitespaces are automatically removed
var testNumbers = new[]
{
    "0535 688 331",           // Spaces throughout
    " 0535688331 ",           // Leading/trailing spaces
    "+233 535 688 331",       // International with spaces
};

foreach (var number in testNumbers)
{
    if (mobileNumberParser.IsMobileNumberValid(number, "GH", out var formatted))
    {
        Console.WriteLine($"{number} → {formatted}"); // All output: 233535688331
    }
}

Response Models

PhoneNumberCheckListResponse

Response for multiple phone number validation:

// C# Response Model
var response = new PhoneNumberCheckListResponse
{
    CheckLists = new List<PhoneNumberCheckList>
    {
        new PhoneNumberCheckList
        {
            IsValid = true,
            DerivedPhoneNumber = "233535688331",  // International format without +
            OriginalPhoneNumber = "0535688331"
        },
        new PhoneNumberCheckList
        {
            IsValid = false,
            DerivedPhoneNumber = null,
            OriginalPhoneNumber = "invalidnumber"
        }
    },
    Error = null
};

// JSON Response
{
    "checkLists": [
        {
            "isValid": true,
            "derivedPhoneNumber": "233535688331",
            "originalPhoneNumber": "0535688331"
        },
        {
            "isValid": false,
            "derivedPhoneNumber": null,
            "originalPhoneNumber": "invalidnumber"
        }
    ],
    "error": null
}

ParsedPhoneNumberResponse (NEW)

Response for the ParsePhoneNumber method:

// C# Response Model
var response = new ParsedPhoneNumberResponse
{
    IsValid = true,
    InternationalFormat = "233535688331",  // Without + prefix
    CountryCode = "GH",                    // ISO country code
    DialingCode = 233,                     // Country dialing code
    OriginalNumber = "+233535688331",      // Original input
    Error = null
};

// JSON Response
{
    "isValid": true,
    "internationalFormat": "233535688331",
    "countryCode": "GH",
    "dialingCode": 233,
    "originalNumber": "+233535688331",
    "error": null
}

Important Notes

Phone Number Format

All methods return phone numbers in international format without the + prefix:

• ✅ Returned format: 233535688331
• ❌ Not returned: +233535688331

If you need the + prefix, simply prepend it:

var withPlus = $"+{result.InternationalFormat}"; // +233535688331

Whitespace Handling

The library automatically handles whitespaces in phone numbers:

• Leading/trailing spaces are trimmed
• Spaces within the number are removed
• Works with any spacing pattern

Auto-detection

The ParsePhoneNumber method works best when the number includes a country code:

• ✅ +233535688331 (international format with +)
• ✅ 233535688331 (international format without +)
• ⚠️ 0535688331 (local format - tries common countries)

For local format numbers without country code, it attempts to match against common countries (GH, US, GB, NG, etc.).

Support

If you find this library useful, consider supporting the development:

License

This project is licensed under the MIT License.