#requires -version 3.0

Function Update-PowerShellHelp {
<#
.Synopsis
Download PowerShell v3 help from a local source
.Description
This command will download PowerShell help from a local source. The assumption
is that there is a separate process that periodically downloads help to a 
folder or network share. This command downloads the help every 24 hours and
after the scheduled download time. The last update time is stored in the
registry.  The command will create the registry entries if they don't exist.

You can force a download using the -Force parameter which will. This command
also supports -Whatif. Use with -Verbose for testing.

Update-Help is culture-dependent. This version assumes an EN-US culture by
default but you can specify alternate cultures.

To use, dot source the function in your profile and then call the command.

This command requires PowerShell v3 or later.
.Parameter Source
The local path to the PowerShell help files
.Parameter UICulture
.Parameter Hour
The number of the hour for the scheduled update. For example,
if help is scheduled to update at 6:00AM, use a value of 6.
.Parameter Force
Download help regardless of the last time.
.Link
Update-Help
Save-Help
About_Updatable_Help
#>

[cmdletbinding(SupportsShouldProcess=$True)]

Param(
[Parameter(Position=0)]
[ValidateScript({Test-Path $_})]
[String]$Source="\\jdh-nvnas\files\PowerShell_Help",
[CultureInfo[]]$UICulture,
[ValidateRange(1,24)]
[int]$Hour=6,
[Switch]$Force
)

Write-Verbose "Starting $($myinvocation.MyCommand)"
If ($Force) {
    Write-Verbose "Force enabled"
}

#define the path to the registry key
$regpath = "HKCU:\MyPowerShell"
$regkey = "HelpUpdate"

#define a boolean indicating whether an update is needed
$UpdateNeeded=$False

Try {
    #test for existing registry key
    Write-Verbose "Getting $regkey ItemProperty under $regpath"
    [datetime]$LastUpdate = Get-ItemProperty -Path $regpath -Name $regkey -ErrorAction Stop |
       Select-Object -ExpandProperty $regkey
    
    Write-Verbose "Lastupdate is $LastUpdate"
    $now=Get-Date
    Write-Verbose "It is now $now"
    
    <#
        Define a variable to show when the download should 
        happen today. $Now.Date will be datetime object
        with a time of midnight. The help download task is
        scheduled for 6:00 AM so add six hours.
    #>    
    $download=$now.Date.AddHours($hour)
    Write-Verbose "Today's help download scheduled for $Download"
    <#
        compare lastupdate value to current time and download
        time. 24 hours must have elapsed between the last download
        and the current time AND the current time must be later
        than the download time.
    #>
    If ((($now-$lastupdate).totalhours -ge 24) -AND ($now -gt $download) ) {
        $UpdateNeeded=$True
    }
}
Catch {
    #if no key, create it
    if (-Not (Test-Path -Path $regpath)) {
        Write-Verbose "Creating registry key"
        New-Item -Path $regpath 
    } #if not test-path
    else {
        Write-Verbose "Path $regpath exists. Key must be missing"
    }
    $UpdateNeeded=$True
}

#run update if needed or if -Force is used
If ($UpdateNeeded -Or $Force) {
    #update help from local source
    Write-Verbose "Updating PowerShell help from $Source"
    
    if ($PSCmdlet.ShouldProcess("$env:computername from $source")) {
        $cmd="Update-Help -SourcePath $Source -Force -Recurse"
        if ($UICulture) {
            Write-Verbose "Adding UICulture"
            $cmd+=" -UICulture $($UICulture -join ",")"
        }
        Invoke-Expression -Command $cmd
        Write-Verbose "Updating registry"
        Set-ItemProperty -Path $regpath -Name $regkey -Value (Get-Date)
    } #if should process
}
else {
    $msg = "Help last updated $LastUpdate. No download needed."
    Write-Verbose $msg
    Write-Host $msg -ForegroundColor Yellow
}

Write-Verbose "Ending $($myinvocation.MyCommand)"

} #end function