Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add WSL extension to Dev Home #3365

Merged
merged 16 commits into from
Jul 9, 2024
Merged

Add WSL extension to Dev Home #3365

merged 16 commits into from
Jul 9, 2024

Conversation

bbonaby
Copy link
Contributor

@bbonaby bbonaby commented Jul 3, 2024

Summary of the pull request

This PR adds the WSL extension to Dev Home. We'd like to thank @crramirez for allowing us to use his original Dev Home WSL extension as a base for this official extension.

Now on to changes:
- Added the WSLExtension project under the extensions folder
- Added the COM extension guid information to the appxmanifest file
- Added the WSL extension guid to the set for internal guids in the extensions library so it can be enabled/disabled.
- Added template specifically for settings cards used in environment creation to allow for bigger icons.
- Added template in environment project to allow a single button to be shown when there are no launch operations available.

WSL extension architecture:

First thing to note, is that the WSL API surface is very limited and so we will be working with the WSL team to provide us with a APIs in the future to perform all WSL tasks. Until then our approach here will be to use a mix of calling wsl.exe (the only way to interact with wsl through code) and reading from the registry. There are technically a small number of apis listed here: Wslapi.h header - Win32 apps | Microsoft Learn, but it is very limited and won't be updated like how wsl.exe is continuously being updated, so we won't be using those.

Sequence diagram that shows flow for retrieving registered WSL distributions (Click the <--> button for a larger view) :

sequenceDiagram
    DevHome->>+WslProvider: Requests for list of Dev Home compute system SDK objects
    WslProvider->>+WslManager: Requests for a list of WslComputeSystem objects
    WslManager->>+DistributionDefinitionHelper: Requests for all distribution definitions the helper knows about
    DistributionDefinitionHelper->>+DistributionDefinitionHelper: Uses web and local yaml to build definition objects for each distribution.
    DistributionDefinitionHelper->>+WslManager: Returns dictionary of distribution definition objects
    WslManager->>+WslservicesMediator: caches definition objects and requests a list of all WslRegisteredDistribution objects on the machine
    WslservicesMediator->>+WslManager: Reads registry and returns a WslRegisteredDistribution object for each registered distribution it finds
    WslManager-->>-WslManager: Fills out each WslRegisteredDistribution object with additional metadata if the object has a corresponding Distribution definition. E.g adding logos/Publisher info to the WslRegisteredDistribution object.
    WslManager-->>-WslProvider: Creates list of Dev Home compute system SDK objects that represent a registered WSL distribution and returns the list
    WslProvider-->>-DevHome: Returns list of compute systems
Loading

Sequence diagram that shows flow for creating/installing a WSL distribution (Click the <--> button for a larger view):

sequenceDiagram
    DevHome->>+WslProvider: Requests creation adaptive card session
    WslProvider->>+WslManager: Requests for all available distribution definition objects
    WslManager->>+WslProvider: Returns filtered list of definition objects. Anyones that are already registered are removed.
    WslProvider->>+WslProvider: Creates a new adaptive card session for creation with this list of available distributions.
    WslProvider->>+DevHome: Returns adaptive card session
    DevHome->>+RegisterAndInstallDistributionSession: requests initial creation adaptive card 
    RegisterAndInstallDistributionSession->>+DevHome: Returns adaptive card with list of single select settings cards
    DevHome->>+RegisterAndInstallDistributionSession: User selects a card and selects next button, invoking the sessions OnAction method 
    RegisterAndInstallDistributionSession->>+DevHome: Returns Review page adaptive card
    DevHome->>+RegisterAndInstallDistributionSession: User selects 'Create environment' button, invoking the sessions OnAction method
    RegisterAndInstallDistributionSession->>+DevHome: Raises session ended event with user input json in payload which contains distribution to install
    DevHome->>+WslProvider: Requests to create a new compute system with the returned input payload
    WslProvider->>+DevHome: Returns CreateComputeSystemOperation Dev Home SDK object (WslInstallDistributionOperation)
    DevHome->>+WslInstallDistributionOperation: Starts operation
    WslInstallDistributionOperation->>+WslManager: Requests to install Wsl distribution
    WslManager-->>+WslservicesMediator: Requests to install Wsl distribution
    WslservicesMediator-->>-WslservicesMediator: Initiates wsl.exe --install with distribution name and returns
    loop Check if distribution installed. Timeout in 10 minutes
    WslInstallDistributionOperation-->>+WslManager: Request for registered distribution with user provided distribution name. Break when found
    end
    WslInstallDistributionOperation-->>-DevHome: Creates and returns a new compute system that contains information on the newly registered distribution
