Koans/Cmdlets 1/AboutGetHelpAndGetMember.Koans.ps1
|
#Requires -Module PSKoans [Koan(201)] param() <# Get-Help Get-Help is a built-in PowerShell cmdlet that is used to retrieve help data for cmdlets and functions. It contains usage examples, parameter information, and a significant amount of otherwise difficult to discover tidbits. Get-Member Get-Member is another built-in cmdlet that is invaluable in retrieving information about any object in PowerShell. It can be used to inspect the type name of an object, as well as all available methods and properties that can be accessed for that object. These cmdlets are quintessential discovery tools, and regular use of them will vastly expedite any unfamiliar task in PowerShell. Combined with well-placed Google searches, it is possible to learn a significant amount about native PowerShell cmdlets and functions, and more advanced .NET classes, and methods. #> Describe 'Get-Help' { Context 'shows help information about cmdlets' { # Try calling 'Get-Help Get-Help' in a console to see the built in help available # for the help command. It 'gives exhaustive information for cmdlets and functions' { $HelpInfo = Get-Help 'Get-Help' $GetHelpParams = $HelpInfo.Parameters.Parameter.Name # Using the information from Get-Help, fill in the missing parameters in alphabetical order. $GetHelpParams | Should -Be @( 'Category' 'Component' '__' 'Examples' '__' '__' 'Name' 'Online' '__' 'Path' 'Role' '__' ) } It 'can give detailed information on specific parameters' { # You can also query specific parameters for more detailed information on what they can do. # For instance, does the Path parameter for Get-Help support pipeline input? $ParameterInfo = Get-Help 'Get-Help' -Parameter Path $ParameterInfo.PipelineInput | Should -Be __ } # Remember: if 'Get-Help Cmdlet-Name' doesn't show you all you need, try -Full. You'll need it. } } Describe 'Get-Member' { Context 'Members and methods of objects' { It 'can help you find useful properties' { $String = 'Hello!' # If you try to access a property that doesn't exist, PowerShell returns $null for it. $String.ThisDoesntExist | Should -Be $null <# To use Get-Member, pipe an object into it like so: "Hello!" | Get-Member You may need to try some of these in a PowerShell console for yourself to find the best way to solve the problem! Tab-completion can also help you find method and property names; try typing 'string'.<tab> into a console and cycling through the suggested properties and methods. Which property of the above string has the expected value? #> $PropertyName = '__' $String.$PropertyName | Should -Be 6 } It 'can also find useful methods' { $String = "Methods are handy!" # Methods can be accessed just like properties, but have parentheses and often parameters! $String.EndsWith('__') | Should -BeTrue <# If you have trouble figuring out which parameters a method requires, you can check the OverloadDefinitions by calling the method name without the parentheses. For the above method, these look like this: PS> 'string'.EndsWith OverloadDefinitions ------------------- bool EndsWith(string value) bool EndsWith(string value, System.StringComparison comparisonType) bool EndsWith(string value, bool ignoreCase, cultureinfo culture) Note that each overload is separate, and mentions what object type it returns first, followed by the type and number of arguments it will accept. Only one overload can be used at a time, and usually the number of arguments and type of the arguments determine the overload that PowerShell will apply when calling the method. #> $MethodName = '__' $MethodArguments = @('__', '__') # The ForEach-Object cmdlet can be used to call methods as well. '7', '8', '9', '10' | ForEach-Object -MemberName $MethodName -ArgumentList $MethodArguments | Should -Be @('000007', '000008', '000009', '000010') } } Context 'Members of objects returned from cmdlets' { It 'can help you discover information about unfamiliar objects' { # Cmdlets also return objects! This cmdlet creates an empty .tmp file in a random location, # and returns the object representation of this file. $TempFile = New-TemporaryFile Test-Path -Path $TempFile.FullName | Should -BeTrue $TempFiles = 1..10 | ForEach-Object { New-TemporaryFile } # Which method can be used to remove these files? $MethodName = '__' $TempFiles | ForEach-Object $MethodName $TempFiles | Test-Path | Should -BeFalse } It 'actually returns objects itself' { $MemberData = 'string' | Get-Member # We can all betray our own selves. $MemberData | Should -BeOfType __ } } } |