A .NET library for searching IP address-related data in a CZDB database. Supports memory and B-tree search algorithms for both IPv4 and IPv6 addresses.
$ dotnet add package CzdbSearcherCzdbSearcher is a .NET library for searching IP address-related data in a CZDB (CZ88) database. It supports two types of search algorithms: memory search and B-tree search for both IPv4 and IPv6 addresses.
Install the package via NuGet Package Manager:
dotnet add package CzdbSearcher
Or via Package Manager Console in Visual Studio:
Install-Package CzdbSearcher
Or add it directly to your .csproj file:
<PackageReference Include="CzdbSearcher" Version="1.0.0" />
Database files and decryption keys can be obtained from www.cz88.net.
using CzdbSearcher;
// Create a searcher instance
using var searcher = new DbSearcher("path/to/database.czdb", QueryType.Memory, "your-key");
// Search for an IP address
string result = searcher.Search("8.8.8.8");
Console.WriteLine(result); // Output: Country–Province–City–District ISP
using CzdbSearcher;
using CzdbSearcher.Exceptions;
try
{
// Initialize the searcher
using var searcher = new DbSearcher("database.czdb", QueryType.Memory, "your-decryption-key");
// Perform IP lookup
string region = searcher.Search("192.168.1.1");
if (region != null)
{
Console.WriteLine($"IP location: {region}");
// Example output: "China–Shanghai–Shanghai–Hongkou District Telecom"
}
else
{
Console.WriteLine("IP not found in database");
}
}
catch (IpFormatException ex)
{
Console.WriteLine($"Invalid IP format: {ex.Message}");
}
catch (Exception ex)
{
Console.WriteLine($"Error: {ex.Message}");
}
using CzdbSearcher;
// Load database from stream (Memory mode only)
using var fileStream = File.OpenRead("database.czdb");
using var searcher = new DbSearcher(fileStream, QueryType.Memory, "your-key");
string result = searcher.Search("8.8.8.8");
using var searcher = new DbSearcher("ipv6-database.czdb", QueryType.Memory, "your-key");
// Query IPv6 address
string result = searcher.Search("2001:4860:4860::8888");
Console.WriteLine(result);
CzdbSearcher supports two query types:
using var searcher = new DbSearcher("database.czdb", QueryType.Memory, "key");
using var searcher = new DbSearcher("database.czdb", QueryType.BTree, "key");
⚠️ Important: Only the Memory query mode is thread-safe.
If you're using B-tree mode in a multi-threaded environment:
DbSearcher instance for each thread// Thread-safe approach for Memory mode
private static readonly DbSearcher searcher = new DbSearcher("db.czdb", QueryType.Memory, "key");
// For B-tree mode, use ThreadLocal or create per-thread instances
private static readonly ThreadLocal<DbSearcher> searcherPerThread =
new ThreadLocal<DbSearcher>(() => new DbSearcher("db.czdb", QueryType.BTree, "key"));
Always dispose of the DbSearcher instance when done:
// Using statement (recommended)
using var searcher = new DbSearcher("database.czdb", QueryType.Memory, "key");
// Or explicit disposal
var searcher = new DbSearcher("database.czdb", QueryType.Memory, "key");
try
{
// Use searcher
}
finally
{
searcher.Dispose();
}
The library includes a console application for testing:
# Interactive mode
dotnet run -- -d database.czdb -t Memory -k your-key
# Benchmark mode
dotnet run -- -d database.czdb -t Memory -k your-key -b -i ip-ranges.txt
-d, --dbFilePath: Path to the database file (required)-t, --queryType: Query type - Memory or BTree (required)-k, --key: Decryption key (required)-b, --benchmark: Enable benchmark mode-i, --ipFilePath: Path to IP ranges file for benchmarkingThe IP ranges file should contain one range per line in the format:
start_ip\tend_ip
192.168.1.1\t192.168.1.255
10.0.0.1\t10.0.0.255
The library throws specific exceptions for different error conditions:
try
{
var result = searcher.Search("invalid-ip");
}
catch (IpFormatException ex)
{
// Handle invalid IP address format
}
catch (ArgumentException ex)
{
// Handle invalid IP for database type (IPv4 vs IPv6)
}
catch (Exception ex)
{
// Handle other errors (file not found, decryption errors, etc.)
}
DbSearcher(string dbFile, QueryType queryType, string key)
DbSearcher(Stream stream, QueryType queryType, string key) // Memory mode only
DbType DbType { get; } // IPv4 or IPv6
QueryType QueryType { get; } // Memory or BTree
string Search(string ip) // Search for IP location
void Dispose() // Release resources
void Close() // Alias for Dispose()
public enum DbType
{
IPv4,
IPv6
}
public enum QueryType
{
Memory,
BTree
}
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.
Contributions are welcome! Please feel free to submit a Pull Request.
For issues and questions: