How To Use Write-Host Without Endangering Puppies (or, A Manifesto for Modularizing PowerShell Scripts)

Fri, 15 Jun 2012 01:04:00 +0000

At this week’s TechEd, I was speaking with Jeffrey Snover in the hallway on Wednesday when he remarked, “you know, Write-Host isn’t all bad.” After he got someone to come around with smelling salts to revive me, he elaborated, “so long as your verb is Show.” I started to object - and then a subtle, yet brilliant light came upon me.

He’s write. Heh.

But, seriously, if you do three simple things, you can’t go wrong when you write a PowerShell script or function - and this goes further than just Write-Host. Ask yourself:

Am I naming my script/function according to PowerShell verb-noun naming conventions?
Am I only using allowed verbs (run Get-Verb for a list)?
Am Irespecting the use of the verb I chose?

That last one’s the doozy. But think about it: If your verb is Get, then your function/script *should just get stuff. *It shouldn’t manipulate it. Shouldn’t format it. Shouldn’t (generally) change bytes into megabytes, or anything else. Just get the data, and output a single kind of object to the pipeline, using Write-Output. That’s it.

Ok, if you want some step-by-step progress information as it runs, use Write-Verbose. That’s cool. Or use Write-Debug for trace code, if you need.

The Get verb implies that you may want to do something else with the data. Convert it to HTML. Export it to CSV. Whatever. And so you just output raw objects. Need to put that data into a database? Fine, create an “Export-MyStuffToDatabase” function that does that - the Export verb makes it clear that the data is “leaving the shell” and going elsewhere.

Want to display the data on-screen? *Write a “Show-Whatever” function. *The Show verbimplies on-screendisplay. You’d never think to run something like “Get-Service | Show-ServiceData | Export-CSV.” The Show verb tells you that “this is going to the screen, and by God it isn’t going anywhere else.” So if you’re using the Show verb… go ahead and use Write-Host. *That’s what it’s for. *No puppies will be harmed.

This gets back to my bigger design philosophy of *make each function/script do only one thing. *Each should automate sometask, and should act appropriately for the verb you’ve chosen. If you have a functionGetting something as well asFormatting the output… that’s two things. You’ll also write larger scripts that automate *processes, *and those should generally just be calling sequences of your task-automating commands. A task, then, is something you might use in several different scenarios; a process is one such scenario that employs several tasks.

Provisioning a new user? You’ve got tasks like New-ADUser, Add-ADGroupMember, New-UserHomeShare, New-HREmployeeRecord, and so on. But those tasks (some of which you’d write yourself, obviously) might be used in other circumstances: New-ADUser, for example, might also be used when you need to set up a new SQL Server and create an AD service account, right? With all the tasks written, you’d write a larger “process” script, perhaps called New-CompanyUser.ps1, which combined those various tasks into the sequence needed to provision a user - while leaving the tasks free to be used in other processes as well.

Stick with the verbs, my friend. They won’t lead you astray.

]]>

Using PowerShell to Scrape the Web

Thu, 07 Jun 2012 14:22:00 +0000

One of the things administrators often look to do with PowerShell is “scrape” Web pages. In the past, you had a couple of options: Use Internet Explorer’s COM object (which can get a bit fugly), or use the .NET Framework’s WebRequest stuff (slightly less fugly, but still a bit).

PowerShell v3 to the rescue. Microsoft has wrapped much of the fugly in some cool and simple cmdlets, and given PowerShell a native ability to understand an HTML document’s object model (DOM). Note that the ability to parse the HTML document tree is dependent upon IE being installed, which means it won’t work on a Server Core system (since IE doesn’t exist there). You’ll still get some HTML parsing, but it won’t be the full, broken-down tree.

Start by running Invoke-WebRequest, passing it a -URI with the URL of the Web page you want to download. It’ll handle the full task of connecting to the Web server, getting the text of the HTML page, and parsing it. Other parameters let you specify a -Credential, modify the HTTP -Headers, redirect the text to an -OutFile so that you have a local copy, specify -Proxy settings, and more. You’ll specify -UseBasicParsing when IE isn’t available.

