How to check (find) the newest online documentation

Last week I was playing with online documentation for PowerShell cmdlets. If you are not aware - if you specify -Online parameter for Get-Help cmdlet you are redirected to the most recent version located at Microsoft TechNet site. For example:

PS C:\> Get-Help Add-Computer -Online

redirects you to http://technet.microsoft.com/en-us/library/dd347556.aspx where you can check latest version of help.

I wanted to check latest version for cmdlets provided with PowerShell but I didn't want to go cmdlet by cmdlet and manually checked date of last update. As you know - everything in PowerShell is an object (incl. documentation) so I switched to the console and was looking for property storing link to online help. It was pretty easy and shortly I found right way. So after first check I received following results:

PS C:\> Get-Help Add-* |% {$_.relatedLinks.navigationLink} |? {$_.uri}

linkText uri
-------- ---
Online version: http://go.microsoft.com/fwlink/?LinkID=113279
Online version: http://go.microsoft.com/fwlink/?LinkID=113281
Online version: http://go.microsoft.com/fwlink/?LinkID=113280
Online version: http://go.microsoft.com/fwlink/?LinkID=135195
Online version: http://go.microsoft.com/fwlink/?LinkID=113278
Online version: http://go.microsoft.com/fwlink/?LinkID=135194

Then I was able to do quick check of date just by using my Get-WebPage function which uses DownloadString method of Net.WebClient class.

PS C:\> ... | Get-WebPage |% {$_ -match "</p>Updated:\s(?<date>.*?)</p>" | Out-Null ; $Matches.date }

May 20, 2009
October 21, 2009
October 21, 2009
February 17, 2010
February 17, 2010
February 17, 2010
February 17, 2010
February 17, 2010

