Improved help for public functions - fixes #7

Author: kilasuit

Functions/Public/Clear-JunctionLinks.ps1

@@ -2,6 +2,12 @@ function Clear-JunctionLinks {
     <#
     .Synopsis
     Simple helper script that removes any discovered junction links from user's $env:TEMP directory.
+    
+    .EXAMPLE
+
+    Clear-JunctionLinks
+
+    This will remove any mounted images in the $env:TEMP directory 
     #>
     [CmdletBinding()]
     param (

Functions/Public/ConvertTo-Dockerfile.ps1

@@ -13,42 +13,95 @@ function ConvertTo-Dockerfile {
 
     .PARAMETER OutputPath
     An optional parameter that specifies the filesystem path where artifacts and the resulting
-    Dockerfile will be stored. If you do not specify a path, a temporary directory will be created for you.
+    Dockerfile will be stored. If you do not specify a path, a temporary directory will be created for you within the $env:Temp location.
 
+    .PARAMETER MountPath
+    The filesystem path to the directory where the image will be mounted to for discovery.
+    The folder will be created if it does not exist.
+    If you do not specify a path, a temporary directory will be created for you within the $env:Temp location and will be removed 
+    
     .PARAMETER Artifact
     Specify the discovery artifacts that will be scanned during the ConvertTo-Dockerfile command.
 
-    You can obtain the supported list of artifacts by running the Get-WindowsArtifacts command in the same module.
+    You can use tab completion to find all of the supported artifacts that can be discovered.
+
+    .PARAMETER ArtifactParam
+    This paramater is used in conjunction with the artifact paramater and currently is used when specifying a Single IIS Web App.
+
+    Please see the examples for how to use this parameter.
+
+    .PARAMETER Force
+    This Parameter is for use when you want to use a folder that you have either already used for creating a Dockerfile from an image 
+    
+    .EXAMPLE
+
+    ConvertTo-Dockerfile -ImagePath E:\VMVirtualHardDisks\WebServer.VHDX -OutputPath C:\Docker\IIS\ -MountPath C:\Image\ -Artifact IIS -Verbose
+
+    With this example we will be mounting a VHDX for a Virtual Machine called WebServer and the image will be mounted at the C:\Image\ location. We have specified that we want to only return the IIS Artifact from this machine so this will only perform the discovery of IIS related items and will output the required items to the OutputPath directory which in this case we have specified this to be C:\Docker\IIS\ and we will return all verbose output when running this command.
+
+    .EXAMPLE    
+    
+    ConvertTo-Dockerfile -ImagePath E:\VMVirtualHardDisks\WebServer.VHDX -OutputPath C:\Docker\WebServer\ -Verbose
+
+    With this example we will be mounting a VHDX for a Virtual Machine called WebServer. 
+    As we have not specifiec a MountPath the Image will be mounted into a folder in the Temp path location and will be removed when this command finishes. 
+    As we have not specified a specific Artifact from this machine, this function will return artifacts for all of the available artifacts that this tool can attempt to discover and will output the required items to the OutputPath directory which in this case we have specified this to be C:\Docker\WebServer\
+    
+    .EXAMPLE    
+    
+    ConvertTo-Dockerfile -ImagePath E:\VMVirtualHardDisks\WebServer.VHDX 
+
+    With this example we will be mounting a VHDX for a Virtual Machine called WebServer. 
+    As we have not specifiec a MountPath the Image will be mounted into a folder in the Temp path location and will be removed when this command finishes.
+    
+    As we have not specified a specific Artifact from this machine, this function will return artifacts for all of the available artifacts that this tool can attempt to discover and as we have not specified an OutputPath this command will create a folder in the $env:temp folder where all of the artifacts, required files and the resulting Dockerfile will be output to.
+    
+    .EXAMPLE
+
+    ConvertTo-Dockerfile -ImagePath E:\VMVirtualHardDisks\WebServer.VHDX -OutputPath C:\Docker\IIS_SingleApp\ -MountPath C:\Image\ -Artifact IIS_SingleApp -ArtifactParam 'Default Web Site' -Force  -Verbose
+
+    With this example we will be mounting a VHDX for a Virtual Machine called WebServer and the image will be mounted at the C:\Image\ location.
+    We have specified that we want to only return the IIS_SingleApp Artifact and for this we have provided the name of the WebApp that we want to return via the ArtifactParam Parameter, in this case we have specified that we want to return the 'Default Web Site' that is created when the IIS feature is activated on a new server.
+
+    We have also specified the Force Parameter which will remove any existing files and folders that are in the OutputPath directory and will reuse this directory for the output from this command.
 
-    .PARAMETER MountPath
-    The filesystem path to the directory where the image will be mounted to for discovery.
-    The folder will be created if it does not exist.
     #>
+
+
     [CmdletBinding()]
     param (
         [Parameter(Mandatory = $true)]
-        [ValidateScript({
-            if (!(Test-Path -Path $PSItem)) {
-                return $false
-            }
-            else { return $true }
-         })]
+        [ValidateScript({if (!(Test-Path -Path $PSItem)) { return $false } else { return $true } })]
         [string] $ImagePath,
+
         [Parameter(Mandatory = $false)]
         [string] $OutputPath,
+
         [Parameter(Mandatory = $false)]
         [string] $MountPath,
+
+        [Parameter(Mandatory = $false)]
+        [string[]] $Artifact,
+
+        [Parameter(Mandatory = $false)]
+        [string[]] $ArtifactParam,
+
         [Parameter(Mandatory = $false)]
-        [string[]] $Artifact
+        [Switch] $Force
+
     )
 
     ### If the user doesn't specify an output path, then generate one
     if (!$PSBoundParameters.Keys.Contains('OutputPath')) {
         $OutputPath = GenerateOutputFolder
-    } else {
+    } 
+    elseif(($PSBoundParameters.Keys.Contains('OutputPath')) -and ($PSBoundParameters.Keys.Contains('Force')))
+    {
+        $OutputPath = GenerateOutputFolder -Path $OutputPath -Force
+    }
+    else {
         $OutputPath = GenerateOutputFolder -Path $OutputPath
     }
-
     Write-Verbose -Message ('Starting conversion process')
 
     ### Verify the image type before proceeding
@@ -69,10 +122,20 @@ function ConvertTo-Dockerfile {
     if (!$PSBoundParameters.Keys.Contains('Artifact')) {
         $Artifact = Get-WindowsArtifacts
     }
-    DiscoverArtifacts -Artifact $Artifact -OutputPath $OutputPath
+    if (!$PSBoundParameters.Keys.Contains('ArtifactParam')) {
+         DiscoverArtifacts -Artifact $Artifact -OutputPath $OutputPath
+    }
+    else {
+        DiscoverArtifacts -Artifact $Artifact -OutputPath $OutputPath -ArtifactParam $ArtifactParam
+    }
 
     ### Generate Dockerfile
-    GenerateDockerfile -ArtifactPath $OutputPath -Artifact $Artifact
+    if (!$PSBoundParameters.Keys.Contains('ArtifactParam')) {
+        GenerateDockerfile -ArtifactPath $OutputPath -Artifact $Artifact
+    }
+    else {
+        GenerateDockerfile -ArtifactPath $OutputPath -Artifact $Artifact -ArtifactParam $ArtifactParam
+    }
     Write-Verbose -Message 'Finished generating the Dockerfile'
 
     ### Dismount the image when inspection is completed

Functions/Public/Get-WindowsArtifacts.ps1

@@ -2,19 +2,26 @@ function Get-WindowsArtifacts {
     <#
     .SYNOPSIS
     Returns a list of supported artifacts for discovery in a Windows image.
+    
+    .EXAMPLE
+
+    $Artifacts = Get-WindowsArtifacts
+
+    This will return all of the discoverable artifacts and assign the result to the Artifacts Variable
+    
     #>
     [CmdletBinding()]
     param (
     )
 
-    $ArtifactList = Get-ChildItem -Path $ModulePath\Artifacts -Directory
+    $ArtifactList = Get-ChildItem -Path $ModulePath\Functions\Private\Artifacts -Directory
     Write-Verbose -Message ('Searching for artifacts in filesystem path: {0}\Artifacts' -f $ModulePath)
 
     foreach ($Artifact in $ArtifactList) {
         $ChildItems = (Get-ChildItem -Path $Artifact.FullName).Name
         Write-Verbose -Message ('Child items for "{0}" artifact: {1}' -f $Artifact.FullName, ($ChildItems -join ', '))
 
-        if ($ChildItems -contains 'Discover.ps1' -and $ChildItems -contains 'Generate.ps1') {
+        if ($ChildItems -contains "Discover_$Artifact.ps1" -and $ChildItems -contains "Generate_$Artifact.ps1") {
             Write-Output -InputObject $Artifact.Name
             Write-Verbose -Message ('Valid artifact found: {0}' -f $Artifact.Name)
         }

Image2Docker.psd1

@@ -1,7 +1,7 @@
 #
-# Module manifest for module 'DockerMigrate'
+# Module manifest for module Image2Docker
 #
-# Generated by: TrevorSullivan
+# Generated by: Docker
 #
 # Generated on: 8/29/2016
 #
@@ -12,7 +12,7 @@
 RootModule = 'Image2Docker.psm1'
 
 # Version number of this module.
-ModuleVersion = '1.5'
+ModuleVersion = '1.5.1'
 
 # Supported PSEditions
 ### NOTE: This module will not work with PowerShell Core.
@@ -25,13 +25,13 @@ ModuleVersion = '1.5'
 GUID = '93adf15e-4b53-4f7b-9954-a86011c8ce55'
 
 # Author of this module
-Author = 'Trevor Sullivan <trevor@artofshell.com>'
+Author = 'Docker'
 
 # Company or vendor of this module
 CompanyName = 'Docker Inc.'
 
 # Copyright statement for this module
-Copyright = '(c) 2016 TrevorSullivan. All rights reserved.'
+Copyright = '(c) 2016 Docker Inc. All rights reserved.'
 
 # Description of the functionality provided by this module
 Description = 'Performs inspection of artifacts in a valid Windows Server 2012 or Windows Server 2012 R2 WIM or VHDX image and emit a Dockerfile to build the image with.
@@ -105,13 +105,13 @@ PrivateData = @{
     PSData = @{
 
         # Tags applied to this module. These help with module discovery in online galleries.
-        Tags = @('Docker', 'migration')
+        Tags = @('Docker', 'Migration','DockerFile','Image Capture')
 
         # A URL to the license for this module.
         LicenseUri = 'http://www.apache.org/licenses/LICENSE-2.0'
 
         # A URL to the main website for this project.
-        ProjectUri = 'https://github.com/docker/dockermigrate'
+        ProjectUri = 'https://github.com/docker/communitytools-image2docker-win'
 
         # A URL to an icon representing this module.
         # IconUri = ''