Community.Wsl.Sdk 3.1.0

dotnet add package Community.Wsl.Sdk --version 3.1.0                
NuGet\Install-Package Community.Wsl.Sdk -Version 3.1.0                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Community.Wsl.Sdk" Version="3.1.0" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Community.Wsl.Sdk --version 3.1.0                
#r "nuget: Community.Wsl.Sdk, 3.1.0"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Community.Wsl.Sdk as a Cake Addin
#addin nuget:?package=Community.Wsl.Sdk&version=3.1.0

// Install Community.Wsl.Sdk as a Cake Tool
#tool nuget:?package=Community.Wsl.Sdk&version=3.1.0                

Community SDK for Windows Subsystem for Linux

Fork: This repository is based on the awsome work of wslhub/wsl-sdk-dotnet

This project contains a WSL API wrapper for Windows developers who wants to integrate WSL features into existing Windows applications. You can enumerate, query, executing WSL commands via C# classes.

Supported frameworks

  • .Net 6
  • .Net 8

Supported Operating Systems

  • Windows 10 x64 16299 or higher
  • Windows 11 x64

How to use

There are one default implementations of IWslApi.

It uses the wsl.exe executable and (mostly) public information stored in the registry.

❗ Com-Api: WSL has a com-based api that could also used instead. Using com-apis has several disadvantages including security related issues. Using the managed alternative with wsl.exe has proven to be more versatile and easier to use.

How to install

This package is available on nuget.org.
You can add a reference using dotnet:

dotnet add package Community.Wsl.Sdk

API

WSL Api

Class Description
WslApi Get list of installed linux distributions.
Command Execute command in specified linux distribution.

Code Example

Basic usage of wsl api

using Community.Wsl.Sdk;

// Create instance
var api = new WslApi();

// Check if wsl is supported
bool isSupported = api.IsWslSupported();

// OR check if wsl is supported and also know why not:
string reason;
bool isSupported = api.IsWslSupported(out reason);

// Enumerate distro list
var distros = api.GetDistroList();

// Query default distro details
var defaultDistro = api.GetDefaultDistro();

Basic command execution

using Community.Wsl.Sdk;

// Setup
var api = new WslApi();

var distroName = api.GetDefaultDistro()!.Value.DistroName;

// Get command result
var cmd = new Command(
    distroName,
    "echo",
    new string[] { "-n", "test" },
    new CommandExecutionOptions() { StdoutDataProcessingMode = DataProcessingMode.String }
);
// execute the command and wait for the result (blocks current thread)
var result = cmd.StartAndGetResults();
// OR start and wait asynchronously
// var result = await cmd.StartAndGetResultsAsync();

// result.Stdout is "test"

Unit tests and Mocks

Both WslApi and Command implement interfaces, namely IWslApi and ICommand. If you already use mocking frameworks & DI, use them to create a test friendly class, for example using FakeItEasy:

var api = A.Fake<IWslApi>();

You can also mock specific parts of the implementation by passing custom implementations in the constructor:

/*
Signature of the constructor:
public WslApi(
    IRegistry? registry = null,
    IIo? io = null,
    IEnvironment? environment = null
)
*/

// mock only the IIo logic
var api = new WslApi(
    io: A.Fake<IIo>()
);

Migrate from v1 to v2

Breaking changes:

  • ComBasedWslApi has been removed

  • ComCommand has been removed

  • ManagedWslApi has been renamed to WslApi

  • ManagedCommand has been remamed to Command

  • Changed namespace Community.Wsl.Sdk.Strategies.Command to Community.Wsl.Sdk.Strategies.Commands

Please use the managed api (Managed{WslApi,Command}). It has the same features and is easier to use.

Migrate from v2 to v3

Breaking changes:

  • Support for .Net 5 has been removed. .Net 5 is out of support since May 10, 2022.
  • Support for .NET Core 3.1 has been removed. .NET Core 3.1 will be out of support after December 13, 2022.
  • Migrated to Community.Wsx.Shared (replaces most interfaces and implementations for .Net framework)
  • Moved classes & interfaces in Strategies.{Api,Commands}.* to root namespace.

Please upgrade to a newer .NET and .NET Core runtime version. The minimum supported .Net version is .Net 6.

Product Compatible and additional computed target framework versions.
.NET net6.0-windows7.0 is compatible.  net7.0-windows was computed.  net8.0-windows was computed.  net8.0-windows7.0 is compatible. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
3.1.0 143 8/17/2024
3.1.0-alpha1 111 8/17/2024
3.0.0 1,219 6/12/2022
3.0.0-alpha2 205 6/12/2022
3.0.0-alpha1 185 6/12/2022
2.0.2 555 4/17/2022
2.0.2-alpha3 202 4/17/2022
2.0.2-alpha2 185 4/17/2022
2.0.2-alpha1 195 4/17/2022
2.0.1 455 4/17/2022
0.1.4 360 12/27/2021
0.1.3 288 12/27/2021
0.1.2 291 12/26/2021
0.1.1 292 12/25/2021
0.1.0 282 12/25/2021

## 3.1.0
Ignore invalid sub reg keys (#18)