Cool. But ... as you can see I have dates but no idea which help file to check :( So I decided to create short function (filter) which creates object for info I needed. I decided to store name of the cmdlet, web link and date of update. You can check Get-WebPage and New-TempObj (strange name - I know - but I wanted results quickly).

function Get-WebPage {

[Cmdletbinding()]

param (
    [Parameter(Mandatory=$true,
        Position=0,
        ValueFromPipeline=$true,
        HelpMessage="Enter URL to download")]
        [string]
        $Uri
)

BEGIN {
    $wc = New-Object System.Net.WebClient
    $proxy = [System.Net.WebProxy]::GetDefaultProxy()
    $proxy.UseDefaultCredentials = $true
    $wc.proxy = $proxy
}

PROCESS {
    $wc.DownloadString($Uri)
}

END { }

}

filter New-TempObj {

$hash = @{   
    name = $($_.Name)
    uri  = $($_.relatedLinks.navigationLink |? {$_.linkText -eq 'Online version:'}).uri
}
[datetime]$hash.date = Get-WebPage $hash.uri |% {$_ -match "<p>Updated:\s(?<date>.*?)</p>" | Out-Null; $Matches.date}

$myObj = New-Object PSObject -Property $hash
$myObj
} 

Now I am able to do following:

PS C:\> Get-Help Add-* | New-TempObj | ft -AutoSize

date name uri
---- ---- ---
20.5.2009 0:00:00 Add-History http://go.microsoft.com/fwlink/?LinkID=113279
20.5.2009 0:00:00 Add-PSSnapin http://go.microsoft.com/fwlink/?LinkID=113281
16.12.2009 0:00:00 Add-Member http://go.microsoft.com/fwlink/?LinkID=113280
20.5.2009 0:00:00 Add-Type http://go.microsoft.com/fwlink/?LinkID=135195
20.5.2009 0:00:00 Add-Content http://go.microsoft.com/fwlink/?LinkID=113278
17.6.2009 0:00:00 Add-Computer http://go.microsoft.com/fwlink/?LinkID=135194

Or - even better - all help files changed in 2010:

PS C:\> get-help *-* | New-TempObj |? { $_.date.Year -eq 2010 } | Select date, name

date name
---- ----
17.2.2010 0:00:00 Get-Counter
17.2.2010 0:00:00 Import-Counter
17.2.2010 0:00:00 Export-Counter
17.2.2010 0:00:00 Start-Job
20.1.2010 0:00:00 New-Module
17.2.2010 0:00:00 Get-Module
17.2.2010 0:00:00 Out-File
17.2.2010 0:00:00 Read-Host
17.2.2010 0:00:00 Export-Clixml
17.2.2010 0:00:00 Select-XML
17.2.2010 0:00:00 Join-Path
20.1.2010 0:00:00 Get-Location
20.1.2010 0:00:00 Set-Location
20.1.2010 0:00:00 Push-Location
20.1.2010 0:00:00 Pop-Location
20.1.2010 0:00:00 New-Item

So now I am able to read latest documentation everytime without any special manual work.

Note: As I said - whole "script" was created in a hurry and therefore it's not the best one I created. You can receive exceptions for some help files but it is not the case for standard cmdlets.

Windows PowerShell Community Doc Review

Před pár dny uveřejnil Shay Levy výzvu dobrovolníkům, kteří chtějí ovlivnit dokumentaci dostupnou v PowerShellu. Originální text:

”We're looking for users at all experience levels and with all different backgrounds, but we love to have beginners, people with no programming experience, people who know other scripting languages or shells, and people who are not native English speakers. If you're a system admin and you don't really know Windows PowerShell, this is a great way to learn it with help from insiders.”

Celý proces probíhá ve spolupráci Windows PowerShell documentation týmu a powershellcommunity.org. Pokud chcete ovlivnit dokumentaci, která je součástí PowerShellu, máte šanci. Napište buď June Blender (juneb@microsoft.com) nebo Marco Shawovi (marco.shaw@gmail.com). Opravdu nezáleží na tom, kolik toho umíte – důležitá je ochota udělat něco pro komunitu. Já jsem June napsal a již jsem dostal potvrzení, že jsem byl zařazen.

Pokud se vám nechce trávit moc času s procházením celé dokumentace, ale přesto jste nalezli nějakou chybu, můžete ji reportovat přes Microsoft Connect.

1. Ujistěte se, zda chyba existuje v on-line dokumentaci. Použijte parametr –Online v cmdletu Get-Help, např. Get-Help Get-Random –Online. Na webu je vždy poslední verze nápovědy.
2. Jděte na http://connect.microsoft.com/powershell
3. Klikněte na Report a bug (nejdříve se přes Search Feedback ujistěte, jestli nebyla stejná chyba již reportována).
4. Přihlašte se vaším LiveID.
5. Vyberte Documentation bug.
6. Vyplňte jednoduchý formulář a odešlete jej.

Každá takto reportovaná chyba jde přímo k June Blender. Pokud vás téma nápovědy zajímá, můžete June sledovat in na Twitteru.

Get-Help

Naši pouť po cmdletech začneme u jednoho z nejpoužívanějších (doufejme :) - Get-Help. Každý z nás byl někdy více či méně nespokojen z jakoukoli Microsoftí nápovědou (když pomineme lidi, kteří nápovědu nečtou, což je asi většina). V PowerShellu je ovšem Get-Help na velice dobré úrovni a doporučujeme jej používat. Základní variantou je čistě uvedení cmdletu bez parametrů:

Get-Help

Tento příkaz vypíše základní informace, ze kterých můžeme dále vycházet. Zobrazíme je všechny a ukážeme si na nich práci s nápovědou v PowerShellu (barevně jsme odlišili jednotlivé sekce - o nich si více povíme za chvíli).

TOPIC
    Get-Help

SHORT DESCRIPTION
    Displays help about PowerShell cmdlets and concepts.

LONG DESCRIPTION

SYNTAX
    get-help {<CmdletName> | <TopicName>}
    help {<CmdletName> | <TopicName>}
    <CmdletName> -?

    "Get-help" and "-?" display help on one page.
    "Help" displays help on multiple pages.

    Examples:
      get-help get-process : Displays help about the get-process cmdlet.
      get-help about-signing : Displays help about the signing concept.
      help where-object : Displays help about the where-object cmdlet.
      help about_foreach : Displays help about foreach loops in PowerShell.
      match-string -? : Displays help about the match-string cmdlet.

    You can use wildcard characters in the help commands (not with -?).
    If multiple help topics match, PowerShell displays a list of matching
    topics. If only one help topic matches, PowerShell displays the topic.

    Examples:
      get-help * : Displays all help topics.
      get-help get-* : Displays topics that begin with get-.
      help *object* : Displays topics with "object" in the name.
      get-help about* : Displays all conceptual topics.

    For information about wildcards, type:
      get-help about_wildcard

REMARKS
    To learn about PowerShell, read the following help topics:
      get-command : Displays a list of cmdlets.
      about_object : Explains the use of objects in PowerShell.
      get-member : Displays the properties of an object.

    Conceptual help files are named "about_<topic>", such as:
      about_regular_expression.

    The help commands also display the aliases on the system.
    For information about aliases, type:

      get-help about_alias

Každý help v PowerShellu je rozdělen do sekcí, které jsou volány v závislosti na parametrech cmdletu Get-Help (-detailed, -full). Názvy sekcí jsou následující:

• Name - jméno cmdletu
• Synopsis - krátký popis cmdletu
• Syntax - popis syntaxe
• Detailed Description - podbobnější popis funkce cmdletu
• Parameters - popis použítí všech parametrů
• Input Type - typ objektů, které cmdlet očekává na vstupu
• Return Type - typ výstupu
• Examples - příklady použití cmdletu
• Related Links - jména podobných cmdletů
• Remarks - informace o použití parametrů

Při volání Get-Help -full nám Get-Help vrátí všechny výše popsané sekce. Pro vypsání všech informací o cmdletu Get-WmiObject, tedy zapíšeme

Get-Help Get-WmiObject -full

Další zajímavou části nápovědy v PowerShellu je tématická nápověda. Poznáte ji podle toho, že její jméno začíná slovem about. Například Get-Help about_regular_expression vyvolá nápovědu o používání regulárních výrazů.

Domácí úkol: Projděte si všechny příklady v Get-Help a zapamatujte si je pro další použití :)