Articles from April 2016 on PowerShell.org - Welcome Automaters!

Documenting your PowerShell API–solved!

Fri, 29 Apr 2016 22:01:52 +0000

Long has it been known how to easily document your PowerShell source code simply by embedding properly formatted documentation comments right along side your code, making maintenance relatively painless…

But if you advanced to writing your PowerShell cmdlets in C#, you have largely been on your own, either hand-crafting MAML files or using targeted MAML editors far removed from your source code. But not anymore. With the advent of Chris Lambrou’s open-source XmlDoc2CmdletDoc, the world has been righted upon its axis once more: it allows instrumenting your C# source with doc-comments just like any other C# source:

All of the above provides fuel for Get-Help, i.e. providing help one cmdlet at a time. But we are a civilized people; we also need a web-based version of our full custom PowerShell API. That is, a hierarchical and indexed set of Get-Help pages for all the cmdlets in our module. For this task, my own open-source effort, DocTreeGenerator, nicely fills the gap, requiring very little beyond the doc-comments described above to do the complete job.
I have written extensively on using both XmlDoc2CmdletDoc and DocTreeGenerator, and just this week, released a one-page wallchart that shows how all the pieces work together:

Here’s the link to get you started on this fun journey:
Unified Approach to Generating Documentation for PowerShell Cmdlets

Scripting Games May 2016 AD Puzzle

Wed, 27 Apr 2016 02:32:52 +0000

I love working in AD (Active Directory) with PowerShell. I find that I have had to really dig in to learn some of the syntax nuances that you need to understand to really mine data and change configurations within Active Directory. This puzzle reflects the kind of situation that people have to deal with in PowerShell everyday. I am interested to see what kinds of approaches each of you will take, this is a real chance to learn more of the diversity of methods that can be used in Active Directory with PowerShell.
This month Bartek Bielawski has submitted two puzzles, I am going to post the beginner to medium one first and then the advanced one next month. This is going to be a real learning opportunity. Keep the puzzles coming in, Mike F. Robbinson has submitted one recently too, so you can look forward to that in a couple of months.
Here we go:
During an internal IT audit of rights on your file server it was discovered that certain group had rights to the share used by finance and HR with sensitive data and the main question is: who was able to access these files because of that. When it happens you are attending a conference (surprise, surprise) and can’t really do anything remotely. That doesn’t stop your boss from calling you and asking for help. All she wants is a list of all users that are members of that group. The problem is that this group suffers from snow-ball effect and has multiple nested groups, that contain nested groups, that contain nested…
You respond with “use Get-ADGroupMember -Recursive” but your boss complains, that when she tried to use it, she just got some red text on her screen with information, that common delete is not recognized. You roll your eyes and eventually decide to write a short script and send it over e-mail. Luckily, you have sandbox domain controller running on your laptop, so testing your code is not that difficult. As you are in the middle of an interesting talk, you try to make it as simple and minimalistic as possible. You also decide not to try any other tools that require something to be installed on a computer running the code. One call from the boss is enough.
Design goals:

Solution has to be quick. Don’t waste time on producing nice, informative error messages.
Your boss won’t read them anyway
Try to use a solution that requires least testing possible
Writing simple function could be nice, but if you manage to get it done in two lines, or even one – just do it
You are limited to build-in functionality only.

]]>

Verified Effective Exam Results

Fri, 22 Apr 2016 16:14:26 +0000

We’ve uploaded the results of the Verified Effective: PowerShell Toolmaker exam, which was administered at the recent PowerShell + DevOps Global Summit 2016. Note that this exam has, for a couple of years now, been available only as an on-site, in-person, proctored experience - we do not offer online delivery.
We had our best pass rate ever - about 20%. That said, nobody hit 100%. I had actually done a pre-con, full-day session on the very topic being tested - writing advanced functions - and had more than a few folks tell me that the session wasn’t as “advanced” as they wanted. Notwithstanding, 80% of the people who took the test didn’t pass (and I wasn’t the one grading the tests, either, so it’s not just spite!). Unfortunately, a lot of us think we’re “advanced,” but in fact are missing a lot of details. In some cases, having reviewed the graded tests, folks are missing some of the basics.
If you took the test, head over toVerifiedEffective.org and enter your candidate ID to see if you passed. I want to stress that I personally don’t have access to the graded tests with names attached - I only have anonymized copies.
We’re not going to offer the exam again at Summit 2017. We’re considering making some schedule changes that won’t accommodate the time and space and personnel needed to administer the exam and - to be frank - I think education would benefit a lot of people more than a test. Whether we offer the test again in future years hasn’t yet been decided, although I’ll share our general feelings at the end of this article.
In fact, with that “education” in mind, I’m going to break a rule. I’m going to post the entire exam packet, exactly as it was given to the attendees who took the exam. I did something similar after PowerShell Summit Europe 2015, but this is the exact exam packet. Go ahead - give yourself an hour to finish the test, and then check back here. I’ll wait.
Exam