Loading

Videos:

Video of me creating a WSL compute system:

creating.ubuntu.distribution.mp4

Video of me launching a WSL compute system:

ubuntu.launch.mp4

Video of me Terminating all sessions a WSL compute system:

ubuntu.terminate.mp4

Video of me Deleting a WSL compute system:

debian.delete.mp4

References and relevant issues

Detailed description of the pull request / Additional comments

  • More work needs to be done as we flesh out pinning environments. We'll also need to add the ability to create/reuse terminal profiles for launching wsl distributions. E.g allowing users to provide us with the path to their custom profile. Today we only use the hard coded profiles that ubuntu offers for that distribution.
  • When terminating a distribution, we don't have access to the wsl.exe process that runs in terminal so you'll see that when we terminate a distribution in the video above, the window stays up. Users can then press enter and terminal will restart wsl in that window but that is outside of Dev Home and no event get fired to tell Dev Home the distribution is now running again. So, we'll show "Stopped" when in actuality the distribution is running. I've added a threadpool timer that allows us to refresh the state once a minute due to these cases
  • Noticed that now that we use bigger icons in the settings card, the icon for the Dev Box provider becomes blurry. I'll need to submit a PR into the Azure extension to update this icon.
  • WSL Page - Feature Exploration! #2266 lists a lot of features that users have requested. This is the first step in that direction

Validation steps performed

Confirmed that the Hyper-v environment and dev box environment are still working as intended. Also confirmed no regressions in other parts of Dev Home.

PR checklist

common/DevHome.Common.csproj Outdated Show resolved Hide resolved
extensions/WSLExtension/Constants.cs Outdated Show resolved Hide resolved
extensions/WSLExtension/DevHomeProviders/WslProvider.cs Outdated Show resolved Hide resolved
extensions/WSLExtension/Program.cs Outdated Show resolved Hide resolved
extensions/WSLExtension/Services/WslExtension.cs Outdated Show resolved Hide resolved
extensions/WSLExtension/Services/WslExtension.cs Outdated Show resolved Hide resolved
extensions/WSLExtension/Strings/en-US/Resources.resw Outdated Show resolved Hide resolved

<!--- Data templates for custom adaptive card renders can go here -->
<converters:EmptyObjectToObjectConverter x:Key="EmptyObjectToObjectConverter" NotEmptyValue="Visible" EmptyValue="Collapsed"/>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

NIT: rename the key name to EmptyObjectToVisibilityConverter


// Launch terminal with specific profile and log the user into their home directory in the login shell
// Note: this opens a new terminal window in the UI
public static string LaunchDistributionInTerminalWithProfile { get; } = "--profile {0} -- wsl --shell-type login --cd ~ --distribution {1}";
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

NIT for this and the other strings. Explain what the placeholders are for. This way calling code does not need to look at the string.

Another option is to remove the properties all together and change these into methods. Then, the code can describe the format with parameters.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think it would make sense to make them into methods, because in the future when the WSL team provides us with apis then we'd need to remove/change those methods. Today we're using wsl.exe under the hood, but I've made it in a way where, when we get new apis, only the body of the methods that use these strings need to change, not the method themselves.

Ultimately if you typed in wsl --help in your command line window you'll see what these commands are used for but I can add it to the comments if you feel strongly about it.

@dhoehna
Copy link
Contributor

dhoehna commented Jul 9, 2024

Please run through all your examples with text scaling set to 200%.

@bbonaby
Copy link
Contributor Author

bbonaby commented Jul 9, 2024

@dhoehna , just confirmed at 225%, everything still looks good with no issues.

@bbonaby bbonaby merged commit d606948 into main Jul 9, 2024
4 checks passed
@go-colin
Copy link

Just popping in to say thank you for this :)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

WSL Integration
6 participants