Euonia.Concurrency.FileSystem 2026.5.0

dotnet add package Euonia.Concurrency.FileSystem --version 2026.5.0
                    
NuGet\Install-Package Euonia.Concurrency.FileSystem -Version 2026.5.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Euonia.Concurrency.FileSystem" Version="2026.5.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Euonia.Concurrency.FileSystem" Version="2026.5.0" />
                    
Directory.Packages.props
<PackageReference Include="Euonia.Concurrency.FileSystem" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Euonia.Concurrency.FileSystem --version 2026.5.0
                    
#r "nuget: Euonia.Concurrency.FileSystem, 2026.5.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Euonia.Concurrency.FileSystem@2026.5.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Euonia.Concurrency.FileSystem&version=2026.5.0
                    
Install as a Cake Addin
#tool nuget:?package=Euonia.Concurrency.FileSystem&version=2026.5.0
                    
Install as a Cake Tool

Euonia.Concurrency.FileSystem

Euonia 分布式同步的文件系统提供程序:以目录中的锁文件实现跨进程互斥,适用于单机多进程或已挂载共享卷的场景,无需额外基础设施。

  • 目标框架:net10.0、net11.0
  • 根命名空间:Nerosoft.Euonia.Concurrency.FileSystem
  • NuGet 包:Euonia.Concurrency.FileSystem
  • 依赖:Euonia.Concurrency、Euonia.Modularity
  • 配置节:FileSynchronization

安装

dotnet add package Euonia.Concurrency.FileSystem

快速开始

配置锁目录(FileSystemLockModule 会自动绑定该配置节):

{
  "FileSynchronization": {
    "Directory": "/var/lib/myapp/locks"
  }
}

环境变量(两种写法等价,仓库 alias 见 Euonia.Modularity):

export FileSynchronization__Directory=/var/lib/myapp/locks   # .NET 原生:双下划线表示层级
export FILESYNCHRONIZATION_DIRECTORY=/var/lib/myapp/locks    # 仓库 alias:大写单下划线

也可在代码中覆盖(显式 Configure 优先于配置节):

using Nerosoft.Euonia.Concurrency.FileSystem;

services.Configure<FileSynchronizationOptions>(options =>
{
    options.Directory = "/var/lib/myapp/locks";
});

声明模块依赖:

using Nerosoft.Euonia.Concurrency.FileSystem;
using Nerosoft.Euonia.Modularity;

[DependsOn(typeof(FileSystemLockModule))]
public sealed class WorkerModule : ModuleContextBase
{
}

使用锁:

public sealed class SchedulerService(ILockFactory lockFactory)
{
    public async Task RunAsync(CancellationToken cancellationToken)
    {
        var locker = lockFactory.Create("nightly-job");
        await using var handle = await locker.TryAcquireAsync(TimeSpan.Zero, cancellationToken);
        if (handle is null)
        {
            return; // 其他进程正在执行
        }

        // 独占执行
    }
}

主要功能

  • 文件锁:FileSystemLockModule 注册 ILockFactory,由 FileSynchronizationFactory 创建 FileLockProvider。
  • 自动建目录:获取锁时若目录不存在会自动创建;创建目录失败时抛出带目录信息的 InvalidOperationException。
  • 跨进程互斥:以 FileShare.None 独占打开锁文件;进程退出时操作系统关闭句柄并删除文件。
  • 可移植文件名:锁名称被转换为“安全前缀 + Base32 哈希 + .lock”,避免特殊字符与大小写差异。
  • 轻量无依赖:不需要 Redis、ZooKeeper 或数据库。

核心类型

类型 作用
FileSystemLockModule 注册 ILockFactory 的模块
FileSynchronizationFactory 基于 DirectoryInfo 创建锁提供程序
FileLockProvider / FileSynchronizationHandle 文件锁实现与句柄
FileSynchronizationOptions 同步目录配置(Directory)

配置项

配置键 类型 默认值 说明
FileSynchronization:Directory string 无(必填) 锁文件目录;不存在时在获取锁时创建
{
  "FileSynchronization": {
    "Directory": "/var/lib/myapp/locks"
  }
}
FileSynchronization__Directory=/var/lib/myapp/locks    # .NET 原生
FILESYNCHRONIZATION_DIRECTORY=/var/lib/myapp/locks     # 仓库 alias

