PIA Sharp

For basic installation instructions, see the main readme.

Compatibility

PIA Sharp's main package, Cmpnnt.Pia.Ctl, has been tested against version 3.3.1 on Windows and Linux (MacOS compatibility is on the roadmap). It provides access to every piactl command available in those version on those systems. It might also work on other versions of piactl, provided they expose the same commands with the same parameters. However, this hasn't been tested and nothing is guaranteed.

Setup

You must have a Private Internet Access account and the piactl command line application installed on your system. This is included with their desktop GUI application.

There are two ways to use Cmpnnt.Pia.Ctl: Dependency Injection and simple instantiation

Dependency Injection

There's a separate dependency injection library you can use if you require DI. Add a reference to Cmpnnt.Pia.DependencyInjection and include it in your DI container by adding a call to services.AddPiaCtl() under ConfigureServices.

Note

Note: The dependency injection package registers PiaCtl as a singleton.

Here's a basic example. You can find the runnable code in the examples project.

using IHost host = Host.CreateDefaultBuilder(args)
    .ConfigureServices(services =>
    {
        services.AddPiaCtl();
        services.AddScoped<SomeClass>();
    })
    .ConfigureLogging(options =>
    {
        options.ClearProviders();
        options.AddConsole();
    })
    .Build();

Configuration

You can also pass a lambda function to AddPiaCtl to configure the path to your system's piactl application, if it differs from the default. On Windows, the default location is C:\Program Files\Private Internet Access\piactl.exe.

using IHost host = Host.CreateDefaultBuilder(args)
    .ConfigureServices(services =>
    {
        services.AddPiaCtl(options =>
        {
            options.PiaPath = @"C:\path\to\piactl.exe";
        });
        services.AddScoped<SomeClass>();
    })
    .ConfigureLogging(options =>
    {
        options.ClearProviders();
        options.AddConsole();
    })
    .Build();

Instantiation

If you don't need DI, you can use the command-line wrapper by itself by including a reference to Cmpnnt.Pia.Ctl, available as a nuget package.

PiaCtl pia = new PiaCtl();
PiaResults results = await pia.GetRegions();
Console.WriteLine(results);

Usage

Full API documentation is available in the API Reference.

Commands

TODO: Add link to developer documentation

Cmpnnt.Pia.Ctl allows access to every command exposed by piactl. The methods are all asynchronous, but don't include the async suffix. The available commands are as follows. See the API reference for detailed developer documentation.

Results (command line output)

All PiaCtl commands return a Task<PiaResults>, which contains a Status enum indicating the result of the operation and a List<string> for each of stdout and stderr output. The ToString() method has been overridden to return a JSON-formatted string with that information (using source generation for the JSON serialization).

Compiling

Because Cmpnnt.Pia.Ctl is a .NET 7 Native AOT library, it requires additional tooling to compile.

Windows

On Windows, install Visual Studio 2022 with the Desktop Development for C++ workload.

Linux

On Linux, install the following packages, depending on your distribution:

Ubuntu 18.04+

sudo apt-get install clang zlib1g-dev

Alpine 3.15+

sudo apk add clang build-base zlib-dev

MacOS

To compile on MacOS, you'll need to install the latest Command Line Tools for XCode.

References

Links to various articles and documentation referenced while building this project can be found here

Edit this page