What you get back (store it in a variable to work with it) is an HTML response. it’ll have a StatusCode property, a Content property, and more. What’s useful are some of the parsed properties:

Images - all the tags
InputFields - all form fields
Links - all tags
Forms - all tags

These are collections of objects, each one giving you access to the most commonly-needed data from he HTML. You can easily grab all of the images, links, and so forth, and process them however you like. For example, assume that you put your HTML results in $html. Run $html.links[0].href to get the destination of the first hyperlink in the page. Cool!

Here’s a quick example that grabs the first page of search result links from a Bing search for “cmdlet:”

0 1 68 392 Concentrated Technology 3 1 459 14.0 Normal 0 false false false EN-US JA X-NONE

PS C:\> Invoke-WebRequest -uri

‘http://www.bing.com/search?q=cmdlet&form=AP

MCS1' | select -expand links | select -expand href -first 10
/?scope=web&FORM=Z9FD
/images/search?q=cmdlet&FORM=BIFD
/videos/search?q=cmdlet&FORM=BVFD
/shopping/search?q=cmdlet&mkt=en-US&FORM=BPFD
/news/search?q=cmdlet&FORM=BNFD
/maps/default.aspx?q=cmdlet&mkt=en-US&FORM=BYFD
/explore?q=cmdlet&FORM=BXFD
http://www.msn.com/
http://mail.live.com/

Now that’s just nifty. And it works fine against local HTML pages as well as ones served up from a Web server. There’s obviously a LOT more you can do, but this should give you a great starting point!

This article was inspired by the chapter “Working with HTML and XML Data” in the upcomingPowerShell in Depth, co-authored with Jeffery Hicks and Richard Siddaway. That book can be purchased from the publisher, and isavailable directly from the authors in a signed, limited edition package.

]]>

FInal Outlines for the v3 "Lunches" Books

Sun, 03 Jun 2012 13:35:00 +0000

1
1095
6247
Concentrated Technology
52
14
7328
14.0
Normal

false
false
false
EN-US
JA
X-NONE

I wanted to get these posted for folks’ reference. The books are proceeding apace, and now that PowerShell v3 is in Release Candidate, we’re going to move forward with publication ASAP.

ToC – “Learn Windows PowerShell 3 in a Month of Lunches”

Before You Begin

a.
Why You Can’t Afford to Ignore PowerShell

b.
Is This Book for You?

c.
How to Use this Book

i. The
Main Chapters

ii. Hands-On
Labs

iii. Supplementary
Materials

iv. Further
Exploration

v. Above
and Beyond

d.
Setting up Your Lab Environment

e.
Installing Windows PowerShell

f.
Online Resources

g.
BeingImmediately
Effective with PowerShell

Meet PowerShell

a.
Choose Your Weapon

b.
The Console Window

c.
The Integrated Scripting Environment

d.
It’s Typing Class All Over Again!

e.
What Version is This?

f.
Common Points of Confusion

g.
Lab

h.
Further
Exploration

Using the Help System

a.
The Help System: How You Discover Commands

b.
Updatable Help

c.
Asking for Help

d.
Using Help to Find Commands

e.
Interpreting the Help

i. Parameter
Sets and Common Parameters

ii. Optional
and Mandatory Parameters

iii. Positional
Parameters

iv. Parameter
Values

v. Examples

f.
Accessing “About” Topics

g.
Accessing Online Help

h.
Lab

Running Commands

a.
Not Scripting: Just Running Commands

b.
The Anatomy of a Command

c.
The Cmdlet Naming Convention

d.
Aliases: Nicknames for Commands

e.
Taking Shortcuts

i. Truncating
Parameter Names

ii. Parameter
Name Aliases

iii. Positional
Parameters

f.
Cheating, a Bit: Show-Command

g.
Support for External Commands

h.
Dealing With Errors

i.
Common Points of Confusion

i. Typing
Cmdlet Names

ii. Typing
Parameters

j.
Lab

Working with Providers

a.
What are Providers?

b.
How the File System is Organized

c.
How the File System is Like Other Data Stores

d.
Navigating the File System

e.
Using Wildcards and Literal Paths

f.
Working with Other Providers

