Class Wsl2Proxy

INTERNAL USE ONLY: Used internally for building Linux components.

Inheritance

object

Wsl2Proxy

Namespace: Neon.WSL

Assembly: Neon.WSL.dll

Syntax

public sealed class Wsl2Proxy

Remarks

WSL2 distibutions are managed by the Microsoft wsl.exe command line tool. This includes commands to import/export, register, and terminate WSL2 Linux distributions as well as the ability to login and/or execute commands,

wsl.exe seems to be primarily intended to be used by users performing interactive commands from within some sort of command shell like cmd.exe, Powershell, cmdr.exe, ms-terminal, etc.

The Wsl2Proxy class wraps the wsl.exe tool such that Linux commands can be be invoked via code running on Windows. We currently use this for managing WSL2 for a local NEONDESKTOP cluster.

Managing WSL2 Distros

This class provides these static methods for managing distros:

Import(string, string, string)	Imports a WSL2 distro from a TAR file.
Export(string, string)	Exports a WSL2 distro to a TAR file.
Terminate(string)	Terminates the named WSL2 disto.
Unregister(string)	Unregisters the named WSL2 distribution. Note that you must Terminate(string) it first when the distro is running.
List(bool, bool)	Lists registered distributions, optionally returning only the running distros.

Executing Commands

To start a WSL distro, you'll need to instantiate an instance via new Wsl2Proxy(string, string), passing the registered name of the distribution and optionally the Linux user name (defaults to root). By default, the constructor logs into the distro using specified user name.

This class provides several methods for executing commands within the distro:

Execute(string, params object[])	Executes a command as the current user.
ExecuteAs(string, string, params object[])	Executes a command as a specific user.
ExecuteScript(string)	Executes a script as the current user.
ExecuteScriptAs(string, string)	Executes a script as a specific user.
SudoExecute(string, params object[])	sudo executes a command as the current user.
SudoExecuteAs(string, string, params object[])	sudo executes a command as a specific user.
SudoExecuteScript(string)	sudo executes a script as the current user.
SudoExecuteScriptAs(string, string)	sudo executes a script as the current user.

note

IMPORTANT: Do not depend on the executed commands sharing the same environment variables. Also, don't depend on the Linux login having been started.

Managing Files

WSL2 distro file management is pretty easy because Windows mounts its file system at /mnt/DRIVE-LETTER/... within the distro so Linux code can access them and the distro files are mounted on Windows at //wsl$/DISTRO-NAME/....

ToLinuxPath(string)	Maps a host Windows file system path to the equivalent path within the Linux distro.
ToWindowsPath(string)	Maps a Linux distro file system path to the equivalent path on the Windows host.
UploadFile(string, string, string, string, bool)	Uploads a file from the Windows host to the distro, optionally setting the owner and permissions as well as optionally converting Windows style line endings (\r\n) to Linux (\n);

note

These file methods work when Wsl2Proxy instance regardless of whether the instance is logged into the distro or not.

Constructors

Wsl2Proxy(string, string)

Constructs a proxy connected to a specific WSL2 distribution, starting the distribution by default of it's not already running.

Declaration

public Wsl2Proxy(string name, string user = "root")

Parameters

Type	Name	Description
string	name	Identifies the target WSL2 distribution.
string	user	Optionally connect as a non-root user.

Remarks

The user passed will become the default user for subsequent proxy operations. This may be overridden by for specific operations by specifying a different user in the call.

Fields

RootUser

The name of the root Linux user.

Declaration

public const string RootUser = "root"

Field Value

Type	Description
string

Properties

IsDebian

Returns true for Debian/Ubuntu based distributions.

Declaration

public bool IsDebian { get; }

Property Value

Type	Description
bool

IsRunning

Determines whether the distribution is running.

Declaration

public bool IsRunning { get; }

Property Value

Type	Description
bool

IsWsl2Enabled

Returns true if WSL2 is enabled on the local Windows workstation.

Declaration

public static bool IsWsl2Enabled { get; }

