CloudLis.Util 1.0.4

CloudLis.Util

用于 .NET 客户端小程序开发的常用工具类。

常用工具类的整合：常见类型的扩展方法，以及汉字信息处理等。

Install

首先需要配置项目 NuGet.config，或者在 NuGet 包管理器增加源：http://nexus.mjiankang.com/repository/nuget-hosted/

配置完成后便可以在程序包管理器控制台输入命令安装：

Install-Package CloudLis.Util

或者直接搜索 CloudLis.Util 进行安装。

Features

• 增加 string 类型扩展方法；
• 增加集合或数组类型扩展方法；
• 增加 DataSet、DataTable、DataRow 等的扩展方法；
• 提供汉字的拼音首码、五笔首码等信息；
• 提供 ini 配置文件读写能力；
• 支持简单的日志管理功能；
• 提供图片的扩展方法，包括反色、获取缩略图等；
• 提供 ASCII 类，提供静态字段获取 ASCII 与 EASCII 中的控制字符；

String 扩展方法

根据业务需要，string 类型添加了一系列扩展方法：

• 判断是否能够转换为值类型；
• 将字符串转换为值类型，可以设置转换失败返回默认值；
• 判断类型是否为可空值类型；
• 将字符串转换为可空值类型，可以设置转换失败返回默认值；
• 判断是否能够转换为常见的一些数据类型；
• 将字符串转换为常见的一些数据类型，可以设置转换失败返回默认值；
• 提供将字符串中控制字符进行转义，或转换为 Unicode 转义字符，同时反转义操作；

判断是否能够转换为值类型

值类型具体包括哪些类型可以参考 MSDN：值类型表（C# 参考）

普通方法调用 IsXXX()

使用 Is + 值类型关键字 的方式调用，例如判断是否可以转换为整型，方法名为 IsInt，当然也支持 IsInt32 写法。

// 用法
bool b = "2".IsInt32();

// 指定可以成功转换时执行一个委托
bool b = "2".IsInt32(action: (i)=> Console.WriteLine(i));

泛型方法调用 Is<XXX>()

为了方便使用，增加了泛型方法的调用。例如判断是否可以转换为日期时间，可以调用 Is<DateTime>()。

另外无论是普通方法，还是泛型方法，都支持了 TryParse() 或 TryParseExact() 方法的入参。（注意，普通方法可以指定格式的方法，方法名带有 Exact）

// 用法
bool b = "190801".Is<DateTime>(format:"yyMMdd");
// 以上等同于下面写法
// bool b = "190801".IsDateTimeExact(format: "yyMMdd");

// 指定可以成功转换时执行一个委托
bool b = "190801".Is<DateTime>(format:"yyMMdd", action: (dt)=> Console.WriteLine(dt.ToString("yyyy-MM-dd")));

将字符串转换为指定的值类型

此类扩展方法的特点是无论是否转换成功都将返回一个值，默认转换失败返回的是该类型的 default 值，该返回值可以指定。

普通方法调用 IsXXX()

使用 To + 值类型关键字 的方式调用，例如将字符串转换为十进制浮点型，方法名为 ToDecimal。

// 用法
decimal d = "0.1".ToDecimal();

// 指定转换失败返回的默认值，不指定失败返回 default(decimal)
decimal d = "< 0.1".ToDecimal(-1);

泛型方法调用 To<XXX>()

为了方便使用，增加了泛型方法的调用。例如判断是否可以转换为枚举，可以调用 To<XXXEnum>()。

// 用法
NumberStyles style = "none".To<NumberStyles>(ignoreCase: true);

// 指定转换失败返回的默认值，不指定失败返回 default(NumberStyles)
NumberStyles style = "Error".To<NumberStyles>(NumberStyles.None);

// 注意：枚举类型比较特殊，普通方法转换时也需要通过泛型参数指定枚举类型
NumberStyles style = "none".ToEnum<NumberStyles>(ignoreCase: true);

转换为可空类型

以上方法在字符串为 null 时，将无法进行转换，而在写数据库访问层或书写业务层代码时，又经常使用到可空类型的转换，所以这里给出对应的扩展，方便调用。

// 将字符串转换为特定可空值类型，可以指定转换失败默认值
long? l = ((string)null).ToNullable<long>(def: null);

// 判断是否为特定的可空类型，如果为空或转换成功可以分别再执行特定方法
bool b = ((string)null).IsNullable<long>(action: (n) => Console.WriteLine("转换成功：{0}", n)
            , isNullAction: () => Console.WriteLine("字符串为空"));

其他类型的扩展

除值类型的转换外，还提供了几种常见引用类型的转换，使用方法和值类型的转换基本一致，这里不再赘述。

• Base64 转字节数组：调用 GetBytesFromBase64String() 方法；
• HEX 转字节数组：调用 GetBytesFromHexString() 方法；
• Version：程序集、操作系统或公共语言运行时的版本号；
• IPAddress：Internet 协议 (IP) 地址；
• Encoding：字符编码，支持 ANSI；
• ……：其他支持类型是否支持可以通过调用 IsAllowConvertType 方法判断。

字符串一些静态方法与正则的扩展

为了方便调用，扩展了字符串是否为空、Format 方法、正则等，当然该扩展有利有弊。

例如默认的 Format 与正则方法，书写时在 Visual Studio 中对于正则的内容或 Format 参数匹配会给出提示，但是扩展方法就无法支持。

但是扩展方法书写更简单，而且不用特意的引用命名空间，如果不想放弃 IDE 的提示信息，建议还是使用原有的写法。

增加 Length 方法

默认与 Length 属性一致，区别在于入参可以指定编码 Encoding，返回字符串的字节长度。

string s = "张三";
int length1 = s.Length();
int length2 = s.Length(Encoding.UTF8);

