Skip to content

Commit 5d91979

Browse files
LinlcccLinlccc
committed
Complete README
1 parent ef5c453 commit 5d91979

3 files changed

Lines changed: 365 additions & 10 deletions

File tree

‎AutoLaunch.slnx‎

Lines changed: 3 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,10 @@
11
<Solution>
22
<Folder Name="/files/">
3-
<File Path="README.md"/>
4-
<File Path=".editorconfig"/>
53
<File Path=".gitignore"/>
4+
<File Path=".editorconfig"/>
65
<File Path="Directory.Build.props"/>
6+
<File Path="README.md"/>
7+
<File Path="README-ZH_CN.md"/>
78
</Folder>
89
<Folder Name="/files/docs/">
910
<File Path="docs/dev.md"/>
@@ -14,12 +15,5 @@
1415
<File Path=".github/workflows/push-nuget.yml"/>
1516
<File Path=".github/workflows/release.yml"/>
1617
</Folder>
17-
<Folder Name="/files/github_issue_temp/">
18-
<File Path=".github/ISSUE_TEMPLATE/bug-report.yml"/>
19-
<File Path=".github/ISSUE_TEMPLATE/bug-report-zh.yml"/>
20-
<File Path=".github/ISSUE_TEMPLATE/feature-request.yml"/>
21-
<File Path=".github/ISSUE_TEMPLATE/feature-request-zh.yml"/>
22-
</Folder>
23-
2418
<Project Path="src\AutoLaunch\AutoLaunch.csproj" Type="Classic C#"/>
2519
</Solution>

‎README-ZH_CN.md‎