Property Value

Type	Description
bool

Name

Returns the distribution's name.

Declaration

public string Name { get; }

Property Value

Type	Description
string

OSRelease

Returns a dictionary with the properties loaded from the /etc/os-release file on the distribution.

Declaration

public IDictionary<string, string> OSRelease { get; }

Property Value

Type	Description
IDictionary<string, string>

Remarks

The contents will look something like:

NAME=Ubuntu
VERSION=20.04.1 LTS (Focal Fossa)
ID=ubuntu
ID_LIKE=debian
PRETTY_NAME=Ubuntu 20.04.1 LTS
VERSION_ID=20.04
HOME_URL=https://www.ubuntu.com/
SUPPORT_URL=https://help.ubuntu.com/
BUG_REPORT_URL=https://bugs.launchpad.net/ubuntu/
PRIVACY_POLICY_URL=https://www.ubuntu.com/legal/terms-and-policies/privacy-policy
VERSION_CODENAME=focal
UBUNTU_CODENAME=focal

User

Sppecifies the distribution user account to use for operations. This will be initialized to the user passed to the constructor but may be changed afterwards to perform operations under other accounts.

Declaration

public string User { get; set; }

Property Value

Type	Description
string

Methods

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

Declaration

public void Dispose()

Execute(string, params object[])

Executes a program within the distribution as the current user.

note

The program will be executed within the current login session if there is one.

Declaration

public ExecuteResponse Execute(string path, params object[] args)

Parameters

Type	Name	Description
string	path	The program path.
object[]	args	Optional program arguments.

Returns

Type	Description
ExecuteResponse	An ExecuteResponse with the command results.

ExecuteAs(string, string, params object[])

Executes a program within the distribution as a specific user.

Declaration

public ExecuteResponse ExecuteAs(string user, string path, params object[] args)

Parameters

Type	Name	Description
string	user	The user.
string	path	The program path.
object[]	args	Optional program arguments.

Returns

Type	Description
ExecuteResponse	An ExecuteResponse with the command results.

ExecuteScript(string)

Executes a bash script on the distribution as the current user.

note

The script will be executed within the current login session if there is one.

Declaration

public ExecuteResponse ExecuteScript(string script)

Parameters

Type	Name	Description
string	script	The script text.

Returns

Type	Description
ExecuteResponse	An ExecuteResponse with the command results.

ExecuteScriptAs(string, string)

Executes a bash script on the distribution as a specific user.

Declaration

public ExecuteResponse ExecuteScriptAs(string user, string script)

Parameters

Type	Name	Description
string	user	The user.
string	script	The script text.

Returns

Type	Description
ExecuteResponse	An ExecuteResponse with the command results.

Exists(string)

Checks to see if a named distribution exists.

Declaration

public static bool Exists(string name)

Parameters

Type	Name	Description
string	name	The distribution name.

Returns

Type	Description
bool	true if the distribution exists.

Export(string, string)

Exports a named distribution to a TAR file.

Declaration

public static void Export(string name, string tarPath)

Parameters

Type	Name	Description
string	name	The new distribution's name.
string	tarPath	Path to the distribution output TAR file.

GetDefault()

Returns the name of the default WSL2 distribution, if any.

Declaration

public static string GetDefault()

Returns

Type	Description
string	The name of the default distribution or null.

Import(string, string, string)

Imports a distribution from a TAR file.

Declaration

public static void Import(string name, string tarPath, string targetFolder)

Parameters

Type	Name	Description
string	name	The new distribution's name.
string	tarPath	Path to the distribution input TAR file.
string	targetFolder	Path to the folder where the distribution image will be created.

IsPortListening(int)

Determines whether a WSL2 IPv4 port is currently listening for connections.

Declaration

public bool IsPortListening(int port)

Parameters

Type	Name	Description
int	port	The port number.

Returns

Type	Description
bool	true if the port is available.

Remarks