g.
Lab

h.
Further
Exploration

The Pipeline: Connecting Commands

a.
Connect One Command to Another: Less Work For
You!

b.
Exporting to a CSV or XML File

c.
Piping to a File or Printer

d.
Converting to HTML

e.
Using Cmdlets That Modify the System: Killing
Processes and Stopping Services

f.
Common Points of Confusion

g.
Lab

Adding Commands

a.
How One Shell Can Do Everything

b.
About Product-Specific “Management Shells”

c.
Extensions: Finding and Adding Snap-Ins

d.
Extensions: Finding and Adding Modules

e.
Playing With a New Module

f.
Profile Scripts: Preloading Extensions When the
Shell Starts

g.
Common Points of Confusion

h.
Lab

“Objects:”
Just Data by Another Name

a.
What are Objects?

b.
Why PowerShell Uses Objects

c.
Discovering Objects: Get-Member

d.
Object Attributes, or “Properties”

e.
Object Actions, or “Methods”

f.
Sorting Objects

g.
Selecting the Properties You Want

h.
Objects Until the Very End

i.
Common Points of Confusion

j.
Lab

The Pipeline, Deeper

a.
The Pipeline: Enabling Power With Less Typing

b.
How PowerShell Passes Data Down the Pipeline

c.
Plan A: Pipeline Input ByValue

d.
Plan B: Pipeline Input ByPropertyName

e.
When Things Don’t Line Up: Custom Properties

f.
Parenthetical Commands

g.
Extracting the Value from a Single Property

h.
Lab

Formatting

and Why it’s Done on the Right

a.
Formatting: Making What You See Prettier

b.
About the Default Formatting

c.
Formatting Tables

d.
Formatting Lists

e.
Formatting Wide

f.
Custom Columns and List Entries

g.
Going Out: To a File, a Printer, or the Host

h.
Another Out: GridViews

i.
Common Points of Confusion

i. Always
Format Right

ii. One
Object at a Time, Please

j.
Lab

k.
Further
Exploration

Filtering
and Comparisons

a.
Making the Shell Give You Just What You Need

b.
Filter Left

c.
Comparison Operators

d.
Filtering Objects out of the Pipeline

e.
The Iterative Command-Line Model

f.
Common Points of Confusion

i. Filter
Left, Please

ii. When
$_ is Allowed

g.
Lab

h.
Further
Exploration

A
Practical Interlude

a.
Defining the Task

b.
Finding the Commands

c.
Learning to Use the Commands

d.
Tips for Teaching Yourself

e.
Lab

Remote
Control: One on One, and One to Many

a.
The Idea Behind Remote PowerShell

b.
WinRM Overview

c.
Using Enter-PSSession and Exit-PSSession for
One-to-one Remoting

d.
Using Invoke-Command for One-to-many Remoting

e.
Differences Between Remote and Local Commands

i. Invoke-Command
vs -ComputerName

ii. Local
vs Remote Processing

iii. Deserialized
Objects

f.
But Wait, There’s More

g.
Remoting Options

h.
Common Points of Confusion

i.
Lab

j.
Further
Exploration

Using
Windows Management Instrumentation

a.
WMI Essentials

b.
The Bad News About WMI

c.
Exploring WMI

d.
Choose Your Weapon: WMI or CIM

e.
Using Get-WmiObject

f.
Using Get-Ciminstance

g.
WMI Documentation

h.
Common Points of Confusion

i.
Lab

j.
Further
Exploration

Multitasking
with Background Jobs

a.
Making PowerShell Do Multiple Things at the Same
Time

b.
Synchronous versus Asynchronous

c.
Creating a Local Job

d.
WMI, as a Job

e.
Remoting, as a Job

f.
Getting Job Results

g.
Working with Child Jobs

h.
Commands for Managing Jobs

i.
Scheduled Jobs

j.
Common Points of Confusion

k.
Lab

Working
with Bunches of Objects, One at a Time

a.
Automation for Mass Management

b.
The Preferred Way: “Batch” Cmdlets

c.
The WMI Way: Invoking WMI Methods

d.
The Backup Plan: Enumerating Objects

