Comment-based help in PowerShell - Mini Project: Build & Apply

Comment-based help

📖 Scenario: You are creating a PowerShell script that performs a simple task. To help others understand and use your script easily, you will add comment-based help. This is like writing instructions inside your script so anyone can see how to use it by typing Get-Help.

🎯 Goal: Build a PowerShell script with comment-based help that describes the script's purpose, syntax, parameters, and examples.

📋 What You'll Learn

Create a PowerShell script named Get-Greeting.ps1.

Add comment-based help with .SYNOPSIS, .DESCRIPTION, .PARAMETER, and .EXAMPLE sections.

Include a parameter called Name that accepts a string.

Write a simple script that outputs a greeting message using the Name parameter.

Display the help content using Get-Help.

💡 Why This Matters

🌍 Real World

Comment-based help is used in real PowerShell scripts and modules to provide users with clear instructions on how to use commands and scripts.

💼 Career

Knowing how to write comment-based help is important for system administrators, DevOps engineers, and anyone who writes PowerShell scripts professionally to improve script usability and maintainability.

1

Create the script with a Name parameter

Create a PowerShell script named Get-Greeting.ps1 with a parameter called Name that accepts a string. The script should output a greeting message using Name. Write the line: param([string]$Name) and a line that outputs "Hello, $Name!".

PowerShell

# Create a parameter called Name and output a greeting message
# Your code here

Need a hint?

Use param([string]$Name) to declare the parameter. Use Write-Output to print the greeting.

2

Add the .SYNOPSIS and .DESCRIPTION sections

Add comment-based help at the top of the script with .SYNOPSIS describing the script as "Outputs a greeting message." and .DESCRIPTION describing it as "This script takes a name and prints a greeting message." Use the <# and #> comment block.

PowerShell

param([string]$Name)

Write-Output "Hello, $Name!"

Need a hint?

Use a comment block starting with <# and ending with #>. Inside, add .SYNOPSIS and .DESCRIPTION lines.

3

Add the .PARAMETER and .EXAMPLE sections

Inside the comment-based help block, add a .PARAMETER Name section describing it as "The name of the person to greet." Then add an .EXAMPLE section showing how to run the script with -Name "Alice".

PowerShell

param([string]$Name)

Write-Output "Hello, $Name!"

Need a hint?

Inside the comment block, add .PARAMETER Name and describe it. Then add .EXAMPLE with a usage example.

4

Display the help content using Get-Help

Run the command Get-Help .\Get-Greeting.ps1 in PowerShell to display the comment-based help you added.

PowerShell

# Run the command below in PowerShell
# Your code here

Need a hint?

Type Get-Help .\Get-Greeting.ps1 in PowerShell to see your help content.