All done? Now I’m going to break another rule and go through the exam. I’m going to point out a bunch of stuff that people got wrong, although _just because you did or did not get these things wrong does not mean you did or did not pass, _if you were one of the folks who took this at Summit. This is an amalgamation of comments. So do not drop into comments all angry that you “should have passed” because you think you did perfectly based on my comments in this article. If you didn’t pass, you didn’t pass for at least a couple of good reasons, and no, I’m not going to ask the scoring panel to go over your exam with you personally. We don’t have the tests with names on them anymore, anyway.
So.
The first thing people ran across is the fact that the function in the exam clearly has comment-based help, but when run in the transcript no help appeared. No help. Not even the auto-generated help, _which should have been a clue. _The problem is the blank line between the end of the help block and the function keyword[NB: Dave Wyatt points out that this was fixed in v5; it’s irrelevant for the exam scoring because you were not expected to fix it anyway]. PowerShell _(in v4, at least, which is obviously what was used to create the transcript) _chokes on this and abandons all hope. _You were not expected to fix this, _because it was like this in the transcript - and your goal was to make the function look as needed to reproduce the transcript. Some (most) folks deleted the comment block. But do me a favor - paste this function into a script, omit the comment block, and see what PowerShell does when you ask for help. Is that what’s shown in the transcript? Only two left it alone, recognizing the problem for what it was. “But that’s tricky!” you might say. No, it isn’t - not if you know the details of how this technology works. The technology may be tricky, but knowing those ins and outs is what sets you apart as an expert. However, nobody failed solely because they suggested deleting the comment block - the goal of this article is to point out what was going on, not describe the ways in which people failed or passed.
Now for the parameter block, which caused more grief than almost anything else.

Param( [Parameter(ValueFromPipelineByPropetyName=$True)] [string[]]$ComputerName, [ValidateSet('Cim','Wmi')] [string]$Protocol = 'Cim' )Most everyone recognized that ValueFromPipeline needed to be added; very few struck ByPropertyName. It’s fine; it doesn’t hurt to have it there and nothing in the transcript suggested it was wrong.
There is no need to add [Parameter()] to the second parameter. However, that [ValidateSet()] really caused a lot of variation in the responses. The transcript clearly shows Dcom as one value, so Wmi is clearly wrong. While the transcript does not show any other value _being passed to the parameter, _it clearly shows Wsman as the “default” value - this is in the verbose output when the command is first run. Ergo, if Wsman is the default, then it must also be part of the validation set, not Cim. This is the kind of deductive reasoning that makes you a good debugger.
Many people correctly pointed out that [CmdletBinding()] is missing, which is required to enable the built-in -Verbose parameter. Some folks wrote entire If() block to test for -Verbose, which is not the right thing to do. [NB: Dave Wyatt points out that the -Verbose parameter would be implied by including [Parameter()], which is fine; I checked with the scoring panel and nobody was docked for not specifying [CmdletBinding()]. It’s the If() construct that was unnecessary.]
Several people insisted on adding a BEGIN{} and END{} block. These are unnecessary _to reproducing the transcript. _Advanced functions work fine without them, even in pipeline input mode.

if ($Protocol -eq 'Dcom') { $opt = New-CimSessionOption -Protocol Dcom } else { $opt = New-CimSessionOption -Protocol Wsman }Many folks made extensive changes to that section. However, _according to the transcript, _the If() block is correct. It’s the ValidateSet() that was wrong. Some folks felt that -Protocol $protocol could have removed the need for the whole If() block. That’s fine, and the opinion wasn’t counted against you, but the goal was to reproduce the transcript, not to simply simplify the code.
Now for the main chunk.

