# Viyi.Util

**Repository Path**: jamesfancy/Viyi.Util

## Basic Information

- **Project Name**: Viyi.Util
- **Description**: .NET 的数据格式处理和数据转换工具
- **Primary Language**: C#
- **License**: MulanPSL-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 25
- **Forks**: 3
- **Created**: 2015-03-19
- **Last Updated**: 2026-03-03

## Categories & Tags

**Categories**: utils

**Tags**: None

## README

# Viyi.Util - .NET 的常用工具扩展

Viyi.Util v2 对该工具库进行了完全重写，**不完全**兼容 v1。

v2 参考其它现代高级语言、类库和日常使用的情况，提供一些常见的工具函数和工具类，以 C# 的“扩展函数”作为主要实现形式，也包含一些 Helper 静态类和其他工具类。

> ###### 其他相关类库
>
> Viyi.Util 包含内容较多，依赖项也较多，部分功能已经分离出去，按功能分解成一些小工具库
>
> - [Viyi.Strings](https://gitee.com/jamesfancy/Viyi.Strings) 专注于扩展字符串相关的功能和工具函数
> - [Viyi.Bytes](https://gitee.com/jamesfancy/Viyi.Bytes) 专注于扩展二进制相关的功能和工具函数

## 获取

Viyi.Util 通过 [NuGet](https://www.nuget.org/packages/Viyi.Util/) 发布。

在 [Visual Studio 包管理器控制台](https://docs.microsoft.com/nuget/consume-packages/install-use-packages-powershell) 中运行下面的命令获取：

```
PM> Install-Package Viyi.Util
```

或者在 [管理 NuGet 程序包对话框](https://docs.microsoft.com/nuget/consume-packages/install-use-packages-visual-studio) 中安装。

## 主要特性 (Features)

- 扩展 `object`，

    - 参考 Kotlin，提供了 `.Also()` 和 `.Let()` 扩展，同时支持它们的异步版本；
    - 提供 `ToXxxx()`  和 `ConvertTo()` 方法，是 `System.Convert` 类中相关功能的免异常封装；
    - 提供 `As()` 方法弥补 `as` 关键字不能应用于结构体 (struct) 类型的问题；

- 扩展 Linq (`Enumerable`)，

    - 提供 `ForEach()` / `ForEachAsync` 扩展；
        > 注：Viyi.Util 目前不支持 `IAsyncEnumerable`，请使用 [System.Linq.Async](https://www.nuget.org/packages/System.Linq.Async)。
    - 提供 `AsToArray()` 和 `AsToList()` 先尝试 as 操作，最大避免重新生成数组或列表对象。由于它可能返回源数组或列表，所以使用时需要充分考虑到对结果数组或列表的变更可能产生的别作用。

    - 为 .NET Standard 2.0 提供 `MaxBy()` 和 `MinBy()`；
    - 为 `List<T>` 和 `T[]` 分别提供 `Shuffle()` 扩展用来打乱其内部元素的顺序；
    - `ViyiEnumerable<T>.Of(params T[])` 从一组单个对象创建 `IEnumerable<T>`；

- 对部分包装类型提供 `Map` 功能

	- `R? Map<T>(T?)` 对可空类型进行映射，兼容 class 和 struct。
	- `R Map<T>(Task<T>)` 可以将 `Task<T>` 映射成 `Task<R>`
	- `Task<T?> Unwrap<T>(Task<T>?)`，常用于链式调用

- 扩展 `boolean`

    - `it.Then()`，`if / if ... else ...` 的表达式形式；
    - `it.Else()`，`if not` 的表达式形式；
    - `it.Then(fnThen, fnElse)`，` ? : ` 的函数调用形式；
    
- `ViyiRandom` 提供随机数工具

    - `ViyiRandom.Create()` 创建随机数据发生器 (`Random`)
        在 .NET 6 和 .NET 8 中使用 `Random.Shared` 来产生随机种子，在 .NET Standard 2.0 中使用类似的方式，通过一个静态且线程安全的 `Random` 对象来产生随机种子。
    - `ViyiRandom.RandomIndexes()` 产生一组以 `0` 开始的随机序数，可用于产生顺序随机的数据
    - 使用 C# 14 提供的扩展块语法为 .NET Standard 2.0 的 Random 添加 `Random.Shared`。

- 扩展 `DateTime` 和 `DateTimeOffset`

	- `DateTime.ToDateTimeOffset(TimeSpan)` 转换成 `DateTimeOffset`。`new DateTimeOffset(DateTime, TimeSpan)`  会因为 `TimeSpan` 和 `DateTimeKind` 不匹配抛异常，但 `DateTime.ToDateTimeOffset(TimeSpan)` 会按 `TimeSpan` 强制转换（忽略 `DateTime` 的时区），或者在有 `Kind` 时按 `Kind` 转换。
	- 提供 `ToRfc3399String()` 方法。虽然 `ToString("O")` 类似，但毕竟不是。
	- `DateTimeOffset.StartOfDay`，扩展属性，表示当天 0 点的的 `DateTimeOffset`。
	- `DateTimeOffset.SpecifyOffset(TimeSpan)` 保留日期时间字面值，同时改变时区。注意与 `ToOffset(TimeSpan)` 的区别，后者会计算时间字面值以保持实际时间值不变。

- `EnumHelper` 为枚举类型提供工具方法

    - `EnumHelper.EnumerateWith()` 将枚举中定义的枚举值转换为指定对象的 `IEnumerable`；
    - `EnumHelper.GetDescription()` 获取枚举值的 [`DescriptionAttribute`][description_attribute] 描述信息；
    - `EnumHelper.EnumerateWithDescription()` 与 `EnumerateWith()`类似，但会去分析 [`DescriptionAttribute`][description_attribute] 属性，结果保存在 `EnumEntry` 对象中；
    - `EnumHelper.Enumerate()` 得到 `IEnumerable<KeyValuePair>`；
    - `EnumHelper.ToNameValueCollection()` 得到 `NameValueCollection`（可通过参数交换 Key-Value）

- 对 Compare 和 Equality 的支持

    - `LambdaCompare` 可以通过 Lambda 来产生 `IComparer<T>` 对象，避免定义类；
    - `LambdaEqualityComparer` 通过 Lambda 产生 `IEqualityComparer<T>` 对象，避免定义类；

- 其它工具

    会根据 [Issue](https://gitee.com/jamesfancy/Viyi.Util/issues) 进行分析、确认并完成实现。

## 目标框架

- [.NET 10](https://dotnet.microsoft.com/zh-cn/download/dotnet/10.0)
- [.NET 8](https://dotnet.microsoft.com/zh-cn/download/dotnet/8.0)
- [.NET 6](https://dotnet.microsoft.com/download/dotnet/6.0)（v2.2 之前，不含 v2.2）
- [.NET Standard 2.0](https://docs.microsoft.com/dotnet/standard/net-standard?tabs=net-standard-2-0)
## 文档

- 阅读 `README.md` 对 Viyi.Util 的功能进行大致地了解。
- [WIKI](https://gitee.com/jamesfancy/Viyi.Util/wikis/) 中对部分功能进行了说明。
- 阅读源代码，大部分工具类方法的源代码非常简洁。
## License

[木兰宽松许可证，第2版 (MulanPSL2)](http://license.coscl.org.cn/MulanPSL2/)

> ###### 注：
>
> Viyi.Util `v1.x` 使用 MIT，从 `v2.0` 开始变更为 MulanPSL2



[description_attribute]: https://docs.microsoft.com//dotnet/api/system.componentmodel.descriptionattribute