LintFile.Android 1.0.2

LintFile (.NET 版)

一个适用于 .NET(Android) 平台的安卓文件操作库,由 Kotlin 版 LintFile 移植而来。

在 .NET 环境下提供与 Kotlin 版一致的文件访问能力:支持 System.IO 直访、SAF(Storage Access Framework) 与 Shizuku 三种模式,可访问 /storage/emulated/0/Android/data(含任意应用的私有目录),并内置自动化权限申请流程。

特性

• 适配 Android 7.0~16,使用方式与 java.io.File 类似
• 支持 Shizuku 文件操作与 Shizuku 打开文件操作流(一次性进程管道,零宽连接符绕过 FUSE 拦截)
• 高性能 Shizuku 批量操作:一次 shell 调用返回整目录的名称/大小/修改时间/类型
• 支持通过 SAF 框架访问受限目录,持久化授权自动记录
• 智能路径检测:自动判断读写能力并选择最优文件操作模式
• 自动化权限申请(Use() 权限安全作用域)
• 支持递归删除目录树与批量获取目录属性
• 核心逻辑跨端可复用(LintFile.Core 不依赖 Android API,桌面端可接任意 shell 执行器)

项目结构

LintFile-.NET/
├── src/
│   ├── LintFile.Core/       net10.0 — LintFile 抽象、DefaultFile/ShizukuFile 实现、路径与 shell 解析纯逻辑
│   ├── LintFile.Android/    net10.0-android — Shizuku 桥接 / SAF / 权限流程(自动合并 manifest)
│   └── LintFile.Demo/       MAUI 联调示例 app
├── tests/LintFile.Tests/    47 个单元测试(xUnit)
└── NOTICE.md / LICENSE      LGPL v2.1 衍生作品声明

使用

1. 引用 NuGet 包

<PackageReference Include="LintFile.Android" Version="1.0.0" />

LintFile.Core 会作为依赖自动引入。库的 AAR 依赖与 AndroidManifest(存储权限 + ShizukuProvider)会在构建时自动合并,使用方无需手动配置。

2. 初始化

// NORMAL 模式
LintFileAndroid.Init(ApplicationContext, new LintFileConfig { IoModel = IoModel.Normal });

// SHIZUKU 模式(可访问任意应用的 /Android/data 私有目录)
LintFileAndroid.Init(ApplicationContext, new LintFileConfig { IoModel = IoModel.Shizuku });
if (!ShizukuBridge.IsShizukuAvailable())
    ShizukuBridge.RequestPermission();

3. 文件操作

var file = LintFiles.File("/storage/emulated/0/Android/data");

// 与 java.io.File 一致的语义
file.Exists(); file.IsDirectory(); file.List();
file.RenameTo(dest); file.Delete(); file.DeleteRecursively();

// 批量获取子项属性(Shizuku 模式一次 shell 调用)
var infos = file.ListFilesWithAttributes();

// 打开流
using var input = file.OpenInputStream();
using var output = file.OpenOutputStream();

4. 权限安全作用域

var file = LintFiles.File("/storage/emulated/0/Android/data/com.example/files/a.txt");
file.Use(
    onRequestPermission: type => /* 按 PermissionType 引导授权(外部存储/所有文件/SAF/Shizuku) */,
    granted: f => /* 权限就绪,可操作 f */);

权限授予完成后重新调用 Use() 即可进入 granted 作用域(授权结果同时通过 ShizukuBridge.PermissionRequestResult 事件回调)。

构建

# 需要: .NET 10 SDK + Android workload、JDK 17+、Android SDK(API 36)
dotnet workload install maui-android
dotnet build LintFile.slnx
dotnet test tests/LintFile.Tests

本机 JDK/Android SDK 路径配置在 Directory.Build.props(参考 Directory.Build.props.example,该文件已被 .gitignore 排除)。

打包发布

dotnet pack src/LintFile.Core    -c Release -o artifacts
dotnet pack src/LintFile.Android -c Release -o artifacts

两个 nupkg 均需发布(LintFile.Android 依赖 LintFile.Core)。

通过 GitHub Actions 发布到 NuGet(Trusted Publishing)

仓库已包含 .github/workflows/publish.yml: 打 v* 标签或手动触发后,自动打包并推送到 NuGet.org(使用 NuGet/login@v1 通过 OIDC 换发临时 API Key,无需任何长期密钥)。

在 NuGet.org 上配置 Trusted Publisher:

1. 登录 nuget.org → 点击右上角用户名 → "受信任的发布"(Trusted Publishers)
2. "添加新的受信任发布策略",填写:
   • 存储库所有者: qbhx224
   • 存储库: LintFile-.NET
   • 工作流文件: publish.yml(仅文件名,不含路径)
   • 环境: 留空
3. 首次发布后策略自动转为永久生效(私有仓库需 7 天内完成首次发布)

注意: 若 LintFile.Core / LintFile.Android 包 ID 已被他人占用, 首次发布时 nuget.org 会提示你验证包所有权。

参考: https://learn.microsoft.com/zh-cn/nuget/nuget-org/trusted-publishing

许可

本项目基于 GNU LGPL v2.1 许可证,由 Kotlin 版 LintFile 移植而来,衍生作品声明见 NOTICE.md。