Copy sampleConfigurations folder from devhome repo to a samples f…

…older (#133) * Copy entire folder from devhome repository * Update README URL * markdown + general lint fixes * Update sandbox script as per microsoft/devhome#3984 * spelling * try again * markdownlint
microsoft · Nov 27, 2024 · 584dfb6 · 584dfb6
1 parent 569b657
commit 584dfb6
Show file tree

Hide file tree

Showing 42 changed files with 1,360 additions and 1 deletion.
diff --git a/.github/actions/spelling/allow.txt b/.github/actions/spelling/allow.txt
@@ -43,3 +43,25 @@ pscustomobject
 VGpu
 wildcards
 worktree
+aspnetcore
+bbwe
+devdocs
+echarts
+ephemoral
+Fancyzones
+gdk
+JDK
+jquery
+Mfor
+msixbundle
+NVM
+powertoys
+reduxjs
+restsource
+seperated
+tastejs
+todomvc
+videojs
+vsconfig
+websites
+wekyb
diff --git a/.github/actions/spelling/patterns.txt b/.github/actions/spelling/patterns.txt
@@ -71,3 +71,6 @@ name\:\s+.+$
 
 # Github User Content
 /[-a-z0-9]+\.githubusercontent\.com/[-a-zA-Z0-9?&=_\/.]*
+
+# GitHub SHAs (markdown)
+(?:\[`?[0-9a-f]+`?\]\(https:/|)/(?:www\.|)github\.com(?:/[^/\s"]+){2,}(?:/[^/\s")]+)(?:[0-9a-f]+(?:[-0-9a-zA-Z/#.]*|)\b|)
diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
 # DSC Resources for WinGet Configuration
 
-This project is intended to support WinGet Configuration. Some of these Desired State Configuration (DSC) Resources are exploratory and may not be published in the PowerShell Gallery. Other resources may be moved to their own projects or removed entirely.  [Samples](https://aka.ms/dsc.yaml) for using these resources are available in the [Dev Home](https://github.com/microsoft/devhome) repository.
+This project is intended to support WinGet Configuration. Some of these Desired State Configuration (DSC) Resources are exploratory and may not be published in the PowerShell Gallery. Other resources may be moved to their own projects or removed entirely. Samples for using these resources are available in the [samples](./samples/) directory. They are also available via the URL: `https://aka.ms/dsc.yaml`
 
 ## Contributing
 

diff --git a/samples/DscResources/GitDsc/CloneWingetRepository.yaml b/samples/DscResources/GitDsc/CloneWingetRepository.yaml
@@ -0,0 +1,32 @@
+# yaml-language-server: $schema=https://aka.ms/configuration-dsc-schema/0.2
+
+########################################################################################
+# This configuration will clone the winget-cli repository to a specified location.     #
+# PowerShell module: GitDsc (v0.1.3-alpha)                                             #
+########################################################################################
+
+properties:
+  resources:
+    - resource: Microsoft.WinGet.DSC/WinGetPackage
+      directives:
+        description: Install Git
+        allowPrerelease: true
+      settings:
+        id: Git.Git
+        source: winget
+    - resource: GitDsc/GitClone
+      directives:
+        description: Clone the winget-cli repository
+        allowPrerelease: true
+      settings:
+        HttpsUrl: https://github.com/microsoft/winget-cli.git
+        RootDirectory: '${WingetConfigRoot}/SampleRepos/'
+    # - resource: GitDsc/GitRemote
+    #   directives:
+    #     description: Add a remote repository to the cloned winget-cli repository.
+    #     allowPrerelease: true
+    #   settings:
+    #     RemoteName: exampleName
+    #     RemoteUrl: https://github.com/exampleName/winget-cli.git
+    #     ProjectDirectory: '${WingetConfigRoot}/SampleRepos/winget-cli'
+  configurationVersion: 0.2.0
diff --git a/samples/DscResources/Microsoft.Windows.Developer/ModifyWindowsSettings.yaml b/samples/DscResources/Microsoft.Windows.Developer/ModifyWindowsSettings.yaml
@@ -0,0 +1,44 @@
+# yaml-language-server: $schema=https://aka.ms/configuration-dsc-schema/0.2
+
+###########################################################################
+# This configuration will modify various Windows Settings.                #
+# PowerShell module: Microsoft.Windows.Developer (v0.2.1-alpha)           #
+###########################################################################
+
+properties:
+  resources:
+    - resource: Microsoft.Windows.Developer/Taskbar
+      directives:
+        description: Modify taskbar settings
+        allowPrerelease: true
+      settings:
+        Alignment: Left # [KeepCurrentValue, Middle]
+        HideLabelsMode: Never # [KeepCurrentValue, WhenFull, Always]
+        SearchBoxMode: ShowIconAndLabel # [KeepCurrentValue, ShowIconOnly, SearchBox, Hide]
+        TaskViewButton: Show # [KeepCurrentValue, Hide]
+        WidgetsButton: Show # [KeepCurrentValue, Hide]
+        RestartExplorer: True # Use caution when setting `RestartExplorer: true` as this will force explorer to close. Required for `HideLabelsMode`.
+    - resource: Microsoft.Windows.Developer/WindowsExplorer
+      directives:
+        description: Modify Windows Explorer settings
+        allowPrerelease: true
+      settings:
+        FileExtensions: Hide # [KeepCurrentValue, Hide]
+        HiddenFiles: Hide # [KeepCurrentValue, Hide]
+        ItemCheckBoxes: Hide # [KeepCurrentValue, Hide]
+        RestartExplorer: True # Use caution when setting `RestartExplorer: true` as this will force explorer to close. Required for all WindowsExplorer settings.
+    - resource: Microsoft.Windows.Developer/ShowSecondsInClock
+      directives:
+        description: Show seconds in clock
+        allowPrerelease: true
+      settings:
+        Ensure: Present
+    - resource: Microsoft.Windows.Developer/EnableDarkMode
+      directives:
+        description: Disable dark mode
+        allowPrerelease: true
+      settings:
+        Ensure: Absent
+        # Use caution when setting `RestartExplorer: true` as this will force explorer to close.
+        RestartExplorer: true # Required to apply changes
+  configurationVersion: 0.2.0
diff --git a/samples/DscResources/Microsoft.Windows.Developer/RevertWindowsSettings.yaml b/samples/DscResources/Microsoft.Windows.Developer/RevertWindowsSettings.yaml
@@ -0,0 +1,44 @@
+# yaml-language-server: $schema=https://aka.ms/configuration-dsc-schema/0.2
+
+###########################################################################
+# This configuration will revert various Windows Settings.                #
+# PowerShell module: Microsoft.Windows.Developer (v0.2.1-alpha)           #
+###########################################################################
+
+properties:
+  resources:
+    - resource: Microsoft.Windows.Developer/Taskbar
+      directives:
+        description: Revert taskbar settings
+        allowPrerelease: true
+      settings:
+        Alignment: Middle # [KeepCurrentValue, Left]
+        HideLabelsMode: Always # [KeepCurrentValue, WhenFull, Never]
+        SearchBoxMode: Hide # [KeepCurrentValue, ShowIconOnly, SearchBox, ShowIconAndLabel]
+        TaskViewButton: Hide # [KeepCurrentValue, Show]
+        WidgetsButton: Hide # [KeepCurrentValue, Show]
+        RestartExplorer: True # Use caution when setting `RestartExplorer: true` as this will force explorer to close. Required for `HideLabelsMode`.
+    - resource: Microsoft.Windows.Developer/WindowsExplorer
+      directives:
+        description: Revert Windows Explorer settings
+        allowPrerelease: true
+      settings:
+        FileExtensions: Show # [KeepCurrentValue, Hide]
+        HiddenFiles: Show # [KeepCurrentValue, Hide]
+        ItemCheckBoxes: Show # [KeepCurrentValue, Hide]
+        RestartExplorer: # Use caution when setting `RestartExplorer: true` as this will force explorer to close. Required for all WindowsExplorer settings.
+    - resource: Microsoft.Windows.Developer/ShowSecondsInClock
+      directives:
+        description: Hide seconds in clock
+        allowPrerelease: true
+      settings:
+        Ensure: Absent
+    - resource: Microsoft.Windows.Developer/EnableDarkMode
+      directives:
+        description: Enable dark mode
+        allowPrerelease: true
+      settings:
+        Ensure: Present
+        # Use caution when setting `RestartExplorer: true` as this will force explorer to close.
+        RestartExplorer: true # Required to apply changes
+  configurationVersion: 0.2.0
diff --git a/samples/DscResources/Microsoft.WindowsSandbox.DSC/README.md b/samples/DscResources/Microsoft.WindowsSandbox.DSC/README.md
@@ -0,0 +1,44 @@
+# Microsoft.WindowsSandbox.DSC
+
+The [Microsoft.WindowsSandbox.DSC](https://www.powershellgallery.com/packages/Microsoft.WindowsSandbox.DSC) PowerShell module contains the WindowsSandbox DSC Resource. This resource accepts either a reference to a Windows Sandbox .WSB file or properties to configure and launch an instance of the Windows Sandbox.
+
+>Note: The Windows Sandbox is an ephemoral instance of Windows. It also defaults to an administrative context when running the LogonCommand.
+
+Prior to running this configuration, users should be on either Windows PRO or Windows enterprise. The "Windows Sandbox" optional feature also needs to be enabled.
+
+The "full.sandbox.dsc.yaml" configuration is not fully capable of verifying the Windows SKU or enabling Windows optional features via the WinGet CLI (and subsequently Dev Home). The Windows optional features can be enabled in a configuration when run via the Microsoft.WinGet.Configuration.
+
+The "full.sandbox.dsc.yaml" configuration can be run via the Microsoft.WinGet.Configuration module.
+
+Install the module using:
+
+```PowerShell
+Install-Module -Name Microsoft.WindowsSandbox.DSC -AllowPrerelease
+```
+
+Run the configuration in PowerShell 7 using:
+
+```PowerShell
+get-WinGetConfiguration -File full.sandbox.dsc.yaml | Invoke-WinGetConfiguration
+```
+
+## How to use the WinGet Configuration File
+
+The following two options are available for running a WinGet Configuration file on your device.
+
+### 1. Windows Package Manager
+
+1. Download the `sandbox.dsc.yaml` file to your computer.
+1. Open your Windows Start Menu, search and launch "*Windows Terminal*".
+1. Type the following: `CD <C:\Users\User\Download>`
+1. Type the following: `winget configure --file .\sandbox.dsc.yaml`
+
+### 2. Dev Home
+
+1. Download the `sandbox.dsc.yaml` file to your computer.
+1. Open your Windows Start Menu, search and launch "*Dev Home*".
+1. Select the *Machine Configuration* button on the left side navigation.
+1. Select the *Configuration file* button
+1. Locate and open the WinGet Configuration file downloaded in "step 1".
+1. Select the "I agree and want to continue" checkbox.
+1. Select the "Set up as admin" button.
diff --git a/samples/DscResources/Microsoft.WindowsSandbox.DSC/full.sandbox.dsc.yaml b/samples/DscResources/Microsoft.WindowsSandbox.DSC/full.sandbox.dsc.yaml
@@ -0,0 +1,42 @@
+# yaml-language-server: $schema=https://aka.ms/configuration-dsc-schema/0.2
+
+###############################################################################
+# Create Windows Sandbox instance with WinGet installed.                      #
+# Run as Administrator                                                        #
+# Mount C:\Sandbox on the local filesystem into the Sandbox filesystem.       #
+# The Logon command performs the following steps in Windows PowerShell:       #
+# 1. Set the execution policy to RemoteSigned                                 #
+# 2. Download and install Microsoft.WinGet.Client PowerShell Module           #
+# 3. Use Repair-WinGetPackageManager cmdlet to bootstrap WinGet               #
+###############################################################################
+
+properties:
+  resources:
+    - resource: PSDscResources/WindowsOptionalFeature
+      id: WindowsSandbox
+      directives:
+        description: Ensure Windows Sandbox is enabled
+      settings:
+        Name: Containers-DisposableClientVM
+        Ensure: Present
+    - resource: Microsoft.WindowsSandbox.DSC/WindowsSandbox
+      dependsOn:
+        - WindowsSandbox
+      directives:
+        description: Create Windows Sandbox with Winget installed
+        allowPrerelease: true
+      settings:
+        Ensure: Present
+        HostFolder: C:\Sandbox
+        SandboxFolder: C:\Sandbox
+        LogonCommand: >
+          cmd /c start powershell -NoExit -Command "$progressPreference = 'silentlyContinue';
+          Write-Host 'Setting execution policy to remote signed...' `n;
+          Set-ExecutionPolicy RemoteSigned -Force;
+          Write-Host "Installing WinGet PowerShell module from PSGallery...";
+          Install-PackageProvider -Name NuGet -Force | Out-Null;
+          Install-Module -Name Microsoft.WinGet.Client -Force -Repository PSGallery | Out-Null;
+          Write-Host "Using Repair-WinGetPackageManager cmdlet to bootstrap WinGet...";
+          Repair-WinGetPackageManager;
+          Write-Host "Done.";
+  configurationVersion: 0.2.0
diff --git a/samples/DscResources/Microsoft.WindowsSandbox.DSC/sandbox.dsc.yaml b/samples/DscResources/Microsoft.WindowsSandbox.DSC/sandbox.dsc.yaml
@@ -0,0 +1,43 @@
+# yaml-language-server: $schema=https://aka.ms/configuration-dsc-schema/0.2
+
+###############################################################################
+# Create Windows Sandbox instance with WinGet installed.                      #
+# Run as Administrator                                                        #
+# Mount C:\Sandbox on the local filesystem into the Sandbox filesystem.       #
+# The Logon command performs the following steps in Windows PowerShell:       #
+# 1. Set the execution policy to RemoteSigned                                 #
+# 2. Download and install Microsoft.WinGet.Client PowerShell Module           #
+# 3. Use Repair-WinGetPackageManager cmdlet to bootstrap WinGet               #
+###############################################################################
+
+properties:
+  resources:
+    - resource: Microsoft.WindowsSandbox.DSC/WindowsSandbox
+      directives:
+        description: Create Windows Sandbox with Winget installed
+        allowPrerelease: true
+      settings:
+        Ensure: Present
+        #WsbFile: <Provide a custom .wsb file to open. The parameters below will override existing values in the wsb file>
+        LogonCommand: >
+          cmd /c start powershell -NoExit -Command "$progressPreference = 'silentlyContinue';
+          Write-Host 'Setting execution policy to remote signed...' `n;
+          Set-ExecutionPolicy RemoteSigned -Force;
+          Write-Host "Installing WinGet PowerShell module from PSGallery...";
+          Install-PackageProvider -Name NuGet -Force | Out-Null;
+          Install-Module -Name Microsoft.WinGet.Client -Force -Repository PSGallery | Out-Null;
+          Write-Host "Using Repair-WinGetPackageManager cmdlet to bootstrap WinGet...";
+          Repair-WinGetPackageManager;
+          Write-Host "Done.";
+        #HostFolder: <Absolute path to folder on host machine that will be shared into the Windows Sandbox>
+        #SandboxFolder: <Absolute path to destination in the sandbox to map the Host Folder to>
+        #ReadOnly: false
+        #MemoryInMB: 2048
+        #vGPU: true
+        #AudioInput: true
+        #ClipboardRedirection: true
+        #Networking: true
+        #PrinterRedirection: false
+        #ProtectedClient: false
+        #VideoInput: true
+  configurationVersion: 0.2.0
diff --git a/samples/DscResources/PowerToysConfigure/PowerToys.dsc.yaml b/samples/DscResources/PowerToysConfigure/PowerToys.dsc.yaml
@@ -0,0 +1,29 @@
+################################################################################
+# yaml-language-server: $schema=https://aka.ms/configuration-dsc-schema/0.2    #
+#                                                                              #
+# This DSC config file will install Microsoft.PowerToys, then configure, by:   #
+# Disabling the ShortcutGuide and setting it to full opacity, then enabling    #
+# Fancy Zones and setting the Fancy Zone Editor hotkey to Shift+Ctrl+Alt+F.    #
+#                                                                              #
+################################################################################
+#
+properties:
+  configurationVersion: 0.2.0
+  resources:
+    - resource: Microsoft.WinGet.DSC/WinGetPackage
+      directives:
+        description: Install PowerToys
+        allowPrerelease: true
+      settings:
+        id: Microsoft.PowerToys
+        source: winget
+    - resource: PowerToysConfigure
+      directives:
+        description: Configure PowerToys
+      settings:
+        ShortcutGuide:
+          Enabled: false
+          OverlayOpacity: 1
+        FancyZones:
+          Enabled: true
+          FancyzonesEditorHotkey: "Shift+Ctrl+Alt+F"
diff --git a/samples/DscResources/README.md b/samples/DscResources/README.md
@@ -0,0 +1,19 @@
+# DscResources
+
+## Sample Configurations for Specific DSC Resources
+
+The sample configurations provided in this directory showcase how to create WinGet configuration files utilizing DSC resources for more specific scenarios.
+
+### [GitDsc](https://www.powershellgallery.com/packages/GitDsc/0.1.2-alpha)
+
+Supports cloning a new repository and adding/removing remote connections to other repositories.
+
+### [Microsoft.WindowsSandbox.DSC](https://www.powershellgallery.com/packages/Microsoft.WindowsSandbox.DSC/0.1.1-alpha)
+
+Create a new instance of Windows Sandbox by either providing a custom .wsb file or specifying parameters.
+
+>Note: [Windows Sandbox](https://learn.microsoft.com/windows/security/application-security/application-isolation/windows-sandbox/windows-sandbox-overview#prerequisites) requires Windows 10 Pro or Enterprise, build version 18305 or Windows 11.
+
+### [Microsoft.Windows.Developer](https://www.powershellgallery.com/packages/Microsoft.Windows.Developer/0.1.3-alpha)
+
+Modify various Windows Settings such as showing seconds in clock, hiding file extensions, or showing the task view button...
diff --git a/samples/README.md b/samples/README.md
@@ -0,0 +1,35 @@
+# DSC Samples
+
+## Using the sample configurations
+
+Download the *.dsc.yaml files to your local system. They can be executed in Dev Home via the "Machine configuration" section. They can also be executed by running `winget configure <path to configuration file>`.
+
+Several DSC resources may require running in administrator mode. If the configuration is leveraging the [WinGet DSC resource](https://www.powershellgallery.com/packages/Microsoft.WinGet.DSC) to install packages, there are also limitations in some cases specific to the installers that may either require or prohibit installation in administrative context.
+
+### GitHub projects (Repositories)
+
+Sample configurations have been provided for various GitHub repositories. These configurations ideally should be placed in a `.configurations` folder in the root of the project directory. Some DSC resources may have parameters that allow you to pass in a relative file path. The reserved variable `$(WinGetConfigRoot)` can be used to specify the full path of the configuration file. An example of how to use that variable with a relative file path is shown below:
+
+```yaml
+    - resource: Microsoft.VisualStudio.DSC/VSComponents
+      dependsOn:
+      directives:
+        description: Install required VS workloads from .vsconfig file
+        allowPrerelease: true
+      settings:
+        productId: Microsoft.VisualStudio.Product.Community
+        channelId: VisualStudio.17.Release
+        vsConfigFile: '${WinGetConfigRoot}\..\.vsconfig'
+```
+
+### Learn to Code (Templates)
+
+Sample configurations in this directory are directly related to the [Windows development paths](https://learn.microsoft.com/windows/dev-environment/#development-paths). These configurations will allow you to automatically set up your device and begin developing in your preferred language quickly.
+
+### Sample DSC Resources (DscResources)
+
+Examples for a few specific DSC Resources are under the [DscResources](./DscResources/) directory.
+
+### Create your own
+
+Writing YAML is a pain. To help you get started creating your own, there is a [sample tool](https://github.com/microsoft/winget-create/blob/main/Tools/WingetCreateMakeDSC.ps1) for authoring in the winget-create repo. It currently only supports adding apps, but give it a try and contribute to make it better!