This is useful for ensuring that another distro hasn't started listening on a port that's going to conflict with this distro. This can happen because all WSL2 distros share the same network namespace. This can also happen when a Windows process is listening on the port.

List(bool, bool)

Lists the names of the installed WSL2 distributions, optionally limiting this to the running distributions.

Declaration

public static IEnumerable<string> List(bool runningOnly = false, bool keepDefault = false)

Parameters

Type	Name	Description
bool	runningOnly	Optionally return just the running distribitions.
bool	keepDefault	Optionally retain the " (Default)" substring identifying the default repo.

Returns

Type	Description
IEnumerable<string>	The list of WSL2 distributions.

SudoExecute(string, params object[])

Executes a program within the distribution as the current user under SUDO.

note

The program will be executed within the current login session if there is one.

Declaration

public ExecuteResponse SudoExecute(string path, params object[] args)

Parameters

Type	Name	Description
string	path	The program path.
object[]	args	Optional program arguments.

Returns

Type	Description
ExecuteResponse	An ExecuteResponse with the command results.

SudoExecuteAs(string, string, params object[])

Executes a program within the distribution as a specifc user under SUDO.

Declaration

public ExecuteResponse SudoExecuteAs(string user, string path, params object[] args)

Parameters

Type	Name	Description
string	user	The user.
string	path	The program path.
object[]	args	Optional pprogram arguments.

Returns

Type	Description
ExecuteResponse	An ExecuteResponse with the command results.

SudoExecuteScript(string)

Executes a bash script as SUDO on the distribution as the current user.

note

The script will be executed within the current login session if there is one.

Declaration

public ExecuteResponse SudoExecuteScript(string script)

Parameters

Type	Name	Description
string	script	The script text.

Returns

Type	Description
ExecuteResponse	An ExecuteResponse with the command results.

SudoExecuteScriptAs(string, string)

Executes a bash script as SUDO on the distribution as a specific user.

Declaration

public ExecuteResponse SudoExecuteScriptAs(string user, string script)

Parameters

Type	Name	Description
string	user	The user.
string	script	The script text.

Returns

Type	Description
ExecuteResponse	An ExecuteResponse with the command results.

Terminate()

Terminates the distribution if it's running.

Declaration

public void Terminate()

Terminate(string)

Terminates the named distribution if it exists and is running.

Declaration

public static void Terminate(string name)

Parameters

Type	Name	Description
string	name	Identifies the target WSL2 distribution.

ToLinuxPath(string)

Maps a fully qualified Windows host filesystem path to the corresponding path within the Linux distribution.

Declaration

public string ToLinuxPath(string windowsPath)

Parameters

Type	Name	Description
string	windowsPath	The fully qualified host Windows path.

Returns

Type	Description
string	The corresponding Windows host path.

ToWindowsPath(string)

Maps a fully qualified filesystem path within the Linux distribution to the corresponding Windows filesystem path on the host machine.

Declaration

public string ToWindowsPath(string linuxPath)

Parameters

Type	Name	Description
string	linuxPath	The fully qualified internal Linux path.

Returns

Type	Description
string	The corresponding Linux path.

Remarks

note

This assumes that the internal Linux path includes only characters supported by Windows.

Unregister(string)

Terminates the named distribution (if it exists ans is running) and then unregisters it with WSL2 effectively removing it.

Declaration

public static void Unregister(string name)

Parameters

Type	Name	Description
string	name	Identifies the target WSL2 distribution.

UploadFile(string, string, string, string, bool)

Creates a text file at the specifid path within the distribution. The file will be created with the current User as the owner by default by this can be overridden.

Declaration

public void UploadFile(string path, string text, string owner = null, string permissions = null, bool toLinuxText = false)

Parameters

Type	Name	Description
string	path	The target path.
string	text	The text to be written.
string	owner	Optionally overrides the current user when setting the file owner.
string	permissions	Optionally specifies the linux file permissions.
bool	toLinuxText	Optionally convertes conversion of Windows (CRLF) line endings to the Linux standard (LF).