{"id":2737,"date":"2013-10-13T00:01:00","date_gmt":"2013-10-13T00:01:00","guid":{"rendered":"https:\/\/blogs.technet.microsoft.com\/heyscriptingguy\/2013\/10\/13\/the-admins-first-steps-discovering-shares\/"},"modified":"2013-10-13T00:01:00","modified_gmt":"2013-10-13T00:01:00","slug":"the-admins-first-steps-discovering-shares","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/scripting\/the-admins-first-steps-discovering-shares\/","title":{"rendered":"The Admin’s First Steps: Discovering Shares"},"content":{"rendered":"

Summary<\/strong>: Richard Siddaway talks about using Windows PowerShell to discover shares on remote systems.\n\"Hey, Hey, Scripting Guy! I’ve just starting using Windows PowerShell to administer my systems, and I’ve been asked to discover the shares on some remote servers. How can I do that?\n—OL\n\"Hey, Hello OL,\nHonorary Scripting Guy, Richard Siddaway, here today—filling in for my good friend, The Scripting Guy. You’re in luck because today I’ve got a solution to that issue as part of my series of posts about how an administrator can start making productive use of Windows PowerShell.\nIf you ask an IT-related question, you’ll often get the answer, “It depends.”\nIn the case of asking how you can discover the shares that are enabled on a remote machine, the full answer is, “It depends on the version of Windows you are running. If you have Windows 8 or Windows Server 2012, you get a shiny new module to play with that does the hard work for you. If you are using, or targeting, earlier versions of Windows, you will have to use WMI.”\nWindows 8 and Windows Server 2012 ship with PowerShell 3.0 and a suite of extra modules. Many of these modules are created by using the “cmdlets-over-objects” technology, which means that you take a WMI class, wrap it in XML, and you get a PowerShell module. Details of how to create your own CDXML modules are provided in my book, PowerShell and WMI<\/a>.\nYou can easily tell if your module has been constructed in this manner because it will have a .cdxml extension. In many instances, the WMI classes that are used for this process are new to Windows 8 and Windows Server 2012, and they are not available on earlier versions of Windows—even if you install Windows PowerShell 3.0.\nThe cmdlets are in a module called SmbShare<\/strong>. If you use Get-SmbShare<\/strong>, you see this output on a Windows 8-based computer:<\/p>\n

£> Get-SmbShare | Format-Table -AutoSize<\/p>\n

Name   ScopeName Path       Description<\/p>\n

—-   ——— —-       ———–<\/p>\n

ADMIN$ *         C:Windows Remote Admin<\/p>\n

C$     *         C:        Default share<\/p>\n

D$     *         D:        Default share<\/p>\n

IPC$   *                    Remote IPC<\/p>\n

Users  *         C:Users\nThis is for the local machine, but more importantly, you need to be able to administer your remote servers. Let’s look at the parameters that are available with Get-SmbShare<\/strong>:<\/p>\n

£> Get-Command  Get-SmbShare  -Syntax<\/p>\n

Get-SmbShare [[-Name] <string[]>] [[-ScopeName] <string[]>] [-Scoped <bool[]>] [-Special <bool[]>]<\/p>\n

[-ContinuouslyAvailable <bool[]>] [-ShareState <ShareState[]>] [-FolderEnumerationMode <FolderEnumerationMode[]>] [-CachingMode <CachingMode[]>] [-ConcurrentUserLimit <uint32[]>] [-AvailabilityType <AvailabilityType[]>] [-CaTimeout<uint32[]>] [-EncryptData <bool[]>] [-IncludeHidden] [-CimSession <CimSession[]>] [-ThrottleLimit <int>] [-AsJob][<CommonParameters>]\nYou will notice one glaring omission. There isn’t a ComputerName<\/strong> parameter. One of the quirks of CDXML-based modules is that you need to use CIM sessions to access remote machines (or run the command over a Windows PowerShell remoting session).<\/p>\n

$sess = New-CimSession -ComputerName Win12R2<\/p>\n

Get-SmbShare -CimSession $sess<\/p>\n

$sess | Remove-CimSession\nYou will automatically get PSComputerName<\/strong> output as an additional property. If you try to run this against an earlier version of Windows with Windows PowerShell 2.0, it will fail because you need WSMAN 3.0 on the remote system to use CIM sessions.\nThe older versions of Windows can’t be left out of this, so you need to look at another way of retrieving the data. WMI supplies a Win32_Share<\/strong> class that you can use:<\/p>\n

£> Get-WmiObject -Class Win32_Share | Format-Table -AutoSize<\/p>\n

Name   Path       Description<\/p>\n

—-   —-       ———–<\/p>\n

ADMIN$ C:Windows Remote Admin<\/p>\n

C$     C:        Default share<\/p>\n

D$     D:        Default share<\/p>\n

IPC$              Remote IPC<\/p>\n

Users  C:Users\nThe next step is to extend this to a remote machine. Get-WmiObject<\/strong> has had a –ComputerName<\/strong> parameter since PowerShell 1.0. Back in those days, it was our only tool for working remotely!<\/p>\n

 £> Get-WmiObject -Class Win32_Share -ComputerName Win12R2 | Format-Table –AutoSize\nSo, you get to the age-old question, “Which do I use?”\nThe drawback with CIM sessions is that you need WSMAN 3.0 on the remote machine, which means that PowerShell 3.0 or above must be installed. On older machines with Windows PowerShell 2.0, you need to have WMI allowed through any firewalls you have between you and the remote machine. As the percentage of machines with WSMAN 3.0 increases, you need to be maximizing the use of CIM sessions. The answer is to test the version of WSMAN that you have installed and proceed accordingly:<\/p>\n

£> Test-WSMan -Authentication default -ComputerName win12r2<\/p>\n

wsmid           : http:\/\/schemas.dmtf.org\/wbem\/wsman\/identity\/1\/wsmanidentity.xsd<\/p>\n

ProtocolVersion : http:\/\/schemas.dmtf.org\/wbem\/wsman\/1\/wsman.xsd<\/p>\n

ProductVendor   : Microsoft Corporation<\/p>\n

ProductVersion  : OS: 6.3.9600 SP: 0.0 Stack: 3.0\nThe value you need to test is the Stack<\/strong> property on the ProductVersion<\/strong>. This leads you to a function like this:<\/p>\n

function get-share {<\/p>\n

[CmdletBinding()]<\/p>\n

param(<\/p>\n

[parameter(Mandatory=$true,<\/p>\n

      ValueFromPipeline=$true,<\/p>\n

      ValueFromPipelineByPropertyName=$true)]<\/p>\n

[string[]]$computername<\/p>\n

)<\/p>\n

PROCESS{<\/p>\n

foreach ($computer in $computername){<\/p>\n

 $stack = ((Test-WSMan -Authentication default -ComputerName $computer  -ErrorAction SilentlyContinue ).ProductVersion -split “: “)[-1]<\/p>\n

  switch ($stack) {<\/p>\n

  “2.0” {<\/p>\n

          Get-WmiObject -Class Win32_Share -ComputerName $computer |<\/p>\n

          select PSComputername, Name, Path, Description<\/p>\n

        }<\/p>\n

  “3.0” {<\/p>\n

          $sess = New-CimSession -ComputerName Win12R2<\/p>\n

          Get-SmbShare -CimSession $sess |<\/p>\n

          select PSComputername, Name, Path, Description<\/p>\n

          $sess | Remove-CimSession<\/p>\n

        }<\/p>\n

  default {Write-Warning -Message “Couldn’t determine WSMAN Stack version for $computer” }<\/p>\n

 } # end switch<\/p>\n

} # end foreach<\/p>\n

} # End process<\/p>\n

}\nTake a pipeline input, and test the WSMAN version for a computer that is passed in. This line may look a bit intimidating:<\/p>\n

((Test-WSMan -Authentication default -ComputerName $computer  -ErrorAction SilentlyContinue ).ProductVersion -split “: “)[-1]\nIt’s not that bad when you break it down…\nThis gets the information:<\/p>\n

Test-WSMan -Authentication default -ComputerName $computer  -ErrorAction SilentlyContinue\nThis simply takes the ProductVersion<\/strong> property:<\/p>\n

(Test-WSMan -Authentication default -ComputerName $computer  -ErrorAction SilentlyContinue ).ProductVersion\nThis splits that property on a “: “<\/strong>:<\/p>\n

-split “: ”\nThe result is an array of which you take the last element by using the -1<\/strong> index. Try building up the command like this at the Windows PowerShell prompt to see how it all works.\nA switch statement is used to determine actions based on the WSMAN stack version. Version 2.0 uses WMI and version 3.0 uses CIM. The appropriate cmdlet is run and then a select statement is used to determine the data returned.  In this case, the PSComputerName<\/strong> property is used to identify the machine from which we generate the data.\nIf the stack version isn’t 2.0 or 3.0, the switch statement drops into the default option, which prints a warning on screen.\nWhat about the situation where you have hundreds or thousands of machines? Do you want to wait for this to run?\nIf the answer is, “No,” you could try turning this into a workflow, but the switch statement doesn’t work very well in workflows. We recommended against using it in PowerShell in Depth<\/a>. Your choices are to completely rewrite or to use Windows PowerShell jobs. Get-WmiObject<\/strong> and Get-SmbShare<\/strong> have an –AsJob<\/strong> parameter.\nA Windows PowerShell job will create a job object to perform your processing and then immediately continue with the next line in the script. This works for Get-WmiObject<\/strong>, but there is an issue using Get-SmbShare<\/strong> like this because the next line will immediately remove the CIM session the job is trying to use, and the job will fail.\nThe answer is to use Wait-Job<\/strong> to test the completion of the job, which will delay the whole script and negate the reason for using jobs, or to move the whole process into a script block and use Start-Job<\/strong>.<\/p>\n

function get-share {<\/p>\n

[CmdletBinding()]<\/p>\n

param(<\/p>\n

[parameter(Mandatory=$true,<\/p>\n

      ValueFromPipeline=$true,<\/p>\n

      ValueFromPipelineByPropertyName=$true)]<\/p>\n

[string[]]$computername<\/p>\n

)<\/p>\n

PROCESS{<\/p>\n

foreach ($computer in $computername){<\/p>\n

 $stack = ((Test-WSMan -Authentication default -ComputerName $computer -ErrorAction SilentlyContinue).ProductVersion -split “: “)[-1]<\/p>\n

  switch ($stack) {<\/p>\n

  “2.0” {<\/p>\n

          Get-WmiObject -Class Win32_Share -ComputerName $computer -AsJob<\/p>\n

        }<\/p>\n

  “3.0” {<\/p>\n

          $sb = {<\/p>\n

            param($comp)<\/p>\n

            $sess = New-CimSession -ComputerName $comp<\/p>\n

            Get-SmbShare -CimSession $sess<\/p>\n

            $sess | Remove-CimSession<\/p>\n

          }<\/p>\n

          Start-Job -ScriptBlock $sb -ArgumentList $computer<\/p>\n

        }<\/p>\n

  default {Write-Warning -Message “Couldn’t determine WSMAN Stack version for $computer” }<\/p>\n

 } # end switch<\/p>\n

} # end foreach<\/p>\n

} # End process<\/p>\n

}\nYou can then use the standard job cmdlets to retrieve the data.\nCreating your scripts in this way allows you to mix and match new technologies with older ways of doing things so that your automation will keep working as your server estate changes.\nIf you want to extend the use of this script you could:<\/p>\n