常用静态方法扩展

Format、IsNullOrEmpty、IsNullOrWhiteSpace 方法。

// Format 方法
string s = "My name is {0}, I'm come from {1}.";
string content = s.Format("Kangkang", "China");

// null、空字符串等的判断
bool b1 = "".IsNullOrEmpty();
bool b2 = " \t\r\n ".IsNullOrWhiteSpace();

正则

支持正则的匹配、提取、替换、拆分方法，对应方法为 IsMatch、Match 与 Matches、RegexReplace、RegexSplit。

// 匹配并指定开始的位置
bool isMatch = "ABC123".IsMatch("[A-Z]", startat: 3);

// 拆分并指定拆分次数
string[] array = "1A2B3".RegexSplit("[A-Z]", count: 2);

反序列化

如果字符串内容为 Json 数据，可以调用 Deserialize 方法进行反序列化。

该实现实际使用的是 Newtonsoft.Json 包，所以入参没有区别，可以直接和平时使用 JsonConvert.DeserializeObject 方法一样使用。

转义与反转义

提供将控制字符转换为可读的内容：

// <ACK>
string explain1 = "\x06".Explain(ExplainStyles.Name);

// <06>
string explain2 = "\x06".Explain(ExplainStyles.Hex);

// \u0006
string explain3 = "\x06".Escape();

同时允许用户反向操作：

// 以下返回均为 \x06
string str1 = "<ACK>".Unexplain(ExplainStyles.Name);
string str2 = "<06>".Unexplain(ExplainStyles.Hex);
string str4 = "\\x06".Unescape();
string str3 = "\\u0006".Unescape();

以上均支持长字符串，如果其中夹带有控制字符，会匹配替换。

控制字符可以参考提供的 ASCII 类型的静态字段，其中包括了 ASCII 与 EASCII 中所有的控制字符。<br> 例如，如果要输出 \x06，可以使用 ASCII.ACK。

DataSet 等类型扩展方法

因为实现的类型比较多与杂，所以这里列举一些已经实现的常用类型的扩展方法。

DataSet、DataTable、DataRow

支持判断是否为空，或无数据，可以调用 IsNullOrEmpty 方法：

DataSet set = new DataSet();
bool isEmpty = set.IsNullOrEmpty(); // true

DataTable table = null;
isEmpty = table.IsNullOrEmpty(); // true

支持将数据转换为实体或 dynamic：

DataTable table = new DataTable();

var data = table.ToDynamic();
var list = table.ToEntity<Person>();
if(!table.IsNullOrEmpty())
{
    var person = table.Rows[0].ToEntity<Person>();
}

object

为了避免对基类型有太多侵入，这里对 object 类型只是酌情添加了 ToJson 的序列化方法。

Entity

为实体类增加了向 DataTable 的转换方法。

Person person = new Person
{
    Name = "Kangkang",
    Sex = "M",
}
var list = new List<Person>(){ person };

DataTable table1 = person.ToTable();
DataTable table2 = list.ToTable();

IEnumerable

为可以迭代的类型提供判断是否为空或没有元素的 IsNullOrEmpty 方法。

int[] array = null;
var list = new List<int>();
array.IsNullOrEmpty(); // true
list.IsNullOrEmpty(); // true

Image

提供了常用的图片操作：

• GetBytes：获取图片内容的字节数组，方便保存或上传；
• InvertColors：获取反色图片，效果类似画图工具中 Ctrl + Shfit + i；
• GetThumbnail：获取图片缩略图，默认获取与原始大小相等的缩略图，可以视为压缩图片，指定宽高后会根据设置的宽高生成缩略图；
• GetRawFormat：获取该图片格式对应在 ImageFormat 内置的原始类型；
• GetExtension：获取图片格式对应的后缀名，例如 JPEG 返回 .jpg；

ini 配置文件读写能力

如果只是读写自定义的配置，不考虑节点等信息，可以使用 Config.Default。

可以使用 SetValue 设置配置项内容：

Config.Default.SetValue<string>("文本", "测试");
Config.Default.SetValue(typeof(int), "数组", new int[]{ 1, 2, 3 });

可以使用 GetValue 或 GetValueArray 获取设置的配置项内容，例如：

var text = Config.Default.GetValue<string>("文本");
var list = Config.Default.GetValueArray<int>("数组")

如果用于初始化，可以使用 GetValue 赋予默认值，系统会自动生成配置文件，并赋予默认值。

var text = Config.Default.GetValue("文本", "测试");
var list = Config.Default.GetValueArray("数组", new[]{ 1, 2, 3 })

另外如果需要监控日志的修改，可以使用 ModifiedConfig 事件。

以上内容会读写程序根目录的 Config.ini 文件，如果不存在会生成该文件。

如果需要读写其他 ini 配置文件，可以使用 CloudLis.Util.SharpConfig.Configuration 类型。

日志管理

内部实现了一个简单的日志读写功能，用户可以简单设置后直接使用。

Logger.Default.Trace("跟踪");
Logger.Default.Debug("调试");
Logger.Default.Info("消息");
Logger.Default.Warn("警告");
Logger.Default.Error("错误");
Logger.Default.Fatal("致命");

可以通过设置 LogType 设置输出日志的方式，默认为文件与自定义事件。

可以通过设置 LogLevel 设置输出日志的级别，默认为 All。

公共字段 Logs 可以获取所有已经输出的日志内容，也可以进行管理。

如果想监听日志的输出，自定义实现输出方式，可以绑定到 LogEventHandler 事件。

需要注意的是，以上的日志输出均为同步方法，没有实现异步，但是已经实现的方法都有加锁，不用担心线程安全问题，但是如果自定义实现，需要自己解决线程安全问题。