try { $session = New-CimSession -SessionOption $opt -ComputerName $Comp $os = Get-CimInstance -CimSession $session-ClassName Win32_OperatingSystem $disk = Get-CimInstance -CimSession $session -ClassName Win32_Volume-Filter "Name = 'C:\\'" $props = @{'ComputerName' = $Computername 'OSVersion' = $os.version 'SPVersion' = $os.ServicePackMajorVersion 'CDiskSize' = $disk.Capacity 'CDiskFree' = $disk.FreeSpace} New-Object -TypeName PSObject -Property $props } catch { Write-Error “Failed to connect to $comp” } `Ignoring the annoying backticks, which were there only to make this fit onto a printed sheet of paper, nearly _everyone missed the lack of -ErrorAction on **New-CimSession. **_Without that, the entire Try/Catch block doesn’t work. That’s a fairly grievous oversight.
Others added in a slew of Write-Verbose statements to duplicate what was in the transcript. Problem is, if you’d added [CmdletBinding()], most of the verbosity in the transcript came from New-CimSession and Get-CimInstance, because running the function with -Verbose “passes down” the verbose instruction to cmdlets within the function. That’s important to know as a Toolmaker. Other added -Verbose to the end of all the Get-CimInstance commands, which is clearly wrong, since those did not always produce verbose output.
Many folks, by the way, caught that Write-Error should have been **Write-Warning. **Many also added #end comments to the construct closing brackets. Unnecessary, as there was no instruction to modify the script to conform with any particular set of practices, but it didn’t count against you. Most caught the replacement of $comp with $computername in the $props hash table. Several insisted on saving the new object to a variable and then writing it with Write-Output; that’s unnecessary but didn’t count against them.
A couple of folks insisted on saving the new object to a variable, and then writing that variable to the pipeline _after the end of the Catch block. _If you follow the logic, you’ll see the problems that will produce. It’s wrong. Others pointed out that the new object variable would have to be set to $null at the end of the ForEach construct. It doesn’t. Not if you’re doing it right.
Several folks unnecessarily asked for the order of the hash table to be different, to match the output of the transcript. Because an unordered hash table is used, PowerShell won’t respect the order shown in the script, and what’s in the transcript is what you actually get. Changing the order of the hash table in the code won’t necessarily have any effect on the output. Again, this is an important thing to know if you’re going to be expert-level in Toolmaking.
A few folks pointed out that Get-CimInstance would require a -Namespace. It doesn’t, because we’re querying the default namespace. Others somewhat inexplicably crossed out the -ClassName parameter, so I’m not sure how the script would be expected to work that way.
I want to emphasize that _I have not covered every single grade point from the exam - _only the major things that I noticed as I reviewed the already-graded packets. I reviewed those without people’s names attached, too, so I can’t even tell you who did what, which is as it should be.
Now, for the good news. Pass or fail, most people got the gist of the thing. Some people were probably just freaked out about taking an exam, and flubbed a few bits they might ordinarily get right. A couple of people got time-pressured, and that can cause screwups. So know that, even if you didn’t pass, _you were probably close. _And there’s a massively legitimate position that you can’t easily test this kind of skill without throwing in all kinds of off-topic stresses and complications. Fortunately, this isn’t a certification exam, you’re not going to lose your job if you didn’t pass, and you didn’t pay a dime to try (the exam was free to all attendees). And I want to emphasize that nobody got it 100% right. There were, I think, 11 errors, and you needed to find 8 of them to pass. So it was easy to fall just on one side or the other of that line.
If there’s a takeaway, it’s that _there’s always room to learn more. _If you made one of the silly mistakes, or missed -ErrorAction, it might well simply be because of the nature of this experience, not because you didn’t know better. In which case - awesome. But I’m pretty sure everyone “legitimately” missed at least one important thing, or added something unnecessary in the belief that it was required - and if you can make this a learning experience, then you’ll at least grow as a professional.
So, on to the future of this thing. This whole exam idea was started because Microsoft simply refuses to do a certification, and people wanted some kind of measuring stick for their skills. Thing is, any kind of exam (and perhaps Microsoft recognizes this?) tosses unrelated factors into the soup, and you get people failing just because of the nature of the exam. They tense up. They stress out. They overthink it. They start looking for “tricks” and second-guessing themselves. Whatever it is, the yardstick itself becomes a problem, perhaps more of a problem than what it was trying to solve. So for now, at least, we’re not going to pursue this any further. I do recognize the need to measure yourself against a standard, and I recognize the value that can have in the workplace. But we’re seeing that the testing process (and we’ve tried this in four different processes in an attempt to combat this) is artificial, and introduces too many extraneous variables to be, I think, a super-accurate standard. So for now, we don’t feel our best value as an organization is to pursue this at the moment. Instead, we’re going to focus on education.
Perhaps in some months the new Scripting Games can take on the role of giving you a task like this one - one with a more defined “answer.” A way for you to test yourself against a standard, just for your own satisfaction and edification. As always, we’re open to suggestions (especially suggestions that come with an offer to _actually implement the suggestion, _since we’re not gifted with any more free time than you are) on how we can help the community better serve itself and meet its needs.
In the meantime, thanks for your support.

]]>

Keeping it simple – Line breaks in PowerShell

Wed, 20 Apr 2016 23:18:07 +0000

Trying to get your code to look good when reading it later can be tricky
For line breaks in function scripts, there are two out-of-the-box options:
First, you can break a lineafter the pipe key, which is an elegant and easy-to-read approach.
Second, you can arbitrarily break a line with aback tick mark, which you will find left of the number 1 on a standard US keyboard.
**It looks like this: ** But did you know that the back tick is a hack? The back tick means, “literally interpret the next character,” or also said, escape the following character.”
For example, you might want to literally reference a quotation mark “ in a path name, but because it’s inside “” for strings, you need to literally interpret it: “”PATH”” – it’s hard to see, but squint.
But here’s another takeaway: if you use the back tick to create a line break, make sure there’s no space after it; otherwise, the space – not the carriage return – will be the escaped, literal character!
So here’s are some examples of what works and what doesn’t:
First, no line breaks - works like a charm, but if we add a few more pipes and parameters this could get ugly.

Next we have an example with a line break after the pipe, also functioning normally

Here we see the line break before the pipe, and the script fails

In this sample we use the tick immediately followed by a return. If we wanted to we could insert these ticks numerous times, before each parameter, for example

Finally we see the effect of using the back tick AND A SPACE before the carriage return - this one is tricky to find when troubleshooting, so don’t let it happen to you!

A special thanks to Sarah Wischmeyer for the introductory comments on this one!
Keep your scripts snappy!

]]>

Help Get the Word Out on the 'GetGoing' Program & Scholarship

Wed, 20 Apr 2016 16:00:44 +0000

A couple of weeks ago, DevOps Collective (PowerShell.org’s parent non-profit organization)announced the availability of the ‘GetGoing’ IT Ops Education Program and Scholarship.
For those of you who may not have yet heard, DevOps Collective and Pluralsight have partnered together to create a modern ’turnkey’ curriculum that brings together mapped courses, recommended hands-on experiences, and live mentoring to prepare people for the real-world of IT Operations. With this initiative, they’ve offered up to full-ride scholarships for 2016. Applications for the scholarship have opened, and applications will be taken in until May 15th.
Now that the way has been paved, it’s our turn as members of the community to get the word out; and doing so might be easier than you think!
Contact Your Local School Districts
I recently reached out to my hometown public school district, and was immediately met with enthusiasm from the local superintendent and their Science, Guidance, and Counseling departments. It only takes a quick email with some bullet points on the program to get the conversation initiated. I’ve included the text of my initial correspondence for you to use as a guide to help you on your way.
Contacting your school district iseasy . A quick search online for your district can get your to their website with contact info, often including the email addresses for the district superintendent and other office officials that can help! Send them acopy of the brochure to help them get informed of the initiative.
Use Your Social Media Skills
Get the conversation going on social media! Talk to your followers; speak out to local educational organizations; and make them aware of this awesome new program!
Inform Your User Groups
Get your user groups in on the action. Enlist the greater community to get the word out faster! Together we can canvas an even larger area and get more people interested!
Get Involved
Offer to become a mentor. We all know that the best way to learn is from real world experiences. We, as a community, have this vast repository of practical knowledge that no book can effectively provide. We, as a collective resource, can help to bring a new generation of administrators, engineers, and architects into this world already prepared to take on DevOps, Agile IT, and more!
If you need a hand getting started, feel free to contact me atwebmaster at powershell.org. Now let’s#GetGoing ourselves, and make this happen!
Here’s my initial contact email that you can use to fit your own story:
Greetings [Contact Name],

I hope this email finds you well.

*My name is [Your Name Here].  I'm a native to [City], IT Consultant, and an industry/community leader in Cloud and Datacenter Management.  I teach PowerShell for free to people in the community that have an interest in the technology at user groups in [location[s]].*
*I also do volunteer work for the DevOps Collective; a 501(c)(3) organization that is dedicated to creating conversations, improving connections between practitioners, and further develop the DevOps state of the art.*
*Recently, DevOps Collective announced the new “GetGoing” IT Ops Education Program & Scholarship.  More on the program can be [researched here](https://devopscollective.org/2016/04/04/announcing-the-getgoing-it-ops-education-program-scholarship/), but I thought I'd offer some of the bullet points on the major educational objectives that form the basis of the program:*
-
*Core understanding of business IT environments, including the various components that commonly form the business technology infrastructure.*
-
*Basic networking essentials, including client configuration and troubleshooting.*
-
*Essentials of business technology security.*
-
*Essentials for technology troubleshooting, including methodologies and patterns.*
-
*Essentials of virtualization technologies.*
-
*Help desk essential skills, including Microsoft Office basics, customer interaction, ticketing systems, and process-following.*
-
*Desktop support essentials.*
-
*Server support essentials.*
-
*Windows client operating system fundamentals, including client and server administration fundamentals.*
-
*Windows PowerShell fundamentals, including the use of PowerShell for core help desk tasks.*
-
*Fundamentals of Microsoft-based databases, collaboration, and messaging technologies.*
*Finally, DevOps Collective has partnered with Pluralsight to offer two full-ride scholarships.  One is a general availability scholarship, and the second is a diversity scholarship being offered to groups that underrepresented in IT in the United States.  The scholarship has a total value of approximately $11,000 dollars and includes:*
-
*Full access to a Pluralsight turnkey curriculum, giving you all the education the model curriculum specifies.*
-
*A paid mentor, who will check-in weekly with each student.*
-
*Paid-for hands-on experiences, including Azure time, predesigned hands-on labs, and even a build-it-yourself kit PC that students get to keep.*
-
*Practice tests, knowledge checks, and other supplemental materials.*
-
*Paid-for certification exams – students only pay if they need to re-take a test.*
*As a leader in the IT community with strong ties the

[city] , I feel that this is an important conversation that we need to have for the children of the city. I grew up [your story]. I have enjoyed much success in my career in Information Technology, and I would love to see today’s [school district] students empowered to become tomorrow’s technology successes.*

*Please feel free to contact me if you have any questions.*
*Best Regards,*

]]>

A study in Powershell scripting – A beginners guide Part 3

Mon, 18 Apr 2016 12:28:02 +0000

Here is the long awaited post of my third installment of where I revisit my script and provide some explanation as to why I did the things I did in regards to synchronizing Active directory groups.
As always feedback is welcome.
Link is here

The Unicode PowerShell module

Fri, 15 Apr 2016 11:25:19 +0000

After authoring last month scripting games puzzle, which involved some scripting around the Unicode standard, I decided to have some fun and write aPowerShell module which interacts directly with the onlineUnicode Database (UCD) to retrieve the main properties of characters.

Using this module you will be able to retrieve the following information for a single char or for every char in a given string:

Glyph name
General category
Unicode script
Unicode block
Unicode version (or age)
Decimal value
Hex value
Here’s a few sample outputs you can get from using the functions in the UnicodeInfo module:

Get-Unicodeinfo '$' Glyph : $ Decimal value : 36 Hexadecimal value : U+0024 General Category : CurrencySymbol Unicode name : DOLLAR SIGN Unicode script : Common Unicode block : BasicLatin Unicode version : 1.1Get-Unicodeinfo ‘Powershell!’ | Format-Table Glyph Decimal value Hexadecimal value General Category Unicode name Unicode script Unicode block Unicode version

P 80 U+0050 UppercaseLetter LATIN CAPITAL LETTER P Latin BasicLatin 1.1 o 111 U+006F LowercaseLetter LATIN SMALL LETTER O Latin BasicLatin 1.1 w 119 U+0077 LowercaseLetter LATIN SMALL LETTER W Latin BasicLatin 1.1 e 101 U+0065 LowercaseLetter LATIN SMALL LETTER E Latin BasicLatin 1.1 r 114 U+0072 LowercaseLetter LATIN SMALL LETTER R Latin BasicLatin 1.1 s 115 U+0073 LowercaseLetter LATIN SMALL LETTER S Latin BasicLatin 1.1 h 104 U+0068 LowercaseLetter LATIN SMALL LETTER H Latin BasicLatin 1.1 e 101 U+0065 LowercaseLetter LATIN SMALL LETTER E Latin BasicLatin 1.1 l 108 U+006C LowercaseLetter LATIN SMALL LETTER L Latin BasicLatin 1.1 l 108 U+006C LowercaseLetter LATIN SMALL LETTER L Latin BasicLatin 1.1 ! 33 U+0021 OtherPunctuation EXCLAMATION MARK Common BasicLatin 1.1`160..170 | % { Get-Unicodeinfo ([char]$_) } | Where ‘General Category’ -eq “CurrencySymbol” | Format-Table Glyph Decimal value Hexadecimal value General Category Unicode name Unicode script Unicode block Unicode version

