每一个有想法的程序员，都会有自己的一系列收藏xxxHelper/xxxUtility。

X组件遵循宁缺毋滥的原则，只封装最为必要的助手类。

Nuget包：NewLife.Core

源码：https://github.com/NewLifeX/X/blob/master/NewLife.Core/Common/Utility.cs

视频：https://www.bilibili.com/video/BV1gq4y1g78w

视频：https://www.bilibili.com/video/BV15T411N74g


概述

Utility是X组件最常用的帮助类，引用几百上千次，位于System命名空间。

Utility采用静态类扩展Object方式提供服务，内部默认实现 DefaultConvert，可重载修改逻辑，赋值覆盖 Utility.Convert 属性。


大部分转换方法带有defaultValue参数，在转换失败时不会抛出异常，而是返回默认值！


整型ToInt

最常用的类型转换，没有之一，特别在web开发场景。

主要功能点：

  1. 字符串转整数，支持全角数字，可过滤掉逗号记数法中的逗号
  2. 字符串数组取第一项转数字，网页表单同名字段提交时，服务端取值得到StringValues就是一个字符串数组
  3. 时间日期转整数，转Unix秒，也就是1970年以来总秒数，不考虑时区，如有需要先转UTC时区再用ToInt
  4. 时间点转整数，也是转Unix秒，但是带时区，支持UTC
  5. 字节数组转整数，默认小字节序 BitConverter.ToInt32，常用于协议解析
  6. 通用版 Convert.ToInt32，异常时返回默认值


强烈推荐，web开发时使用-1作为默认值，因为很多时候0具有业务意义。

如：var userId=p["userId"].ToInt(-1)，如果userId为-1，表示没有传递该参数，且可以接收 userId=0 的参数。

跨系统调用时，常常把时间转UTC时间再转为Unix秒传递，如：DateTime.UtcNow.ToInt()。


长整型ToLong

常用的类型转换，特别在web开发场景。

主要功能点：

  1. 字符串转整数，支持全角数字，可过滤掉逗号记数法中的逗号
  2. 字符串数组取第一项转数字，网页表单同名字段提交时，服务端取值得到StringValues就是一个字符串数组
  3. 时间日期转长整数，转Unix毫秒，也就是1970年以来总毫秒数，不考虑时区，如有需要先转UTC时区再用ToLong
  4. 时间点转整数，也是转Unix毫秒，但是带时区，支持UTC
  5. 字节数组转整数，默认小字节序 BitConverter.ToInt64，常用于协议解析
  6. 通用版 Convert.ToInt64，异常时返回默认值

物联网数据采集时，常取当前UTC时间转为Unix毫秒，避免不同终端设备时区不一致所带来的问题。

如：DateTime.UtcNow.ToLong()。

浮点数ToDouble

只有双精度浮点数，需要单精度浮点数时，可以解析双精度后再强转为单精度。

主要功能点：

  1. 字符串转浮点数，支持全角数字
  2. 字符串数组取第一项转数字，网页表单同名字段提交时，服务端取值得到StringValues就是一个字符串数组
  3. 字节数组转浮点数，默认小字节序，BitConverter.ToDouble
  4. 通用版 Convert.ToDouble，异常时返回默认值


十进制数ToDecimal

Decimal常用于表示金额，避免精度丢失。

主要功能点：

  1. 字符串转浮点数，支持全角数字
  2. 字符串数组取第一项转数字，网页表单同名字段提交时，服务端取值得到StringValues就是一个字符串数组
  3. 字节数组转浮点数，默认小字节序，BitConverter.ToDecimal
  4. 通用版 Convert.ToDecimal，异常时返回默认值


布尔型ToBoolean

任意对象转为布尔型，主要是对true/false字符串的支持

主要功能：

  1. 字符串转布尔型，特别支持true/false字符串，支持全角数字，非零数字为true
  2. 字符串数组取第一项转布尔型，网页表单同名字段提交时，服务端取值得到StringValues就是一个字符串数组
  3. 通用版 Convert.ToBoolean，异常时返回默认值


推荐web开发中用可空类型，得到true/false之外的第三种状态，null表示未提交该参数，如下：

