README.md

Getting Started with Authoring a SHiPS-based PowerShell Provider

Design Document

• SHiPS design details.

Public APIs, Parameters, etc.

• See SHiPS APIs, parameters, etc.

Step 1 - Model your system

• Let's say I want to navigate the following tree:

       Austin
       /   \
     Ben   Bill
     / \
 Cathy  Chris

Step 2 - Add code to your editor

• Open your favorite text editor, such as VSCode or PowerShell ISE

• For each node in the above tree, we'll create a class for it. The sample code looks like below.

• Copy the code to your editor

• Save it. Say MyProvider.psm1.

  using namespace Microsoft.PowerShell.SHiPS
  
  class Austin : SHiPSDirectory
  {
      Austin([string]$name): base($name)
      {
      }
  
      [object[]] GetChildItem()
      {
          $obj =  @()
          $obj += [Ben]::new();
          $obj += [Bill]::new();
          return $obj;
      }
  }
  
  class Bill : SHiPSLeaf
  {
      Bill () : base ("Bill")
      {
      }
  }
  
  class Ben : SHiPSDirectory
  {
      Ben () : base ("Ben")
      {
      }
  
      [object[]] GetChildItem()
      {
          $obj =  @()
          $obj += [Chris]::new();
          $obj += [Cathy]::new();
          return $obj;
      }
  }
  
  class Chris : SHiPSLeaf
  {
       Chris () : base ("Chris")
      {
      }
  }
  
  class Cathy : SHiPSLeaf
  {
      Cathy () : base ("Cathy")
      {
      }
  }
  

Step 3 - Use MyProvider.psm1

• Import-Module SHiPS (See Installing SHiPS for details)

• Create a PSDrive

  new-psdrive -name Austin -psprovider SHiPS -root MyProvider#Austin
  
  cd Austin:
  PS Austin:\> dir
    Container: Microsoft.PowerShell.SHiPS\SHiPS::tt#Austin
  
  Mode  Name
  ----  ----
  +     Ben
  .     Bill
  

Key takeaways from this example

• As MyProvider is built on top of the SHiPS, we need to include the namespace at the beginning

  using namespace Microsoft.PowerShell.SHiPS

• Each class as a navigation node needs inherits from SHiPSDirectory for a directory type, i.e., node contains child items.

• For leaf nodes, you can return any type. For the sake of output formatting, you may define a class inherits from SHiPSLeaf.

• As a root node, you need to define a constructor with node name as a parameter. For example,

  Austin([string]$name): base($name)
  

• To support Get-ChildItem or dir, you need to implement the below method in your class.

  [object[]] GetChildItem()
  

• When you create a PSDrive, the supported format is "module#type", e.g.,

  new-psdrive -name Austin -psprovider SHiPS -root MyProvider#Austin

More Samples

Wanna try more samples? Review the following:

• FamilyTree
• File System as a Recursion Example
• Show Progress, and Other Attributes
• Dynamic Parameters Example
• C# Based Class
• Navigate Azure Resources
• Navigate CIM Classes and Namespaces