{"id":13461,"date":"2011-07-01T00:01:00","date_gmt":"2011-07-01T00:01:00","guid":{"rendered":"https:\/\/blogs.technet.microsoft.com\/heyscriptingguy\/2011\/07\/01\/naming-and-designing-advanced-powershell-functions\/"},"modified":"2011-07-01T00:01:00","modified_gmt":"2011-07-01T00:01:00","slug":"naming-and-designing-advanced-powershell-functions","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/scripting\/naming-and-designing-advanced-powershell-functions\/","title":{"rendered":"Naming and Designing Advanced PowerShell Functions"},"content":{"rendered":"


Summary<\/b>: Microsoft Scripting Guy Ed Wilson discusses naming and designing advanced Windows PowerShell functions in relation to his Local User Management Module.\nMicrosoft Scripting Guy Ed Wilson here. The cool thing about today is that it is Canada Day<\/a>. This means that my boss back in Redmond is off today. Of course, Monday is July 4th<\/sup><\/a>, and the Scripting Wife and I will be off celebrating. The cool thing about this dual country celebration is that we effectively get a four-day weekend. In fact, the Scripting Wife and I will be heading to Canada in October for three weeks. We will be in Ottawa, Quebec City, and in Montreal. I am working with my friend, Georges Maheu, on a new workshop, and we will be conducting Train the Trainer sessions up there. I am also hoping to meet up with at least one users group while I am north of the border. It will be an awful lot of fun, and if we are lucky, maybe we can score some poutine<\/a> while we are in Quebec City.\nIn yesterday’s post<\/a>, I talked a little bit about writing the Local User Management Module<\/a> and how I used parameter sets to simplify some of the code syntax. On the page for the Local User Management Module in the Scripting Guys Script Repository, a couple of questions have already appeared. The first one is, “Does it work on domain users and groups?” To be honest I did not test that scenario. I do know that the WinNT provider (which I used in the module) can be used to make some modifications to Active Directory. I have always advocated that newbies stay away from that approach as it leads to serious confusion early on. After scripters have learned the difference between using the WinNT provider and the LDAP provider, there are some nice shortcuts that can be used with the WinNT provider that will simplify a few scenarios. The reason I called my module the Local User Management Module was specifically because I wanted to fill the hole that currently exists with local user accounts. For domain accounts, you should use either the Quest AD cmdlets or the Microsoft Windows 2008 R2 AD cmdlets (there is also the 2008 Gateway).\nThis having been said, there are some additional scenarios I will examine for the Local User Management Module, and I can guarantee there will be a V2 release soon. There may even be a V3. Send email to me at scripter@microsoft.com<\/a>, and let me know what you would like to see. In response to a comment on yesterday’s Hey, Scripting Guy! Blog post<\/a>, I am thinking about incorporating security into the mixture.\nThere was an additional question<\/a> about why I created a function named Set-LocalUser<\/strong> instead of creating two functions–one called Enable-LocalUser<\/strong> and another called Disable-LocalUser<\/strong>. The first part of the discussion needs to take a look at the verb. In fact, the entire discussion revolves around the verb. The first thing I do when deciding a verb name is to use the Get-Verb<\/strong> cmdlet. When I use that cmdlet, I am able to see which verbs are allowed. The listing appears here, along with the command I used to obtain the results.<\/p>\n

PS C:Usersed.WOODGROVE> get-verb | sort verb<\/p>\n

Verb                 Group<\/p>\n

——                 ——-<\/p>\n

Add                  Common<\/p>\n

Approve           Lifecycle<\/p>\n

Assert              Lifecycle<\/p>\n

Backup             Data<\/p>\n

Block                Security<\/p>\n

Checkpoint       Data<\/p>\n

Clear                Common<\/p>\n

Close                Common<\/p>\n

Compare          Data<\/p>\n

Complete         Lifecycle<\/p>\n

Compress        Data<\/p>\n

Confirm            Lifecycle<\/p>\n

Connect           Communications<\/p>\n

Convert            Data<\/p>\n

ConvertFrom    Data<\/p>\n

ConvertTo        Data<\/p>\n

Copy                Common<\/p>\n

Debug              Diagnostic<\/p>\n

Deny                Lifecycle<\/p>\n

Disable             Lifecycle<\/p>\n

Disconnect       Communications<\/p>\n

Dismount         Data<\/p>\n

Edit                  Data<\/p>\n

Enable              Lifecycle<\/p>\n

Enter                Common<\/p>\n

Exit                  Common<\/p>\n

Expand             Data<\/p>\n

Export              Data<\/p>\n

Find                  Common<\/p>\n

Format             Common<\/p>\n

Get                   Common<\/p>\n

Grant                Security<\/p>\n

Group               Data<\/p>\n

Hide                 Common<\/p>\n

Import              Data<\/p>\n

Initialize           Data<\/p>\n

Install               Lifecycle<\/p>\n

Invoke               Lifecycle<\/p>\n

Join                  Common<\/p>\n

Limit                Data<\/p>\n

Lock                 Common<\/p>\n

Measure           Diagnostic<\/p>\n

Merge              Data<\/p>\n

Mount              Data<\/p>\n

Move                Common<\/p>\n

New                 Common<\/p>\n

Open                Common<\/p>\n

Out                   Data<\/p>\n

Ping                  Diagnostic<\/p>\n

Pop                  Common<\/p>\n

Protect              Security<\/p>\n

Publish             Data<\/p>\n

Push                 Common<\/p>\n

Read                Communications<\/p>\n

Receive            Communications<\/p>\n

Redo                Common<\/p>\n

Register           Lifecycle<\/p>\n

Remove           Common<\/p>\n

Rename           Common<\/p>\n

Repair              Diagnostic<\/p>\n

Request           Lifecycle<\/p>\n

Reset               Common<\/p>\n

Resolve            Diagnostic<\/p>\n

Restart              Lifecycle<\/p>\n

Restore            Data<\/p>\n

Resume           Lifecycle<\/p>\n

Revoke             Security<\/p>\n

Save                 Data<\/p>\n

Search             Common<\/p>\n

Select              Common<\/p>\n

Send                Communications<\/p>\n

Set                   Common<\/p>\n

Show                Common<\/p>\n

Skip                  Common<\/p>\n

Split                 Common<\/p>\n

Start                 Lifecycle<\/p>\n

Step                 Common<\/p>\n

Stop                 Lifecycle<\/p>\n

Submit             Lifecycle<\/p>\n

Suspend          Lifecycle<\/p>\n

Switch              Common<\/p>\n

Sync                 Data<\/p>\n

Test                 Diagnostic<\/p>\n

Trace                Diagnostic<\/p>\n

Unblock            Security<\/p>\n

Undo                Common<\/p>\n

Uninstall           Lifecycle<\/p>\n

Unlock              Common<\/p>\n

Unprotect        Security<\/p>\n

Unpublish         Data<\/p>\n

Unregister        Lifecycle<\/p>\n

Update               Data<\/p>\n

Use                  Other<\/p>\n

Wait                 Lifecycle<\/p>\n

Watch              Common<\/p>\n

Write                Communications\n \nAs you can see from the above list, there are Enable<\/strong> and Disable<\/strong> verbs, so why did I not use them if they are available? For one thing, they are listed as lifecycle verbs.\nSee MSDN for a great article that talks about some of the nuances between the different verbs<\/a>.\nIf Enable<\/strong> and Disable<\/strong> are lifecycle verbs, I need to see the other lifecycle verbs so that I can get a feel for how they behave (unfortunately, there is no help for the Get-Verb<\/strong> cmdlet to describe what the categories actually mean). Here is the command I used to get all the lifecycle verbs; the output from the commands also appears.<\/p>\n

PS C:Usersed.WOODGROVE> get-verb | where { $_.group -eq ‘lifecycle’}<\/p>\n

Verb                 Group<\/p>\n

——                 ——-<\/p>\n

Approve           Lifecycle<\/p>\n

Assert              Lifecycle<\/p>\n

Complete         Lifecycle<\/p>\n

Confirm            Lifecycle<\/p>\n

Deny                Lifecycle<\/p>\n

Disable             Lifecycle<\/p>\n

Enable              Lifecycle<\/p>\n

Install               Lifecycle<\/p>\n

Invoke                Lifecycle<\/p>\n

Register           Lifecycle<\/p>\n

Request           Lifecycle<\/p>\n

Restart              Lifecycle<\/p>\n

Resume           Lifecycle<\/p>\n

Start                 Lifecycle<\/p>\n

Stop                 Lifecycle<\/p>\n

Submit             Lifecycle<\/p>\n

Suspend          Lifecycle<\/p>\n

Uninstall           Lifecycle<\/p>\n

Unregister        Lifecycle<\/p>\n

Wait                 Lifecycle\n \nThe output from the lifecycle verbs did not help too much. The next thing I did was see how the Enable<\/strong> and Disable<\/strong> verbs are used in Windows PowerShell. To do that, I used the Get-Command<\/strong> cmdlet with the verb<\/i> parameter. Because the verb<\/i> parameter will accept an array, I can obtain the output I seek in a single command. The command and returned information appear here.<\/p>\n

PS C:Usersed.WOODGROVE> Get-Command -Verb enable, disable | select name<\/p>\n

Name<\/p>\n

———————<\/p>\n

Disable-ComputerRestore<\/p>\n

Disable-PSBreakpoint<\/p>\n

Disable-PSRemoting<\/p>\n

Disable-PSSessionConfiguration<\/p>\n

Disable-WSManCredSSP<\/p>\n

Enable-ComputerRestore<\/p>\n

Enable-PSBreakpoint<\/p>\n

Enable-PSRemoting<\/p>\n

Enable-PSSessionConfiguration<\/p>\n

Enable-WSManCredSSP\nAs I looked over the listing of cmdlets, I saw things like Enable<\/strong>\/Disable<\/strong> PSRemoting<\/strong> and Enable<\/strong>\/Disable<\/strong> ComputerRestore<\/strong>. I then decided to look at cmdlets with a noun of Service<\/strong>. Here is the command and results.<\/p>\n

PS C:Usersed.WOODGROVE> Get-Command -Noun service | select name<\/p>\n

Name<\/p>\n

————-<\/p>\n

Get-Service<\/p>\n

New-Service<\/p>\n

Restart-Service<\/p>\n

Resume-Service<\/p>\n

Set-Service<\/p>\n

Start-Service<\/p>\n

Stop-Service<\/p>\n

Suspend-Service\nIn the above listing, you will see that there is no Enable<\/strong>\/Disable<\/strong> service cmdets. They do have Set-Service<\/strong>. To disable or enable a service, I use Set-Service<\/strong>. This is because I am not actually disabling the service, but am instead changing a property of the service to Disabled<\/em>. I will admit it causes confusion, and I have known a lot of people who resort to using WMI to Enable<\/strong>\/Disable<\/strong> a service because they do not realize they can do it via the Set-Service<\/strong> cmdlet.\nThe next thing to look at is what is my Set-LocalUser<\/strong> cmdlet actually doing? When I disable the user, it does not actually disable the user; rather, it sets a userflag<\/em> property to the ADS_USER_FLAG_ENUM<\/strong> value of 2. It also sets the description<\/em> property of the user at the same time. To enable a user, the Set-LocalUser<\/strong> function performs three actions: it sets the password, the userflags, and the description. Because of this, I decided that it was more than a simple Enable<\/strong>\/Disable<\/strong> action that was being performed.\nThe Set-LocalGroup<\/strong> function was a bit trickier. Here, I am simply calling either the add<\/i> or the remove<\/i> method, and from our listing of approved verbs, Add<\/strong> and Remove <\/strong>are on the list. But what should I call the function? Add-Group<\/strong>, Remove-Group<\/strong>? Of course not! If I am creating a group or deleting a group, I use Add-Group<\/strong>\/Remove-Group<\/strong> (or more specifically in my case Add-LocalGroup<\/strong> and Remove-LocalGroup<\/strong>). The next thing I thought about was using the names Add-ToLocalGroup<\/strong> and Remove-FromLocalGroup<\/strong>. In the end, it seemed that Set-LocalGroup<\/strong> was the right decision because I am actually setting the group membership (regardless of the actual methods in use in the code). The other advantage is that I avoided having to create two functions; I was able to use only one function to perform both the add<\/em> and the remove<\/em> methods to the group membership.\nNow, let’s go back and look at the Set-LocalUser<\/strong>. I could have used Enable<\/strong> and Disable<\/strong>, and I actually did spend a lot of time thinking about the name. As you can see from the above discussion, one problem with Set-Service<\/strong> is that people do not think about using it to enable or to disable a service. According to the verbs, I guess I can use either Enable<\/strong>\/Disable<\/strong> or Set<\/strong>, and still be following the guidelines. There is one other guideline that I probably violated and that is the principle of least shock, which is also an issue with Set-Service<\/strong>. If everyone who uses the software expects something to be called Enable-LocalUser<\/strong>, discoverability becomes an issue. Again, the overriding factor for me was wanting to incorporate the functionality, follow good Windows PowerShell naming conventions, and get the thing written in time for yesterday’s Hey, Scripting Guy! Blog post to be edited and published. You see, when it comes right down to it, to ship is to choose.\nWell, this concludes another edition of the Hey, Scripting Guy! Blog. Join me tomorrow when I will show you how to use the Local User Management Module .\nI invite you to follow me on Twitter<\/a> and Facebook<\/a>. If you have any questions, send email to me at scripter@microsoft.com<\/a>, or post your questions on the Official Scripting Guys Forum<\/a>. See you tomorrow. Until then, peace.\nEd Wilson, Microsoft Scripting Guy<\/b>\n<\/b> <\/p>\n","protected":false},"excerpt":{"rendered":"

Summary: Microsoft Scripting Guy Ed Wilson discusses naming and designing advanced Windows PowerShell functions in relation to his Local User Management Module. Microsoft Scripting Guy Ed Wilson here. The cool thing about today is that it is Canada Day. This means that my boss back in Redmond is off today. Of course, Monday is July […]<\/p>\n","protected":false},"author":595,"featured_media":87096,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[69,3,4,45,77],"class_list":["post-13461","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-scripting","tag-functions","tag-scripting-guy","tag-scripting-techniques","tag-windows-powershell","tag-writing"],"acf":[],"blog_post_summary":"

Summary: Microsoft Scripting Guy Ed Wilson discusses naming and designing advanced Windows PowerShell functions in relation to his Local User Management Module. Microsoft Scripting Guy Ed Wilson here. The cool thing about today is that it is Canada Day. This means that my boss back in Redmond is off today. Of course, Monday is July […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts\/13461","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/users\/595"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/comments?post=13461"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts\/13461\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/media\/87096"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/media?parent=13461"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/categories?post=13461"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/tags?post=13461"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}