https://github.com/ktsu-dev/singleappinstance
https://github.com/ktsu-dev/singleappinstance
Last synced: about 1 month ago
JSON representation
- Host: GitHub
- URL: https://github.com/ktsu-dev/singleappinstance
- Owner: ktsu-dev
- License: mit
- Created: 2025-01-13T01:51:38.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2026-04-14T23:20:44.000Z (about 2 months ago)
- Last Synced: 2026-04-15T01:35:32.155Z (about 2 months ago)
- Language: C#
- Size: 418 KB
- Stars: 0
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.md
- Authors: AUTHORS.md
- Copyright: COPYRIGHT.md
Awesome Lists containing this project
README
# ktsu.SingleAppInstance
> A .NET library that ensures only one instance of your application is running at a time.
[](LICENSE.md)
[](https://nuget.org/packages/ktsu.SingleAppInstance)
[](https://nuget.org/packages/ktsu.SingleAppInstance)
[](https://nuget.org/packages/ktsu.SingleAppInstance)
[](https://github.com/ktsu-dev/SingleAppInstance/commits/main)
[](https://github.com/ktsu-dev/SingleAppInstance/graphs/contributors)
[](https://github.com/ktsu-dev/SingleAppInstance/actions)
## Introduction
`ktsu.SingleAppInstance` is a lightweight .NET library that provides a robust mechanism to ensure only one instance of an application is running at a time. It uses a JSON-serialized PID file with multi-attribute process verification to accurately detect running instances, making it ideal for desktop applications, services, or any software that requires instance exclusivity to prevent resource conflicts or maintain data integrity.
## Features
- **Single Instance Enforcement**: Prevents multiple copies of your application from running simultaneously
- **Enhanced Process Identification**: Verifies running instances using multiple attributes (PID, process name, start time, executable path) for accurate detection
- **Race Condition Handling**: Includes a built-in 1-second delay to safely detect simultaneous startup attempts
- **PID File Management**: Stores process information as JSON in the application data directory
- **Backward Compatibility**: Gracefully handles legacy PID files that stored only a plain integer PID
- **Simple API**: Two methods — `ExitIfAlreadyRunning()` for automatic exit and `ShouldLaunch()` for custom logic
- **Multi-Target Support**: Works across .NET 10.0 through .NET 5.0, .NET Standard 2.0/2.1
## Installation
### Package Manager Console
```powershell
Install-Package ktsu.SingleAppInstance
```
### .NET CLI
```bash
dotnet add package ktsu.SingleAppInstance
```
### Package Reference
```xml
```
## Usage Examples
### Basic Example
The simplest way to use SingleAppInstance is to call `ExitIfAlreadyRunning` at the start of your application. If another instance is detected, the process exits automatically:
```csharp
using ktsu.SingleAppInstance;
class Program
{
static void Main(string[] args)
{
SingleAppInstance.ExitIfAlreadyRunning();
// Your application code here
Console.WriteLine("Application is running.");
}
}
```
### Custom Launch Logic
If you prefer to handle the duplicate-instance case yourself, use `ShouldLaunch()` which returns a boolean:
```csharp
using ktsu.SingleAppInstance;
class Program
{
static void Main(string[] args)
{
if (SingleAppInstance.ShouldLaunch())
{
// Your application code here
Console.WriteLine("Application is running.");
}
else
{
Console.WriteLine("Another instance is already running.");
}
}
}
```
### WPF Application Integration
```csharp
using System.Windows;
using ktsu.SingleAppInstance;
namespace MyWpfApp
{
public partial class App : Application
{
protected override void OnStartup(StartupEventArgs e)
{
base.OnStartup(e);
if (!SingleAppInstance.ShouldLaunch())
{
MessageBox.Show("Application is already running.");
Shutdown();
return;
}
MainWindow = new MainWindow();
MainWindow.Show();
}
}
}
```
## API Reference
### `SingleAppInstance`
A static class that provides single-instance enforcement for applications. Uses a PID file stored in the application data directory to track running instances.
#### Methods
| Name | Return Type | Description |
| --- | --- | --- |
| `ExitIfAlreadyRunning()` | `void` | Checks if another instance is running and calls `Environment.Exit(0)` if so |
| `ShouldLaunch()` | `bool` | Writes a PID file, waits 1 second for race condition detection, and returns `true` if safe to proceed |
## Contributing
Contributions are welcome! Feel free to open issues or submit pull requests.
## License
This project is licensed under the MIT License. See the [LICENSE.md](LICENSE.md) file for details.