In The Scripting Games this year, more than a few folks took the time to write detailed comment-based help. Awesome. No debating it - comment-based help _is a good thing. _
But some folks felt that others took it too far. There were definitely scripts where the authors used, for example, the .NOTES section to explain their thinking and approach. Some commenters felt it was excessive, while others have pointed out, “wow, what if every programmer gave us some idea what the heck he/she was thinking at the time?” Some felt these extensive comments were just at attempt to get a better score by “convincing” the reviewer of an approach or tactic; others felt, “so what?”
So let’s leave the Games out of this debate - in a production environment, where do you come down on extensive notes in a script? When is it not enough, and when is it going too far? Where’s the value, and where’s the annoyance?
[boilerplate greatdebate]
You’ve probably been hearing about Desired State Configuration from a number of sources (Runas Radio, the PowerScripting Podcast, or the Channel 9 TechEd video for example). If you haven’t go check out those previously mentioned resources, I’ll wait…
Ok, now that you have a basic understanding of what Desired State Configuration (DSC) is, I have an announcement.
PowerShell.Org is building a repository of DSC modules for the community to use and contribute to.
As I’ve started working with Desired State Configuration, I began building up a repository of modules I would use in configuring my systems. I started to round them out with some basic documentation and decent logging messages and began pushing them to GitHub.
I’ve also seen several others starting to post some DSC modules on Github and elsewhere. Since we are very early in the Desired State Configuration lifecycle (it’s still not RTM yet), I would like our community to come together on a central location for our community contributions. I reached out to Don and the PowerShell.Org team and they graciously offered to host the contributions on the PowerShell.Org GitHub repository. What that means is that this effort is no longer under the control of one person (me), but owned by the community, by PowerShell.Org.
There’s not much in the repository yet, so if you’ve been experimenting with DSC and would like to share your efforts with the community, feel free to send a pull request (if you’re into the whole GitHub thing) or file an issue on the GitHub site and we’ll figure something out.
There is some basic “Getting Started With Developing DSC Modules” information at the GitHub repository as well.
Later this month, Jason Helmick will be offering a revised “PowerShell Scripting and Toolmaking” course at Interface Technical Training in Phoenix. This new course carries the Microsoft Courseware Marketplace number 55039 - that’s right, this is an official, unofficial course that will be available to all Microsoft training partners!
(Courseware Marketplace offerings are not written or endorsed by Microsoft, but they are equivalent to Official Curriculum in many ways, including being eligible for Software Assurance voucher programs. Marketplace offerings supplement Official offerings by providing courses that Microsoft doesn’t have the time or resources to generate themselves.)
This course is based directly on Learn PowerShell Toolmaking in a Month of Lunches, and incorporates much of that book’s actual text (in fact, a portion of the course’s sale price goes to the book publisher, with a portion of that going to the book authors as royalties). That’s combined with a full slide deck, some awesome brand-new labs, lab answer key, “starting points” (for lab students who fall behind), and a complete inventory of demo scripts for the instructor to use. It walks through a quick PowerShell review, and moves all the way through creating modules, advanced functions, custom views, and much more. It’s a pretty handy course, and even dives into creating “controller” scripts, such as scripts that automate processes or generate HTML reports. We provide a complete 3-VM build guide, and a simple ISO image containing all of the instructor and student files. Students are even welcome to download that ISO themselves for later reference! That URL will be provided in the student manual.
I’m especially proud of the labs, and thankful to Mike Robbins and Jason Helmick for debugging them for me. Through the main part of the course, students have three lab tracks (A, B, and C) to choose from - and overachievers can work on more than one track. Through each module, the labs gradually build from a basic command to a complete, fleshed-out “script cmdlet” packaged in a module, with a custom view and more. It’s extremely realistic, and it means much of the classroom time is spent on hands-on labs, where students will get the most value for their money.
This course is designed to complement Microsoft’s official 10961 course, which covers substantially the same material as Learn Windows PowerShell in a Month of Lunches, meaning 55039 is kind of a “sequel” course. Training centers are welcome to offer a 5-day accelerated class that combines both courses; that’s pretty much the class I teach myself. I don’t personally categorize 55039 as “advanced;” rather, it’s more of a specific application of PowerShell - building reusable tools. I do offer an advanced course of my own, and there’s a chance for that to become a packaged course in the future.
After the beta is complete, the course will be orderable in the Marketplace with a suggested price of $150 per student. It’s a full 5-day course, with multiple lab tracks per module, so I felt that was a pretty fair price, especially since students basically get the Toolmaking book “included” in their manual!
If any other trainers would like to know more about the course, they’re welcome to contact me. We will be selling it directly as well, for trainers who can’t access the Marketplace.
Download the table of contents: 55039-TOC
As most folks are aware, I’ve been writing the Windows PowerShell column for Microsoft’s _TechNet Magazine _for… wow, going on 7 years now. For 2013, I was doing a serialized column on PowerShell Workflow, introducing a bit of the technology at a time in each month’s article. Eagle-eyed observers will note that the series has “paused,” with no new articles in July or August.
First, I’m sorry for the interruption. Unfortunately, right now Microsoft is re-evaluating and re-positioning TechNet Magazine (perhaps in line with a larger re-considering of the TechNet brand, where they recently discontinued the subscription product), and for the time being the company is sticking with internally generated content for TechNet Magazine. I’m hopeful the company will come to a decision soon, and I’ll try and keep you posted here.
My past columns (all 77 of them) are still online and accessible, along with hundreds of other articles stretching back almost 8 years.
PowerShell Summit North America 2014, April 28-30 (special precon on April 27) is open for registration to our 2013 alumni, shareholders, and to TechLetter subscribers. The alumni block will be released on August 15, and the subscriber block on September 15th; shortly after, sales will be open to the public. If you’re a shareholder, alumni, or subscriber, and you didn’t get your registration in e-mail, drop me a line (use the Contact link in the Site Info menu). Please only contact me if you’re anxious to register right now, so I don’t get swamped.
North America will be in Bellevue, WA, adjacent to Microsoft offices up there; we will
investigate
a move East for the 2015 show, just to perhaps spread the love a bit. We know SEA isn’t the cheapest travel destination.
North America’s call for topics should start fairly soon, and that information will be posted here, along with information on how to submit prospective sessions. I won’t be taking the lead on that process, but some of my fellow Board members will be, so watch for their posts.
PowerShell Summit Europe 2014 is being tentatively scheduled for September or October 2014. Our city shortlist includes Munich, Milan, and Amsterdam; we’re too far out at this point to make inquiries with prospective venues (they usually work only 8-12 months out), but we’ve assembled a list to contact over the next couple of months. Venue pricing and availability (and suitability) will be a significant set of factors in the final city selection, and we’ll post details right here.
You’ll notice a “PowerShell Summit” post category here on PowerShell.org; that’s your one and official source for news and info, with our Summit Page being your one and official source for more static information on both events. You can follow @PSHSummit on Twitter, which will be a good way to receive notifications of new posts here, but which will not contain any information not available on this site. We also try to hashtag #PSHSummit on Twitter, if you’d like to watch out for that.
Soooo…. it’s time for me to start looking at updating my various training materials (books, videos, courses, whatnot) for v4.
I’m going to, with at least some of these, take an all-versions approach. I’ll teach what’s in v2, then cover what v3 added, then cover v4, etc. It’ll be easier to maintain over the upcoming years.
For right now, I’m trying to assemble an organized topic list of “everything” the shell does. Now, I need to wrap that in an important caveat: I’m aiming at admins. Not developers. I’m not saying devs aren’t a great audience, but for this project I need to constrain my scope to just the admin audience. I’m also focused mainly on what the shell does _natively, _with only a few diversions into external or underlying technologies. Those are fixed caveats for this project - no exceptions.
Right now I"m kind of chunking the list into what I feel can be taught (by me) in 20-30 minutes, or a book chapter, or something like that. This isn’t necessarily how the material will be presented - this is just me organizing my thoughts so as to not miss important stuff.
So, given the list below, what do you feel is missing?
(Numbers are major topics; letters are basically my mental notes about what the topic might include that I might otherwise forget; like I said, this isn’t meant to be a real book outline - it’s just a topic list)
PowerShell Core
One of the most frequent comments in The Scripting Games this year was along the lines of, “you should have submitted this as a function, not a script.” Of course, the second-most frequent comment was something like, “you shouldn’t have submitted this as a function.”
Let’s be clear: if an assignment explicitly asks for a function, you should write one. What we’re debating are the pros and cons of a single tool being written one way or another. Read that again: _a single tool. _If you’re writing a library of tools, it’s obvious that writing them as functions for inclusion in a single file (like a script module) is beneficial.
Some argue that any tool is potentially going to be included in a function… so why not write it that way to begin with? Others argue that functions are a smidge harder to test, so why not just write a script?
This is a debate I don’t personally have a strong stake in. I mean, we’re literally talking about a _single keyword. _Take any script, add the function keyword, a function name, and a couple of curly brackets, and you’ve got a function. This really shouldn’t be a criteria when you’re looking at a contest entry… or even when you’re looking at something a colleague offered to you.
Or should it?
[boilerplate greatdebate]
Today’s Great Debate is a bonus, offered from former team member June Blender. Take it away, June!
Like several of the excellent debates in our Great Debate series, this debate issue arose during in Scripting Games 2013 when different judges used different selection criteria to evaluate entries.
Some judges, like me, wanted to see evidence that the scripter had studied all features of the newest version of the Windows PowerShell language and selected the best approach for their solution. Other judges wanted the solutions to work on as many computers as possible.
Outside of the Scripting Games, this issue is very practical and very important. If you"™re writing a script to work on particular computers in your enterprise, you know which versions of Windows PowerShell are installed and which features you can use. But when you write a shared script or functions for a module, your scripts/functions can run in any environment.
What"™s the version best practice?
I think we can all agree that a #Requires statement should appear in any shared script.
This should be interesting.
During The Scripting Games, I observed (and in some cases made) a great many comments that I’m lumping under the name “Purity Laws.”
You shouldn’t use a command-line utility like Robocopy in a PowerShell script.
- You shouldn’t use .NET classes in a PowerShell script.
- You should map a drive using New-PSDrive, not net use.
And so on. You see where I’m going: there are folks out there who feel as if the only thing that goes into a PowerShell script is Pure PowerShell. Which is odd, because it isn’t an approach the product team actually gave much value. They spent extra time making sure the shell could use .NET, and could run external utilities - why not use them, if they work and get the job done?
A counterargument involves maintenance and readability. External commands, for example, are harder to read, may not be well-documented, and don’t work consistently with the rest of PowerShell. .NET classes are hard to discover, and force you into a very “programmer-y” approach. Some environments might not want the extra overhead - even if it means giving up functionality.
So where do you come down on this debate? I’d really love some _detailed recommendations. _What’s right for your environment, and most importantly _why? _Are there any facts or situations that would sway you to the other side of the argument?
Go.
[boilerplate greatdebate]