Lines changed: 182 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,182 @@
1+
# AutoLaunch
2+
3+
<img alt="AutoLaunch" src="https://raw.githubusercontent.com/Linlccc/AutoLaunch/master/docs/icon/icon.png" width="128">
4+
5+
[English](README.md) | 简体中文
6+
7+
[![NuGet Version](https://img.shields.io/nuget/v/AutoLaunch?label=AutoLaunch&logo=dotnet)](https://www.nuget.org/packages/AutoLaunch)
8+
[![NuGet Downloads](https://img.shields.io/nuget/dt/AutoLaunch?label=AutoLaunch)](https://www.nuget.org/packages/AutoLaunch)
9+
[![GitHub License](https://img.shields.io/github/license/Linlccc/AutoLaunch)](https://github.com/Linlccc/AutoLaunch/blob/master/LICENSE)
10+
11+
[AutoLaunch](https://github.com/Linlccc/AutoLaunch) 是一个跨平台的 .NET 库，提供了在 Windows、Linux 和 macOS 系统上实现应用程序和可执行文件自动启动的统一 API。
12+
13+
## ✨ 特性
14+
15+
- 🌍 **跨平台支持**：Windows、Linux、macOS
16+
- 🔧 **多种引擎**：每个平台支持多种实现方式
17+
- 🎯 **易用性**：所有平台使用统一 API
18+
- 🛠 **AOT支持**：完全支持 AOT 与裁剪
19+
- 📦 **零依赖**：不依赖任何第三方库
20+
21+
## 🚚 支持的引擎
22+
23+
### Windows
24+
25+
| 引擎 | 描述 | 权限要求 | 备注 |
26+
|-------------------|-----------|----------|---------------|
27+
| **Registry** | 通过注册表实现 | 普通用户/管理员 | |
28+
| **StartupFolder** | 通过启动文件夹实现 | 普通用户/管理员 | |
29+
| **TaskScheduler** | 通过任务计划实现 | 管理员 | 可启动需要管理员权限的程序 |
30+
31+
### Linux
32+
33+
| 引擎 | 描述 | 权限要求 | 备注 |
34+
|-----------------|------------------------|----------|------------------------|
35+
| **Freedesktop** | 通过 FreeDesktop 规范启动项实现 | 普通用户/管理员 | 需要支持 FreeDesktop 的桌面环境 |
36+
37+
### macOS
38+
39+
| 引擎 | 描述 | 权限要求 | 备注 |
40+
|-----------------|-----------------------|----------|-------------------------------|
41+
| **LaunchAgent** | 通过 Launch Agent 启动项实现 | 普通用户/管理员 | |
42+
| **AppleScript** | 通过登录项启动项实现 | 自动化权限 | 参数只支持 `--hidden`/`--minimize` |
43+
44+
## 📦 安装
45+
46+
dotnet CLI:
47+
48+
```bash
49+
dotnet add package AutoLaunch
50+
```
51+
52+
Package Manager Console:
53+
54+
```powershell
55+
Install-Package AutoLaunch
56+
```
57+
58+
## 🚀 快速开始
59+
60+
所有平台使用统一配置 API
61+
62+
### 基本用法
63+
64+
```csharp
65+
using AutoLaunch;
66+
67+
// 根据当前程序自动配置
68+
var autoLauncher = new AutoLaunchBuilder().Automatic().Build();
69+
70+
// 同步启动
71+
autoLauncher.Enable();
72+
// 同步禁用
73+
autoLauncher.Disable();
74+
// 同步检查是否启用
75+
bool isEnabled = autoLauncher.IsEnabled();
76+
77+
// 异步启动
78+
await autoLauncher.EnableAsync();
79+
// 异步禁用
80+
await autoLauncher.DisableAsync();
81+
// 异步检查是否启用
82+
bool isEnabledAsync = await autoLauncher.IsEnabledAsync();
83+
```
84+
85+
### 自定义配置
86+
87+
```csharp
88+
var autoLauncher = new AutoLaunchBuilder()
89+
.SetAppName("MyApp")
90+
.SetAppPath("/path/to/myapp")
91+
.SetArgs("arg1", "arg2")
92+
.AddArgs("arg3")
93+
.SetWorkScope(WorkScope.CurrentUser) // 配置自启动的工作范围
94+
.SetWindowsEngine(WindowsEngine.Registry) // Windows 下使用注册表方式，在其他平台该配置无效
95+
.SetLinuxEngine(LinuxEngine.Freedesktop) // Linux 下使用 Freedesktop 标准方式，在其他平台该配置无效
96+
.SetMacOSEngine(MacOSEngine.LaunchAgent) // macOS 下使用 AppleScript 方式，在其他平台该配置无效
97+
.SetIdentifiers("com.example.myapp") // macOS 添加 Bundle Identifier
98+
.SetExtraConfigIf(OperatingSystem.IsLinux(), "X-GNOME-Autostart-enabled=true") // 仅在 Linux 下添加额外配置，需要符合 Freedesktop 标准
99+
.SetExtraConfigIf(OperatingSystem.IsMacOS(), "<key>KeepAlive</key><true/>") // 仅在 macOS 下添加额外配置，需要符合 LaunchAgent 标准
100+
.Build();
101+
102+
autoLauncher.Enable();
103+
```
104+
105+
### 安全模式
106+
107+
在安全模式下不会主动抛出异常
108+
109+
```csharp
110+
// 构建安全模式实例
111+
var autoLauncher = new AutoLaunchBuilder().Automatic().BuildSafe();
112+
113+
// 尝试启用，返回 true/false 表示成功/失败
114+
bool success = autoLauncher.TryEnable();
115+
116+
if(!success)
117+
{
118+
// 获取最后一次操作的异常信息
119+
Exception? lastException = autoLauncher.TakeLastException();
120+
if (lastException is PermissionDeniedException) Console.WriteLine("权限被拒绝。");
121+
else Console.WriteLine($"无法启用自动启动: {lastException?.Message}");
122+
}
123+
```
124+
125+
## API 文档
126+
127+
### AutoLaunchBuilder
128+
129+
| 方法 | 描述 |
130+
|-----------------------------------|----------------------------|
131+
| `Automatic()` | 自动配置应用名称和路径 |
132+
| `SetAppName(string)` | 设置应用名称 |
133+
| `SetAppPath(string)` | 设置应用路径 |
134+
| `SetArgs(params string[])` | 设置启动参数 |
135+
| `AddArgs(params string[])` | 添加启动参数 |
136+
| `SetWorkScope(WorkScope)` | 设置作用域（当前用户/所有用户） |
137+
| `SetWindowsEngine(WindowsEngine)` | 设置 Windows 引擎 |
138+
| `SetLinuxEngine(LinuxEngine)` | 设置 Linux 引擎 |
139+
| `SetMacOSEngine(MacOSEngine)` | 设置 macOS 引擎 |
140+
| `SetIdentifiers(params string[])` | 设置标识符（仅 macOS LaunchAgent） |
141+
| `AddIdentifiers(params string[])` | 添加标识符（仅 macOS LaunchAgent） |
142+
| `SetExtraConfig(string)` | 设置额外配置 |
143+
| `SetExtraConfigIf(bool, string)` | 条件设置额外配置 |
144+
| `Build()` | 构建 AutoLauncher 实例 |
145+
| `BuildSafe()` | 构建 SafeAutoLauncher 实例 |
146+
147+
### AutoLauncher 接口
148+
149+
| 方法 | 描述 |
150+
|--------------------|----------|
151+
| `Enable()` | 启用自动启动 |
152+
| `Disable()` | 禁用自动启动 |
153+
| `IsEnabled()` | 检查是否启用 |
154+
| `EnableAsync()` | 异步启用自动启动 |
155+
| `DisableAsync()` | 异步禁用自动启动 |
156+
| `IsEnabledAsync()` | 异步检查是否启用 |
157+
158+
### SafeAutoLauncher 额外方法
159+
160+
| 方法 | 描述 |
161+
|-----------------------|----------------------|
162+
| `TryEnable()` | 尝试启用，返回成功/失败 |
163+
| `TryDisable()` | 尝试禁用，返回成功/失败 |
164+
| `TryIsEnabled()` | 尝试检查状态，返回 (成功, 启用状态) |
165+
| `TryEnableAsync()` | 异步尝试启用 |
166+
| `TryDisableAsync()` | 异步尝试禁用 |
167+
| `TryIsEnabledAsync()` | 异步尝试检查状态 |
168+
| `TakeLastException()` | 获取最后一次操作的异常 |
169+
170+
## ⚠️ 异常类型
171+
172+
| 异常 | 描述 |
173+
|------------------------------|----------|
174+
| `AutoLaunchException` | 基础异常类 |
175+
| `AutoLaunchBuilderException` | 构建器配置错误 |
176+
| `UnsupportedOSException` | 不支持的操作系统 |
177+
| `PermissionDeniedException` | 权限被拒绝 |
178+
| `ExecuteCommandException` | 命令执行失败 |
179+
180+
## 📜 许可证
181+
182+
根据 [MIT](LICENSE) 许可证的条款。

‎README.md‎

Lines changed: 180 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,182 @@
11
# AutoLaunch
22

3-
[AutoLaunch](https://github.com/Linlccc/AutoLaunch) provides a cross-platform(Windows, Linux, and macOS) feature for automatically launching applications or executable files at login, suitable for .NET.
3+
<img alt="AutoLaunch" src="https://raw.githubusercontent.com/Linlccc/AutoLaunch/master/docs/icon/icon.png" width="128">
4+
5+
English | [简体中文](README-ZH_CN.md)
6+
7+
[![NuGet Version](https://img.shields.io/nuget/v/AutoLaunch?label=AutoLaunch&logo=dotnet)](https://www.nuget.org/packages/AutoLaunch)
8+
[![NuGet Downloads](https://img.shields.io/nuget/dt/AutoLaunch?label=AutoLaunch)](https://www.nuget.org/packages/AutoLaunch)
9+
[![GitHub License](https://img.shields.io/github/license/Linlccc/AutoLaunch)](https://github.com/Linlccc/AutoLaunch/blob/master/LICENSE)
10+
11+
[AutoLaunch](https://github.com/Linlccc/AutoLaunch) is a cross-platform .NET library that provides a unified API for enabling auto-start for applications and executables on Windows, Linux, and macOS systems.
12+
13+
## ✨ Features
14+
15+
- 🌍 **Cross-Platform Support:** Windows, Linux, macOS
16+
- 🔧 **Multiple Engines:** Various implementations for each platform
17+
- 🎯 **Ease of Use:** Unified API across all platforms
18+
- 🛠 **AOT Support:** Fully supports AOT and trimming
19+
- 📦 **Zero Dependency:** No third-party library required
20+
21+
## 🚚 Supported Engines
22+
23+
### Windows
24+
25+
| Engine | Description | Permission | Note |
26+
|-------------------|-----------------------------------|------------|--------------------------------------------|
27+
| **Registry** | Manage startup via registry | User/Admin | |
28+
| **StartupFolder** | Manage startup via startup folder | User/Admin | |
29+
| **TaskScheduler** | Manage startup via Task Scheduler | Admin | Can launch programs requiring admin rights |
30+
31+
### Linux
32+
33+
| Engine | Description | Permission | Note |
34+
|-----------------|-----------------------------------------|------------|-------------------------------------------------------|
35+
| **Freedesktop** | Manage startup via Freedesktop standard | User/Admin | Requires a desktop environment supporting Freedesktop |
36+
37+
### macOS
38+
39+
| Engine | Description | Permission | Note |
40+
|-----------------|--------------------------------------|-----------------------|-------------------------------------------------|
41+
| **LaunchAgent** | Manage startup via Launch Agent | User/Admin | |
42+
| **AppleScript** | Manage startup items via login items | Automation permission | Only supports `--hidden`/`--minimize` arguments |
43+
44+
## 📦 Installation
45+
46+
dotnet CLI:
47+
48+
```bash
49+
dotnet add package AutoLaunch
50+
```
51+
52+
Package Manager Console:
53+
54+
```powershell
55+
Install-Package AutoLaunch
56+
```
57+
58+
## 🚀 Quick Start
59+
60+
Unified configuration API for all platforms
61+
62+
### Basic Usage
63+
64+
```csharp
65+
using AutoLaunch;
66+
67+
// Automatically configure for current program
68+
var autoLauncher = new AutoLaunchBuilder().Automatic().Build();
69+
70+
// Enable auto-launch synchronously
71+
autoLauncher.Enable();
72+
// Disable auto-launch synchronously
73+
autoLauncher.Disable();
74+
// Check if enabled synchronously
75+
bool isEnabled = autoLauncher.IsEnabled();
76+
77+
// Enable auto-launch asynchronously
78+
await autoLauncher.EnableAsync();
79+
// Disable auto-launch asynchronously
80+
await autoLauncher.DisableAsync();
81+
// Check if enabled asynchronously
82+
bool isEnabledAsync = await autoLauncher.IsEnabledAsync();
83+
```
84+
85+
### Custom Configuration
86+
87+
```csharp
88+
var autoLauncher = new AutoLaunchBuilder()
89+
.SetAppName("MyApp")
90+
.SetAppPath("/path/to/myapp")
91+
.SetArgs("arg1", "arg2")
92+
.AddArgs("arg3")
93+
.SetWorkScope(WorkScope.CurrentUser) // Set work scope for auto-launch
94+
.SetWindowsEngine(WindowsEngine.Registry) // Use Registry engine on Windows, ignored on other platforms
95+
.SetLinuxEngine(LinuxEngine.Freedesktop) // Use Freedesktop engine on Linux, ignored on other platforms
96+
.SetMacOSEngine(MacOSEngine.LaunchAgent) // Use LaunchAgent engine on macOS, ignored on other platforms
97+
.SetIdentifiers("com.example.myapp") // Add Bundle Identifier for macOS
98+
.SetExtraConfigIf(OperatingSystem.IsLinux(), "X-GNOME-Autostart-enabled=true") // Add extra config for Linux, must conform to Freedesktop standard
99+
.SetExtraConfigIf(OperatingSystem.IsMacOS(), "<key>KeepAlive</key><true/>") // Add extra config for macOS, must conform to LaunchAgent standard
100+
.Build();
101+
102+
autoLauncher.Enable();
103+
```
104+
105+
### Safe Mode
106+
107+
No exceptions will be thrown in safe mode
108+
109+
```csharp
110+
// Build an instance in safe mode
111+
var autoLauncher = new AutoLaunchBuilder().Automatic().BuildSafe();
112+
113+
// Try to enable, returns true/false for success/failure
114+
bool success = autoLauncher.TryEnable();
115+
116+
if(!success)
117+
{
118+
// Get the last exception
119+
Exception? lastException = autoLauncher.TakeLastException();
120+
if (lastException is PermissionDeniedException) Console.WriteLine("Permission denied.");
121+
else Console.WriteLine($"Failed to enable auto-launch: {lastException?.Message}");
122+
}
123+
```
124+
125+
## API Documentation
126+
127+
### AutoLaunchBuilder
128+
129+
| Method | Description |
130+
|-----------------------------------|-------------------------------------------|
131+
| `Automatic()` | Automatically configure app name and path |
132+
| `SetAppName(string)` | Set app name |
133+
| `SetAppPath(string)` | Set app path |
134+
| `SetArgs(params string[])` | Set startup arguments |
135+
| `AddArgs(params string[])` | Add startup arguments |
136+
| `SetWorkScope(WorkScope)` | Set work scope (current user/all users) |
137+
| `SetWindowsEngine(WindowsEngine)` | Set Windows engine |
138+
| `SetLinuxEngine(LinuxEngine)` | Set Linux engine |
139+
| `SetMacOSEngine(MacOSEngine)` | Set macOS engine |
140+
| `SetIdentifiers(params string[])` | Set identifiers (macOS LaunchAgent only) |
141+
| `AddIdentifiers(params string[])` | Add identifiers (macOS LaunchAgent only) |
142+
| `SetExtraConfig(string)` | Set extra configuration |
143+
| `SetExtraConfigIf(bool, string)` | Conditionally set extra configuration |
144+
| `Build()` | Build AutoLauncher instance |
145+
| `BuildSafe()` | Build SafeAutoLauncher instance |
146+
147+
### AutoLauncher Interface
148+
149+
| Method | Description |
150+
|--------------------|------------------------------------|
151+
| `Enable()` | Enable auto-launch |
152+
| `Disable()` | Disable auto-launch |
153+
| `IsEnabled()` | Check if enabled |
154+
| `EnableAsync()` | Enable auto-launch asynchronously |
155+
| `DisableAsync()` | Disable auto-launch asynchronously |
156+
| `IsEnabledAsync()` | Check if enabled asynchronously |
157+
158+
### SafeAutoLauncher Extra Methods
159+
160+
| Method | Description |
161+
|-----------------------|-------------------------------------------------|
162+
| `TryEnable()` | Try to enable, returns success/failure |
163+
| `TryDisable()` | Try to disable, returns success/failure |
164+
| `TryIsEnabled()` | Try to check status, returns (success, enabled) |
165+
| `TryEnableAsync()` | Try to enable asynchronously |
166+
| `TryDisableAsync()` | Try to disable asynchronously |
167+
| `TryIsEnabledAsync()` | Try to check status asynchronously |
168+
| `TakeLastException()` | Get last exception |
169+
170+
## ⚠️ Exception Types
171+
172+
| Exception | Description |
173+
|------------------------------|------------------------------|
174+
| `AutoLaunchException` | Base exception class |
175+
| `AutoLaunchBuilderException` | Builder configuration error |
176+
| `UnsupportedOSException` | Unsupported operating system |
177+
| `PermissionDeniedException` | Permission denied |
178+
| `ExecuteCommandException` | Command execution failed |
179+
180+
## 📜 License
181+
182+
Licensed under the terms of the [MIT License](LICENSE).

0 commit comments

Comments
 (0)