Skip to content

README.en.md

Latest commit

 

History

History
327 lines (250 loc) · 8.1 KB

README.en.md

File metadata and controls

327 lines (250 loc) · 8.1 KB
Raw

LuYao .NET Utility Library

MIT License NuGet Build

中文 | English

This document is kept in sync with README.zh-CN.md.

Introduction

LuYao is a comprehensive collection of .NET utility libraries designed for enterprise-level applications. It provides a rich set of common tools, extensions, and utilities to help .NET developers write business code more efficiently.

The project consists of four main packages:

  • LuYao.Common: Core utilities library with caching, hashing, I/O helpers, threading utilities, and more
  • LuYao.Net.Http.FakeUserAgent: Fake user agent utilities
  • LuYao.Text.Json: JSON processing utilities built on Newtonsoft.Json
  • LuYao.Text.Json.Jint: JavaScript-powered JSON transformation using Jint engine

Supported Frameworks

  • .NET Framework 4.5+
  • .NET Framework 4.6.1+
  • .NET Standard 2.0
  • .NET Standard 2.1
  • .NET 6.0
  • .NET 8.0
  • .NET 10.0

Installation

Install via NuGet Package Manager:

# Core utilities
dotnet add package LuYao.Common

# Fake User Agent
dotnet add package LuYao.Net.Http.FakeUserAgent

# JSON utilities
dotnet add package LuYao.Text.Json

# Jint-based JSON transformation
dotnet add package LuYao.Text.Json.Jint

Or clone the source code:

git clone https://github.com/coderbusy/luyao-dotnet.git

Key Features

LuYao.Common

1. Caching
using LuYao;

// Create a cached object with automatic expiration
var cache = new CachedObject<string>("Hello World", TimeSpan.FromMinutes(5));
Console.WriteLine(cache.Value); // "Hello World"
Console.WriteLine(cache.IsExpired); // false
2. Array Utilities
using LuYao;

// Get empty array instances (optimized for memory)
var emptyInts = Arrays.Empty<int>();
var emptyStrings = Arrays.Empty<string>();
3. Hashing Algorithms
using LuYao.IO.Hashing;

// Compute file hash
var md5 = HashAgents.MD5.HashFile("test.txt");
var sha1 = HashAgents.SHA1.HashFile("test.txt");

// Compute string hash
var crc32 = HashAgents.CRC32.HashString("hello");
var crc64 = HashAgents.CRC64.HashString("world");

// Stream hashing
using var stream = File.OpenRead("data.bin");
var murmur128 = HashAgents.Murmur128.HashStream(stream);
4. Temporary File Management
using LuYao.IO;

// Auto-cleaning temporary file
using (var tempFile = AutoCleanTempFile.Create())
{
    File.WriteAllText(tempFile.FileName, "Temporary content");
    // File will be automatically deleted when disposed
}

// Create temp file with specific extension
using var tempCsv = AutoCleanTempFile.Create(".csv");
5. Thread Synchronization
using LuYao.Threading;

// Keyed lock for fine-grained synchronization
var lockObj = KeyedLocker<string>.GetLock("my-resource");
lock (lockObj)
{
    // Critical section
}

// Async lock
using var asyncLock = new AsyncLock();
using (await asyncLock.LockAsync())
{
    // Async critical section
}
13. Single Instance Manager
using LuYao.Threading;

// Call at application startup to ensure only one instance is running.
// If another instance is already running, sends an activation request to it
// and exits the current process.
SingleInstanceManager.EnsureSingleInstance();

// Subscribe to the activation event to bring your window to the foreground
// when another instance tries to start.
SingleInstanceManager.ActivateWindowRequested += (sender, args) =>
{
    // Bring the main window to the front
    mainWindow.Activate();
    mainWindow.WindowState = WindowState.Normal;
};

// Release the lock manually if needed (use with caution)
SingleInstanceManager.ReleaseLock();
6. String Compression
using LuYao.Encoders;
using LuYao;