e.
Common Points of Confusion

i. Which
Way is the Right Way?

ii. WMI
Methods versus Cmdlets

iii. Method
Documentation

iv. ForEach-Object
Confusion

f.
Lab

Security
Alert!

a.
Keeping the Shell Secure

b.
Windows PowerShell Security Goals

c.
Execution Policy and Code Signing

i. Execution
Policy Settings

ii. Digital
Code Signing

d.
Other Security Measures

e.
Other Security Holes?

f.
Security Recommendations

g.
Lab

Variables:
A Place to Store Your Stuff

a.
Introduction to Variables

b.
Storing Values in Variables

c.
Fun Tricks with Quotes

d.
Storing Lots of Objects in a Variable

e.
More Tricks with Double Quotes

f.
Declaring a Variable’s Type

g.
Commands for Working with Variables

h.
Variable Best Practices

i.
Common Points of Confusion

j.
Lab

k.
Further
Exploration

Input
and Output

a.
Prompting For, and Displaying, Information

b.
Read-Host

c.
Write-Host

d.
Write-Output

e.
Other Ways to Write

f.
Lab

g.
Further
Exploration

Sessions:
Remote Control, with Less Work

a.
Making PowerShell Remoting a Bit Easier

b.
Creating and Using Reusable Sessions

c.
Using Sessions with Enter-PSSession

d.
Using Sessions with Invoke-Command

e.
Implicit Remoting: Importing a Session

f.
Disconnected Sessions

g.
Lab

h.
Further
Exploration

You
Call This Scripting?

a.
Not Programming… More Like Batch Files

b.
Making Commands Repeatable

c.
Parameterizing Commands

d.
Creating a Parameterized Script

e.
Documenting Your Script

f.
One Script, One Pipeline

g.
A Quick Look at Scope

h.
Lab

Improving
Your Parameterized Script

a.
Starting Point

b.
Getting PowerShell to do the Hard Work

c.
Making Parameters Mandatory

d.
Adding Parameter Aliases

e.
Validating Parameter Input

f.
Adding the Warm and Fuzzies with Verbose Output

g.
Lab

Advanced
Remoting Configuration

a.
Using Other Endpoints

b.
Creating Custom Endpoints

i. Creating
the Session Configuration

ii. Registering
the Session

c.
Enabling Multi-Hop Remoting

d.
Digging Deep into Remoting Authentication

i. Defaults
for Mutual Authentication

ii. Mutual
Authentication via SSL

iii. Mutual
Authentication via TrustedHosts

e.
Lab

Using
Regular Expressions to Parse Text Files

a.
The Purpose of Regular Expressions

b.
A RegEx Syntax Primer

c.
Using RegEx with -Match

d.
Using RegEx with Select-String

e.
Lab

f.
Further
Exploration

Additional
Random Tips, Tricks, and Techniques

a.
Profiles, Prompts and Colors: Customizing the
Shell

i. PowerShell
Profiles

ii. Customizing
the Prompt

iii. Tweaking
Colors

b.
More Operators: -as, -is, -replace, -join,
-split

i. -as
and -is

ii. -replace

iii. -join
and -split

iv. -contains
and -in

c.
String Manipulation

d.
Date Manipulation

e.
Dealing with WMI Dates

f.
Setting Default Parameter Values

g.
Playing with Script Blocks

Using
Someone Else’s Script

a.
The Script

b.
It’s a Line-by-line Examination

c.
Lab

Never
the End

a.
Ideas for Further Exploration

b.
“Now That I’m Done, Where Do I Start?”

c.
Other Resources You’ll Grow to Love

PowerShell
Cheat Sheet

a.
Punctuation

b.
Help File

c.
Operators

d.
Custom Property and Column Syntax

e.
Pipeline Parameter Input

f.
When to Use $_

Appendix
A: Review Labs

a.
Review Lab 1 (Chapters 1-6)

b.
Review Lab 2 (Chapters 1-14)

c.
Review Lab 3 (Chapters 1-19)

1
784
4474
Concentrated Technology
37
10
5248
14.0
Normal

false
false
false
EN-US
JA
X-NONE

