asif/ps-cmdlet-wol
1
0
Fork 0
Code Issues Pull Requests Releases 3 Activity

feature(magicpacket): add comment-based help

Browse Source 
- add help text
- include examples
- add pipeline assistance text
- clean-up code format
This commit is contained in:
Asif Bacchus 2021-09-04 02:18:26 -06:00
parent ec2e204a27
commit 0b8f04561b
1 changed files with 47 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

49
wol-magicPacket.psm1
View File

@ -1,16 +1,61 @@
<#
.SYNOPSIS
Broadcast one or more "magic packets" across a subnet to wake-up one or more target computers.
.DESCRIPTION
Sends a configurable number of "magic packets" per supplied MAC address as a broadcast over the subnet using a specified UDP port. MAC addresses can be supplied directly or via the pipeline either with or without explicitly specifying a parameter. The broadcast address and UDP port can be specified via parameters.
Note: You must specify the '-Verbose' parameter to see output for successfully sent packets.
.PARAMETER MacAddress
Array of MAC addresses for which to construct magic packets. The array should be provided in standard comma-separated string format ('1a:2a:3a:4a:5a:aa', '1b:2b:3b:4b:5b:bb', ...). You may use either a colon (:) or a hyphen (-) to delimit each hex value-pair in the MAC address. You may supply this array either directly or via the pipline.
.PARAMETER BroadcastIP
The address to which magic packets should be sent in order for them to be broadcast across the subnet. By default this is 255.255.255.255 however, many routers block such global broadcasts. Therefore, it is suggested to use the subnet-specific broadcast address (e.g. 192.168.1.255). You may also use IP6 addresses if you prefer.
.PARAMETER Port
The UDP port that should be used when sending the broadcast. By default this is port 7 (echo). Port 9 (discard) is also a common port.
.INPUTS
String array or object containing a string array named "MacAddress".
.EXAMPLE
Send-MagicPacket 1a-2a-3a-4a-5a-aa
Wake-up a computer with MAC address '1a-2a-3a-4a-5a-aa' via global broadcast using default port (echo).
.EXAMPLE
Send-MagicPacket '1a-2a-3a-4a-5a-aa' 192.168.1.255 9
Wake-up a computer with MAC address '1a-2a-3a-4a-5a-aa' in subnet 192.168.1.0/24 using port 9 (discard).
.EXAMPLE
Send-MagicPacket -MacAddress '1a-2a-3a-4a-5a-aa', '1b-2b-3b-4b-5b-bb', '1c:2c:3c:4c:5c:cc' -Port 99 -BroadcastIP 10.0.1.255 -Verbose
Wake-up 3 computers in the specified subnet using non-standard port. Parameters are explicitly defined. Show confirmation messages for each MAC address.
.EXAMPLE
'1a-2a-3a-4a-5a-aa', '1b-2b-3b-4b-5b-bb' | Send-MagicPacket -IP 172.16.20.255 -Verbose
Use pipeline to provide MAC addresses, provide broadcast address directly. Show result.
.NOTES
There is no output generated for successfully sent packets. This is done to keep the pipeline clear. To see success confirmation messages, run this function with the '-Verbose' parameter.
#>
function Send-MagicPacket
{
[CmdletBinding()]
param
(
# Array of MAC addresses for which to construct magic packets
[Parameter(Mandatory, ValueFromPipeline, ValueFromPipelineByPropertyName)]
[Parameter(
Mandatory,
ValueFromPipeline,
ValueFromPipelineByPropertyName,
HelpMessage = "Please provide one or more MAC addresses. You may use a colon (:) or a hypen (-) to separate hex values."
)]
[ValidatePattern('^([0-9A-F]{2}[:-]){5}([0-9A-F]{2})$')]
[String[]]
$MacAddress,
# Broadcast IP address (default: all subnets --> 255.255.255.255)
[Alias("IP","Address")]
[Alias("IP", "Address")]
[Parameter()]
[IPAddress]
$BroadcastIP = [System.Net.IPAddress]::Broadcast,