¢ 162 U+00A2 CurrencySymbol CENT SIGN Common Latin-1Supplement 1.1 £ 163 U+00A3 CurrencySymbol POUND SIGN Common Latin-1Supplement 1.1 ¤ 164 U+00A4 CurrencySymbol CURRENCY SIGN Common Latin-1Supplement 1.1 ¥ 165 U+00A5 CurrencySymbol YEN SIGN Common Latin-1Supplement 1.1 `Before you dive into the code, head over to the blog post I wrote describing each and every one of these properties, how some of them are accessible directly from the .NET framework, and how other less known but still relevant can be extracted from the UCD and integrated to the resulting object:
http://www.happysysadm.com/2016/04/working-with-unicode-scripts-blocks-and.html
The UnicodeInfo module is available on Github:
https://github.com/happysysadm/UnicodeInfo
The module is for sure ‘Work-In-Progress’ so if you find yourself willing to collaborate, you are very welcome to do so!

]]>

PowerShell + DevOps Global Summit Videos Online

Wed, 13 Apr 2016 22:04:24 +0000

The session recordings are now online! We did miss a few of the videos. The few 2-hour sessions scheduled in Room 406 were not recorded (and weren’t planned to be; we only have two sets of recording equipment, although for 2017 we’re adding a third set). And, we had a couple that had video problems on-site and weren’t recordable. We hope you’ll appreciate that our priority on-site is to provide a great experience for the people who were there, and stopping everything to make sure we get a recording isn’t always practical. As always, recordings are on a best-effort basis. As far as we know, we missed one of Matt Graeber’s sessions, Lee Holmes’ session, and the Microsoft general session from Kenneth Hansen and Angel Cavelo.
A new experiment this year should come online by July 2016. Pluralsight showed up with two film crews, and captured live HD video, and audio right from the speakers’ mic, in rooms 404 and 405, which were our main session rooms. Those recordings, which will combine the live video with our screen captures, will be available in the Pluralsight library for all Pluralsight subscribers. Registered attendees of the event will receive free access to those as well, by means of a “slice” of the Pluralsight library.
Note that last-minute registration transferees will not be automatically included in that, as we’ll be sending the library information to the originally registered person. In addition, for attendees who did not provide complete contact information (like, if someone else registered you), the notification will go to the contact information we do have. We don’t have the ability to update that list at this point, sorry.

2016-March Scripting Games Wrap-Up

Sat, 02 Apr 2016 15:04:22 +0000

Carlo really put a brain-twister out for ourMarch 2016 Puzzle. Also, as a note, we’re eagerly awaiting submissions of next month’s puzzle, so don’t delay in handing that in.Here’s how you can contribute to the community’s favorite scripting game.