Boolean? enable = p["enable"]?.ToBoolean();


时间日期ToDateTime/ToFullString

由于时间日期的字符串表示方式在全球没有统一，即使在中国也有很多种写法，因此这块特别常用。

在X组件内，时间日期的标准格式是：yyyy-MM-dd HH:mm:ss，标准默认值是：DateTime.MinValue

ToDateTime主要功能：

  1. 字符串转时间日期，支持UTC，支持格式 yyyy-M-d 、 yyyy/M/d 、 yyyyMMddHHmmss 、 yyyyMMdd
  2. 字符串数组取第一项转时间，网页表单同名字段提交时，服务端取值得到StringValues就是一个字符串数组
  3. 整型转时间日期，Unix秒，1970年以来秒数，不支持时区
  4. 长整型转时间日期，Unix毫秒，1970年以来毫秒数，不支持时区，如果小于100年，则使用Unix秒
  5. 通用版 Convert.ToDateTime，异常时返回默认值


ToFullString主要功能：最高性能把时间日期转为yyyy-MM-dd HH:mm:ss字符串，支持UTC。

普通的DateTime.ToString(format)在千万级次数时有性能问题。

emptyValue参数用于只是时间为最小值时的返回值，在web中一般使用String.Empty，即时间为最小值时返回空字符串，避免显示 0001-01-01 00:00:00 的时间。

Unix秒或Unix毫秒转时间日期时，一定要注意双方约定的是UTC时间还是当前时间。因为不同开发者有不同的使用习惯，实际上更多习惯使用UTC时间的Unix毫秒。

强烈反对使用字符串传递时间日期类型数据，推荐使用Unix毫秒来传递时间，如：time.ToLong()。

字符串表示时间日期会遇到格式不一致问题，特别是不同Json库的表示也不尽相同。


时间点ToDateTimeOffset/ToFullString

时间点DateTimeOffset比DateTime多了一个时区偏移量，因此全部支持UTC时区。

在X组件内部，时间日期的标准格式是：yyyy-MM-dd HH:mm:ss +08:00，标准默认值是：DateTimeOffset.MinValue

ToDateTime主要功能：

  1. 字符串转时间点，支持时区，支持格式 yyyy-M-d 、 yyyy/M/d 、 yyyyMMddHHmmss 、 yyyyMMdd
  2. 字符串数组取第一项转时间，网页表单同名字段提交时，服务端取值得到StringValues就是一个字符串数组
  3. 整型转时间点，Unix秒，1970年以来秒数
  4. 长整型转时间点，Unix毫秒，1970年以来毫秒数，如果小于100年，则使用Unix秒
  5. 通用版 Convert.ToDateTime，异常时返回默认值


ToFullString主要功能：最高性能把时间日期转为yyyy-MM-dd HH:mm:ss +08:00字符串，支持UTC。

普通的DateTimeOffset.ToString(format)在千万级次数时有性能问题。

emptyValue参数用于只是时间为最小值时的返回值，在web中一般使用String.Empty，即时间为最小值时返回空字符串，避免显示 0001-01-01 00:00:00 的时间。


时间截取Trim

时间日期DateTime类型由年月日时分秒毫秒微秒组成，各种转换以后，不好做相等对比。此时可以借助Trim把较小部分截取掉再进行对比。

例如：if( time.ToInt().ToDatetime() == time.Trim("s")) ，时间time转为整数后再转时间，会丢失秒以下的精度，直接跟time做相等比较会失败，而time截取到秒位置就可以比较了。

Trim支持：us / ms / s / m / h。


字节单位ToGMK

常用到字节转KMGTPE等转换，ToGMK用于把长整型转为所能表示的最高级别单位。如10240字节的ToGMK返回“10k”。

魔方的ItemType支持GMK，列表页和表单将把长整型显示为“1.23M”等形式。


异常处理GetTrue/GetMessage

GetTrue用于提起最内层异常对象，支持AggregateException、TargetInvocationException、TypeInitializationException。

GetMessage用于简化Exception.ToString()得到的调用栈信息，特别是异步编程中出现的大量价值不大的调用栈行信息。