// LZ-string compression
var compressed = LzString.CompressToBase64("Hello World");
var decompressed = LzString.DecompressFromBase64(compressed);

// GZip compression
var gzipCompressed = GZipString.Compress("Large text data");
var gzipDecompressed = GZipString.Decompress(gzipCompressed);
7. Hosts File Management
using LuYao.IO.Hosts;

// Read and parse hosts file
var hostsFile = HostFile.Read(@"C:\Windows\System32\drivers\etc\hosts");

// Parse from string
var hosts = HostFile.Parse("127.0.0.1 localhost\n192.168.1.1 router");

// Modify and access entries
foreach (var line in hosts.Lines)
{
    if (line is RecordLine record)
    {
        Console.WriteLine($"{record.IPAddress} -> {record.Domain}");
    }
}
8. Fake User Agent
using LuYao.Net.Http.FakeUserAgent;

// Get random user agent
var selector = UserAgentSelector.All;
var userAgent = selector.Random();
Console.WriteLine(userAgent?.UserAgent);

// Filter by criteria
var chromeSelector = UserAgentSelector.Filter(x => x.Browser == "Chrome");
var chromeUA = chromeSelector.Random();
9. Rate Limiting (Token Bucket)
using LuYao.Limiters.TokenBucket;

// Create token bucket limiter
var bucket = TokenBuckets.Builder()
    .WithCapacity(100)
    .WithFixedIntervalRefillStrategy(10, TimeSpan.FromSeconds(1))
    .Build();

// Try to consume tokens
if (bucket.TryConsume(1))
{
    // Process request
}
else
{
    // Rate limit exceeded
}
10. Password Strength Advisor
using LuYao.Security;

var advisor = new PasswordAdvisor();
var score = advisor.CheckStrength("MyP@ssw0rd123");
Console.WriteLine(score); // Strong, Medium, Weak, etc.
11. Text Tokenization and Analysis
using LuYao.Text.Tokenizer;

// Build custom analyzer
var analyzer = new AnalyzerBuilder()
    .WithCharacterFilter(new ToDbcCaseCharacterFilter())
    .WithTokenizer(new StandardTokenizer())
    .WithTokenFilter(new ToLowerCaseTokenFilter())
    .Build();

var tokens = analyzer.Analyze("Hello World!");
12. File and Path Helpers
using LuYao.IO;

// File size formatting
var sizeStr = FileSizeHelper.FormatSize(1024 * 1024); // "1 MB"

// Path utilities
var normalized = PathHelper.NormalizePath(@"C:\Users\..\Documents");

LuYao.Text.Json

JSON Extraction and Processing
using LuYao.Text.Json;

// Extract JSON from mixed content
var text = "Some text before {\"name\":\"John\",\"age\":30} some text after";
var json = JsonHelper.ExtractJson(text, Formatting.Indented);
Console.WriteLine(json); // {"name":"John","age":30}

LuYao.Text.Json.Jint

JavaScript-Powered JSON Transformation
using LuYao.Text.Json;

// Define transformation model with embedded JS
public class MyModel : TranslatableJsonModel
{
    // Implement transformation logic
}

// Use the model for JSON transformation
var model = new MyModel();
// Transform JSON using JavaScript

Building from Source

# Clone the repository
git clone https://github.com/coderbusy/luyao-dotnet.git
cd luyao-dotnet

# Build the solution
dotnet build --configuration Release

# Run tests
dotnet test --configuration Release

Running Tests

# Run all tests
dotnet test

# Run specific test project
dotnet test tests/LuYao.Common.UnitTests/LuYao.Common.UnitTests.csproj

Contributing

We welcome contributions! Please feel free to:

  • Report bugs or request features via Issues
  • Submit pull requests with improvements
  • Improve documentation
  • Share your use cases

License

This project is licensed under the MIT License.

Links