ToC – “PowerShell Scripting and Toolmaking in a Month of Lunches”

Part I: Introduction
to Toolmaking

Before You Begin

a.
What is Toolmaking?

b.
Is This Book for You?

c.
Pre-Requisites

i. PowerShell
v3

ii. Admin
Privileges

iii. Multiple
Computers

iv. SQL
Server

v. PowerShell
ISE

vi. Optional
Pre-Requisites

d.
How To Use this Book

PowerShell Scripting Overview

a.
Whatis
PowerShell Scripting?

b.
PowerShell’s Execution Policy

c.
Running Scripts

d.
Editing Scripts

e.
Further
Exploration: Script Editors

f.
Lab

PowerShell’s Scripting Language

a.
One Script, One Pipeline

b.
Variables

c.
Quotation Marks

d.
Object Members and Variables

e.
Parentheses

f.
Refresher: Comparisons

g.
Logical Constructs

i. If
Construct

ii. Switch
Construct

h.
Looping Constructs

i. Do…While
Construct

ii. ForEach
Construct

iii. For
Construct

i.
Break and Continue in Constructs

j.
Lab

Simple Scripts and Functions

a.
Start with a Command

b.
Turn the Command into a Script

c.
Parameterize the Command

d.
Turning the Script into a Function

e.
Testing the Function

i. Dot-Sourcing

ii. Calling
the Function in the Script

iii. A
Better Way Ahead: Script Modules

f.
Lab

Scope

a.
What is Scope?

b.
Seeing Scope in Action

c.
Working Out-of-Scope

d.
Getting Strict with Scope

e.
Best Practices for Scope

f.
Lab

Part II: Building an
Inventory Tool

Tool Design Guidelines

a.
Do One Thing, and Do it Well

i. Input
Tools

ii. Functional
Tools

iii. Output
Tools

b.
Lab

Advanced Functions, Part 1

a.
Advanced Function Template

b.
Designing the Function

c.
Declaring Parameters

d.
Testing the Parameters

e.
Writing the Main Code

f.
Outputting Custom Objects

g.
What Not to Do

h.
Coming Up Next

i.
Lab

Advanced Functions, Part 2

a.
Making Parameters Mandatory

b.
Verbose Output

c.
Parameter Aliases

d.
Accepting Pipeline Input

e.
Parameter Validation

f.
Adding a Switch Parameter

g.
Parameter Help

h.
Coming Up Next

i.
Lab

Writing Help

a.
Comment-Based Help

b.
XML-Based Help

c.
Coming Up Next

d.
Lab

Error
Handling

a.
It’s All About the Action

b.
Setting the Error Action

c.
Saving the Error

d.
Error Handling v1: Trap

e.
Error Handling v2+: Try…Catch…Finally

f.
Providing Some Visuals

g.
Coming Up Next

h.
Lab

Debugging
Techniques

a.
Two Types of Bugs

b.
Solving Typos

c.
The Real Trick to Debugging: Expectations

d.
Dealing with Logic Errors: Trace Code

e.
Dealing with Logic Errors: Breakpoints

f.
Seriously, Have Expectations

g.
Coming Up Next

h.
Lab

Creating
Custom Format Views

a.
The Anatomy of a View

b.
Adding a Type Name to Output Objects

c.
Making a View

d.
Loading and Debugging the View

e.
Using the View

f.
Coming Up Next

g.
Lab

Script
and Manifest Modules

a.
Introducing Modules

i. Module
Location

ii. Module
Name

iii. Module
Contents

b.
Creating a Script Module

c.
Creating a Module Manifest

d.
Creating a Module-Level Setting Variable

e.
Coming Up Next

f.
Lab

Adding
Database Access

a.
Simplifying Database Access

b.
Setting Up Your Environment

c.
The Database Functions

d.
About the Database Functions

e.
Using the Database Functions

f.
Lab

Interlude:
Creating a New Tool

a.
Designing the Tool

b.
Writing and testing the Function

c.
Dressing Up the Parameters

d.
Adding Help

e.
Handling Errors

f.
Creating a Custom Format View

g.
Making a Module

h.
Coming Up Next

Part III: Advanced
Toolmaking Techniques

