Plugin Authoring

PortForwardingService allows its functionality to be extended with plugins.

These PortForwardingService plugins take the form of .NET DLLs that implement an interface from a shared library and are located in the <installation directory>\plugins\ directory.

Prerequisites

• .NET development environment, such as any one of
  • Visual Studio Community Edition with .NET Desktop Development workload
  • Visual Studio Code with the C# Dev Kit extension
  • JetBrains Rider
  • .NET SDK and a text editor

Sample plugin

The SamplePlugin is a skeleton project that shows how to structure a library to act as a plugin.

Creating a plugin

1. Create a new C# library project, targeting .NET Framework 4.8.
2. Declare a dependency on the PortForwardingService.Abstractions package.

Warning

Make sure to set the ExcludeAssets attribute of the PortForwardingService.Abstractions PackageReference to runtime, otherwise PortForwardingService could load two different copies of that library, which would prevent it from discovering or loading your plugin.

📄 MyPlugin.csproj

<Project Sdk="Microsoft.NET.Sdk">

    <PropertyGroup>
        <TargetFramework>net48</TargetFramework>
        <AssemblyName>PortForwardingService.Plugins.$(MSBuildProjectName)</AssemblyName>
        <RootNamespace>$(AssemblyName)</RootNamespace>
        <Nullable>enable</Nullable>
        <ImplicitUsings>enable</ImplicitUsings>
        <LangVersion>latest</LangVersion>
        <Authors>My Name</Authors>
        <Copyright>© 2026 $(Authors)</Copyright>
        <Company>$(Authors)</Company>
        <DebugType>embedded</DebugType>
        <EnableDynamicLoading>true</EnableDynamicLoading>
    </PropertyGroup>

    <ItemGroup>
        <PackageReference Include="PortForwardingService.Abstractions" Version="0.0.1" ExcludeAssets="runtime" />
    </ItemGroup>

</Project>

3. Create a class that implements the IPortForwardingServicePlugin interface.
4. Provide your custom logic to run when the PIA forwarded port changes in the OnForwardedPortChanged(ushort?, ushort?) method.
5. Optionally provide process-lifetime initialization and cleanup logic in the class' constructor and IDisposable.Dispose methods, respectively.

📄 MyPlugin.cs

using PortForwardingService.Data;

namespace PortForwardingService.Plugins.MyPlugin;

public class MyPlugin: IPortForwardingServicePlugin, IDisposable {

    public MyPlugin() {
        // optional initialization logic when PortForwardingService launches
    }

    public void OnForwardedPortChanged(ushort? newForwardedPort, ushort? oldForwardedPort) {
        // logic when port forwarding starts, stops, or changes port number
    }

    public void Dispose() {
        // optional cleanup logic when PortForwardingService exits
    }

}

Deploying a plugin

1. Compile the project.

   dotnet publish

2. Stop PortForwardingService.
3. Copy the DLLs (such as PortForwardingService.Plugins.MyPlugin.dll) and other required files from bin\Debug\net48\publish\ to <installation directory>\plugins\, which you will have to create if it doesn't already exist.
4. Start PortForwardingService.

Debugging a plugin

You can debug PortForwardingService and its plugins in Visual Studio by clicking Debug › Attach to Process… and choosing PortForwardingService.exe.