注意事项 / 限制

  • 未配置目录会失败:Directory 为空时,创建 ILockFactory 会抛 InvalidOperationException,错误信息中给出配置键与环境变量名。
  • 仅提供锁:本包不实现 ISemaphoreFactory;需要信号量请使用 Redis 或 ZooKeeper 提供程序。
  • 跨主机依赖文件系统语义:FileShare.None 在本地文件系统可靠,但在 NFS/SMB 等网络卷上是否具备原子互斥取决于服务端实现,跨主机强互斥应先验证。
  • 忙等待参数不可配置:竞争时固定以 50ms–1s 的随机间隔重试;锁文件被长期占用时等待方会持续轮询。
  • 锁文件是临时的:释放(或进程退出)时文件被删除;不要依赖锁文件中的内容,它只是互斥标记。

相关包

常见问题与故障排查

InvalidOperationException: FileSynchronizationOptions.Directory is not configured

原因:模块没有绑定到目录:配置节/环境变量/显式 Configure 都为空,或模块没有随应用加载。 解决:设置 FileSynchronization:Directory 或 FileSynchronization__Directory,或在 services.Configure<FileSynchronizationOptions> 中赋值;确保声明了 [DependsOn(typeof(FileSystemLockModule))]。

获取锁时抛 UnauthorizedAccessException

原因:进程账号对目录或锁文件没有写权限;目录可能由其他用户创建。 解决:用运行账号检查 Directory 的读写权限;在容器中挂载可写卷;确认不是只读文件系统。

InvalidOperationException: ... because it is already the name of a directory

原因:清理后的锁文件路径恰好是一个已存在目录(通常是手工创建的目录占用了名称)。 解决:换一个专用且空的锁目录,或移除与锁文件同名的目录;不要手工在锁目录中创建同名文件/目录。

跨主机部署时锁偶尔失效

原因:FileShare.None 在 NFS/SMB 等网络文件系统上的原子性取决于服务端实现与挂载参数,不能等同于本地磁盘。 解决:跨主机强互斥改用 Redis/ZooKeeper/Azure;若必须共享卷,先在目标环境做并发抢占验证并固定挂载选项。

注入 ISemaphoreFactory 失败

原因:本包只实现 ILockFactory,没有信号量实现。 解决:需要并发限流时改用 Euonia.Concurrency.Redis 或 Euonia.Concurrency.ZooKeeper 的信号量模块。

最佳实践

  • 专用目录:每个应用/环境使用独立的绝对路径目录,避免不同服务互相清理锁文件。
  • 确保可写且持久:目录对运行账号可写;容器部署使用持久卷而不是临时层。
  • 锁名带前缀:使用 {app}:{resource}:{id} 形式,名称会哈希成可移植文件名,避免特殊字符与大小写差异。
  • 短临界区:竞争时以 50ms–1s 随机退避轮询,长任务会持续占用等待者;把耗时工作移到锁外。
  • 监控失败率:持续出现权限异常或等待超时通常意味着目录权限/网络卷语义问题,应告警而不是无限重试。

版本与兼容

  • 目标框架:net10.0、net11.0;仓库统一包版本 2026.5.0(project.props)。
  • 关键依赖:Euonia.Concurrency、Euonia.Modularity;不需要额外基础设施。
  • 已知边界:仅锁、无信号量;忙等待固定 50ms–1s;UnauthorizedAccessException 最多重试 400 次;文件名使用“安全前缀 + Base32 哈希 + .lock”,极长路径可能抛 PathTooLongException。
  • 升级注意:锁文件在释放时删除,不承载数据,无需迁移;升级后保持 Directory 与锁名不变即可继续互斥。

许可证

本项目依据仓库根目录的 GNU General Public License v3.0 发布。

Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed.  net11.0 is compatible. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
2026.5.0 92 11/13/2026
2026.4.7 101 11/3/2026
2026.4.6 108 10/28/2026
2026.4.5 103 10/19/2026
2026.4.4 95 10/19/2026
2026.4.3 118 10/1/2026
2026.4.1 112 9/24/2026
2026.4.0 107 9/22/2026
2026.3.16 136 9/8/2026
2026.3.15 126 9/2/2026
2026.3.14 136 8/30/2026
2026.3.13 127 8/29/2026
2026.3.12 129 8/28/2026
2026.3.11 129 8/27/2026
2026.3.10 124 8/26/2026
2026.3.9 130 8/25/2026
2026.3.8 131 8/24/2026
2026.3.7 125 8/20/2026
2026.3.6 127 8/20/2026
2026.3.5 123 8/19/2026
Loading failed