Making
Tools that Make Changes

a.
The -Confirm and -WhatIf Parameters

b.
Passthrough ShouldProcess

c.
Defining the Impact Level

d.
Implementing ShouldProcess

**e.
**Lab

Creating
a Custom Type Extension

a.
The Anatomy of an Extension

b.
Creating a Script Property

c.
Creating a Script Method

d.
Loading the Extension

e.
Testing the Extension

f.
Adding the Extension to a Manifest

g.
Lab

Creating
PowerShell Workflows

a.
Workflow Overview

i. Common
Parameters for Workflows

ii. Activities
and Stateless Execution

iii. Persisting
State

iv. Suspending
and Resuming Workflows

v. Inherently
Remotable

vi. Parallelism

b.
General Workflow Design Strategy

c.
Example Workflow Scenario

d.
Writing the Workflow

e.
Workflows vs. Functions

f.
Lab

Troubleshooting
Pipeline Input

a.
Refresher: How Pipeline Input Works

b.
Introducing Trace-Command

c.
Interpreting Trace-Command Output

d.
Lab

Using
Object Hierarchies for Complex Output

a.
When a Hierarchy Might be Necessary

b.
Hierarchies and CSV: Not a Good Idea

c.
Creating Nested Objects

d.
Working with Nested Objects

i. Using
Select-Object to Expand Child Objects

ii. Using
Format-Custom to Expand an Object Hierarchy

iii. Using
a ForEach Loop to Enumerate Sub-Objects

iv. Using
PowerShell’s Array Syntax to Access Individual Sub-Objects

f.
Lab

Globalizing
a Function

a.
Introduction to Globalization and Localization

b.
PowerShell’s Data Language

c.
Storing Translated Strings

d.
Do You Need to Globalize?

e.
Lab

Crossing
the Line: Utilizing the .NET Framework

a.
.NET Classes and Instances

b.
Static Methods of a Class

c.
Instantiating a Class

d.
Using Reflection

e.
Finding Class Documentation

f.
PowerShell vs. Visual Studio

g.
Lab

Part IV: Creating
Tools for Delegated Administration

Creating
a GUI Tool, Part 1: The GUI

a.
Introduction to WinForms

b.
Using a GUI to create the GUI

c.
Manually Coding the GUI

d.
Showing the GUI

e.
Lab

Creating
a GUI Tool, Part 2: The Code

a.
Addressing GUI Objects

b.
Example: Text Boxes

c.
Example: Button Clicks

d.
Example: List Boxes

e.
Lab

Creating
a GUI Tool, Part 3: The Output

a.
Using Out-GridView

b.
Creating a Form for Output

c.
Populating and Showing the Output

d.
Lab

Creating
Proxy Functions

a.
What are Proxy Functions?

b.
Creating the Proxy Function Template

c.
Removing a Parameter

d.
Adding a Parameter

e.
Loading the Proxy Function

f.
Lab

Setting
Up Constrained Remoting Endpoints

a.
Refresher: Remoting Architecture

b.
What are Constrained Endpoints?

c.
Creating the Endpoint Definition

d.
Registering the Endpoint

e.
Connecting to the Endpoint

f.
Lab

Conclusion

Never
the End

a.
Welcome to Toolmaking

b.
Cool Ideas for Tools

c.
What’s Your Next Step?

]]>

Articles from June 2012 on PowerShell.org - Welcome Automaters!

Upcoming PowerShell Books and How to Get Them

PowerShell In Depth

[UPDATED] Snover School: FANCY Wildcards

TechEd PowerShell Sessions

How To Use Write-Host Without Endangering Puppies (or, A Manifesto for Modularizing PowerShell Scripts)

Sample Code from my TechEd "Building Reusable PowerShell Tools" Session

Using PowerShell to Scrape the Web

[UPDATED] Tweaks to PowerShel v3 Updatable Help

FInal Outlines for the v3 "Lunches" Books

Looking for a good tech conference? Try this.

Articles from June 2012 on PowerShell.org - Welcome Automaters!

Upcoming PowerShell Books and How to Get Them

PowerShell In Depth

The “Month of Lunches” Books