{"id":74209,"date":"2015-02-03T00:01:00","date_gmt":"2015-02-03T00:01:00","guid":{"rendered":"https:\/\/blogs.technet.microsoft.com\/heyscriptingguy\/2015\/02\/03\/registry-cmdlets-first-steps-with-cdxml\/"},"modified":"2019-02-18T10:30:48","modified_gmt":"2019-02-18T17:30:48","slug":"registry-cmdlets-first-steps-with-cdxml","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/scripting\/registry-cmdlets-first-steps-with-cdxml\/","title":{"rendered":"Registry Cmdlets: First Steps with CDXML"},"content":{"rendered":"

Summary<\/b>: Richard Siddaway shows how to start creating CDXML cmdlets.<\/span>\nHonorary Scripting Guy, Richard Siddaway, here today filling in for my good friend, The Scripting Guy. This is the second post in a series. Yesterday, in Registry Cmdlets: Working with the Registry<\/a>, I explained that there aren’t any cmdlets for working directly with the registry. I showed some examples of using cmdlets that I’ve created to access the registry. The cmdlets are created from the WMI registry class, StdRegProv<\/b>, by using CDXML.\nIn this post, I’ll show you how to get started with CDXML. Before that, though, I’d better explain CDXML…\nCmdlet definition XML (CDXML) is a way to create a Windows PowerShell module from a WMI class by using the cmdlets-over-objects technology that was introduced in Windows PowerShell 3.0. As usual, it’s always easier to show you an example:<\/p>\n

<?xml version=”1.0″ encoding=”utf-8″?><\/p>\n

<PowerShellMetadata xmlns=”http:\/\/schemas.microsoft.com\/cmdlets-over-objects\/2009\/11″><\/p>\n

 <Class ClassName=”ROOTcimv2Win32_BIOS”><\/p>\n

  <Version>1.0<\/Version><\/p>\n

  <DefaultNoun>Bios<\/DefaultNoun>\n <\/p>\n

  <InstanceCmdlets><\/p>\n

   <GetCmdletParameters DefaultCmdletParameterSet=”DefaultSet” ><\/p>\n

      <\/p>\n

   <\/GetCmdletParameters><\/p>\n

  <\/InstanceCmdlets><\/p>\n

 <\/Class><\/p>\n

 <\/PowerShellMetadata>\nThe first two lines in the previous command are header information, and they have to be present in all CDXML files. You also need to state the WMI class you want to use:<\/p>\n

<Class ClassName=”ROOTcimv2Win32_BIOS”>\nThe namespace and class have to be supplied. This is equivalent to:<\/p>\n

Get-CimInstance -Namespace root\/CIMV2 -ClassName Win32_BIOS\nYou can only use a single WMI class in a CDXML module. If you need to access several WMI classes in your module, create a CDXML file per class, and use a module manifest to perform the load.\nThe version is arbitrary, and is up to you as to how it is changed as you change the module. Here is an example:<\/p>\n

<Version>1.0<\/Version>\nWindows PowerShell cmdlets have a noun-verb naming convention. CDXML allows you to set a default noun:<\/p>\n

<DefaultNoun>Bios<\/DefaultNoun>\nIf you don’t supply a noun for the name of any cmdlet in your module, it will use the default noun.\nThe following four lines define the standard Get<\/b> cmdlet in the module:<\/p>\n

<InstanceCmdlets><\/p>\n

   <GetCmdletParameters DefaultCmdletParameterSet=”DefaultSet” ><\/p>\n

   <\/GetCmdletParameters><\/p>\n

<\/InstanceCmdlets>\nThe remaining XML closes the tags.\nSave the XML with a .cdxml extension. I’ve used Bios.cdxml. You treat the CDXML file as a Windows PowerShell module. It’s most closely analogous to a .psm1 file. Create a folder on your module path with the same name as your module and save the file in that folder. The module will be automatically loaded in the same way as any other Windows PowerShell module when you start a Windows PowerShell session.\nIf you are working on the module in a series of stages, save it in a working folder that’s not on your module path. You can then load the module directly:<\/p>\n

Import-Module .bios.cdxml\nIf you are testing and debugging, you may need to load the module back into your Windows PowerShell session. You can ensure that you get the latest version of the module by using the –Force<\/b> parameter:<\/p>\n

Import-Module .bios.cdxml –Force<\/p>\n

£> Get-Module -Name Bios | Format-Table -AutoSize<\/p>\n

ModuleType Version Name ExportedCommands<\/p>\n

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

Cim    1.0   bios Get-Bios\nThe module contains a single cmdlet: Get-Bios<\/b>. The module type shows as CIM. If you use a module manifest, the module type will change to Manifest<\/b>.\nIf you use Get-Command<\/b> on the cmdlet, for example:<\/p>\n

£> Get-Command Get-Bios -Syntax<\/p>\n

Get-Bios [-CimSession <CimSession[]>] [-ThrottleLimit <int>] [-AsJob] [<CommonParameters>]\n…you’ll see that there are some parameters that you didn’t define: –CimSession<\/b>, –ThrottleLimit<\/b>, and –AsJob<\/b>. These are always generated on a CDXML module. You get this functionality for free. You also get the standard common parameters without any effort on your part.\nYou use the cmdlet in the same manner as any other cmdlet:<\/p>\n

£> Get-Bios<\/p>\n

SMBIOSBIOSVersion : 2.04.0950<\/p>\n

Manufacturer   : American Megatrends Inc.<\/p>\n

Name       : 2.04.0950<\/p>\n

SerialNumber   : 036685734653<\/p>\n

Version      : OEMA – 1072009\nThis is the same data and format that you’d get by using the WMI class directly:<\/p>\n

£> Get-CimInstance -ClassName Win32_BIOS<\/p>\n

SMBIOSBIOSVersion : 2.04.0950<\/p>\n

Manufacturer   : American Megatrends Inc.<\/p>\n

Name       : 2.04.0950<\/p>\n

SerialNumber   : 036685734653<\/p>\n

Version      : OEMA – 1072009\nYou can use Get-Help<\/b> on the cmdlet. It will only show the basic syntax. If you want extensive help, you need to create an XML-based external Help file for the module. There is no way to provide inline, comment-based Help like you can for a Windows PowerShell module.\nNow that you’ve seen a basic CDXML module, let’s start putting together our Registry module. This code is the first step:<\/p>\n

<?xml version=”1.0″ encoding=”utf-8″?><\/p>\n

<PowerShellMetadata xmlns=”http:\/\/schemas.microsoft.com\/cmdlets-over-objects\/2009\/11″><\/p>\n

 <Class ClassName=”rootcimv2StdRegProv”><\/p>\n

  <Version>1.0.0.0<\/Version><\/p>\n

  <DefaultNoun>Registry<\/DefaultNoun>\n <\/p>\n

  <StaticCmdlets><\/p>\n

   <Cmdlet><\/p>\n

    <CmdletMetadata Verb=”Get” Noun=”RegistrySTRING” ConfirmImpact=”Low”\/><\/p>\n

    <Method MethodName=”GetSTRINGvalue”><\/p>\n

     <ReturnValue><\/p>\n

      <Type PSType=”System.UInt32″\/><\/p>\n

      <CmdletOutputMetadata><\/p>\n

      <\/CmdletOutputMetadata><\/p>\n

     <\/ReturnValue><\/p>\n

    <\/p>\n

     <Parameters><\/p>\n

      <Parameter ParameterName=”hDefKey” ><\/p>\n

       <Type PSType=”System.UInt32″ \/><\/p>\n

       <CmdletParameterMetadata PSName=”Hive”><\/p>\n

       <\/CmdletParameterMetadata><\/p>\n

      <\/Parameter><\/p>\n

      <Parameter ParameterName=”sSubKeyName” ><\/p>\n

       <Type PSType=”System.String” \/><\/p>\n

       <CmdletParameterMetadata PSName=”SubKey”><\/p>\n

       <\/CmdletParameterMetadata><\/p>\n

      <\/Parameter><\/p>\n

      <Parameter ParameterName=”sValueName” ><\/p>\n

       <Type PSType=”System.String” \/><\/p>\n

       <CmdletParameterMetadata PSName=”ValueName”><\/p>\n

       <\/CmdletParameterMetadata><\/p>\n

      <\/Parameter><\/p>\n

      <Parameter ParameterName=”sValue”><\/p>\n

       <Type PSType=”System.String” \/><\/p>\n

       <CmdletOutputMetadata \/><\/p>\n

      <\/Parameter><\/p>\n

     <\/Parameters><\/p>\n

    <\/Method><\/p>\n

   <\/Cmdlet>  <\/p>\n

  <\/StaticCmdlets><\/p>\n

  <\/Class><\/p>\n

<\/PowerShellMetadata>\nThe first few lines define the class and version, as you’ve seen previously. I used Registry<\/b> as the default noun. The next line is very important. In our Registry module, it is:<\/p>\n

<StaticCmdlets>\nThe corresponding line in the BIOS example was:<\/p>\n

<InstanceCmdlets>\nThe difference is that with the BIOS example, you are working with an instance of the object that exists. When you start your computer, the BIOS loads, and that information is available to you. You can’t create another instance of the BIOS!\nOther classes where you are dealing with instances include Win32_LogicalDisk, Win32_ComputerSystem, and Win32_OperatingSystem. These are all objects that exist on your system, and therefore, they can have instances.\nThe Registry<\/b> class is a little different. As you saw yesterday, the StdRegProv<\/b> class provides a set of static methods for working with the registry. You don’t have instances in this case. The <StaticCmdlets><\/b> element tells the system that you are dealing with static members of the class rather than instances of CIM objects.\nEventually, the module will create a cmdlet for most methods in the StdRegProv<\/b> class. To get a quick reminder of the methods available, you can use:<\/p>\n

Get-CimClass -ClassName StdRegProv | select -ExpandProperty CimClassMethods\nMany registry properties are strings, so I’m going to start with the GetStringValue<\/b> method:<\/p>\n

    <CmdletMetadata Verb=”Get” Noun=”RegistrySTRING” ConfirmImpact=”Low”\/><\/p>\n

    <Method MethodName=”GetSTRINGvalue”>\nThe cmdlet metadata sets the verb as Get<\/b> and the noun as RegistrySTRING<\/b> (this is capitalized for demonstration purposes, but feel free to revert to normal Windows PowerShell case conventions if you desire). This cmdlet will be called Get-RegistrySTRING<\/b> and it will use the GetSTRINGvalue<\/b> method.\nThe methods in CIM classes return data and a return value. If the return value is zero (0), it worked correctly. Any other value indicates failure. A return value is useful when troubleshooting registry issues, so you should include it in your cmdlet:<\/p>\n

     <ReturnValue><\/p>\n

      <Type PSType=”System.UInt32″\/><\/p>\n

      <CmdletOutputMetadata><\/p>\n

      <\/CmdletOutputMetadata><\/p>\n

     <\/ReturnValue>\nThe type is very important. It must be System.UInt32<\/b>, that is, an unsigned 32-bit integer. CIM works with unsigned integers, which only have positive values:<\/p>\n

£> [uint32]::MinValue<\/p>\n

0<\/p>\n

£> [uint32]::MaxValue<\/p>\n

4294967295\nIn contrast, the standard integer can take positive and negative values:<\/p>\n

£> [int32]::MinValue<\/p>\n

-2147483648<\/p>\n

£> [int32]::MaxValue<\/p>\n

2147483647\nThe last step in defining the cmdlet is to supply the information that is required to define its parameters. Each parameter is defined in a separate parameter block. The GetStringValue<\/b> method has four arguments—three input arguments and one output argument.\nGet-CimClass<\/b> and the WMI documentation refer to method parameters rather than arguments. To avoid additional confusion, I’m using arguments when I am talking about the method and I’m using parameters when I am talking about the resultant cmdlet.\nThe first input argument, hDefKey<\/b>, defines the hive to be accessed. Remember that this is a number, for instance:<\/p>\n

HKEY_LOCAL_MACHINE = 2147483650 (0x80000002)\nIt is supplied as an unsigned integer and the method argument name is overridden, so the cmdlet parameter name is Hive<\/b> rather than hDefKey<\/b>. This isn’t necessary, but it makes the cmdlet easier to use. The name of your cmdlet parameter is your choice—use whatever makes the cmdlet easier to use for you.<\/p>\n

      <Parameter ParameterName=”hDefKey” ><\/p>\n

       <Type PSType=”System.UInt32″ \/><\/p>\n

       <CmdletParameterMetadata PSName=”Hive”><\/p>\n

       <\/CmdletParameterMetadata><\/p>\n

      <\/Parameter>\nThe sSubKeyName<\/b> and sValueName<\/b> arguments for GetStringValue<\/b> define the value you are reading from the registry. Both use “System.String”<\/b> as their type, and I’ve overridden the argument names so the cmdlet’s parameters are SubKey<\/b> and ValueName<\/b> respectively:<\/p>\n

      <Parameter ParameterName=”sSubKeyName” ><\/p>\n

       <Type PSType=”System.String” \/><\/p>\n

       <CmdletParameterMetadata PSName=”SubKey”><\/p>\n

       <\/CmdletParameterMetadata><\/p>\n

      <\/Parameter>\n <\/p>\n

      <Parameter ParameterName=”sValueName” ><\/p>\n

       <Type PSType=”System.String” \/><\/p>\n

       <CmdletParameterMetadata PSName=”ValueName”><\/p>\n

       <\/CmdletParameterMetadata><\/p>\n

      <\/Parameter>\nThe final argument for the GetStringValue<\/b> method is sValue<\/b>. This again is a string, but it is the property for the return object that holds the value read from the registry. <CmdletOutputMetadata \/><\/b> is required to ensure the data is output:<\/p>\n

      <Parameter ParameterName=”sValue”><\/p>\n

       <Type PSType=”System.String” \/><\/p>\n

       <CmdletOutputMetadata \/><\/p>\n

      <\/Parameter>\n   Note<\/strong>  Renaming output parameters doesn’t seem to be possible.\nSave the file with the CDXML definition as registry1.cdxml. You can load it into Windows PowerShell:<\/p>\n

£> Get-Command -Module registry1<\/p>\n

CommandType   Name                        ModuleName<\/p>\n

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

Function    Get-RegistrySTRING                 registry1<\/p>\n

£> Get-Command Get-RegistrySTRING -Syntax<\/p>\n

Get-RegistrySTRING [-Hive <uint32>] [-SubKey <string>] [-ValueName <string>] [-CimSession <CimSession[]>] [-ThrottleLimit <int>] [-AsJob] [-WhatIf] [-Confirm] [<CommonParameters>]\nYou can use the following commands to use it.\nTo define the hive to use (in this case, HKLM):<\/p>\n

 [uint32]$hklm = 2147483650\nTo define the subkey and value to read:<\/p>\n

 $subkey = “SOFTWAREMicrosoftInternet Explorer”<\/p>\n

 $value = “Version”\nTo use the cmdlet:<\/p>\n

Get-RegistrySTRING -Hive $hklm -SubKey $subkey -ValueName $value\nThis gives the following result:<\/p>\n

sValue              ReturnValue<\/p>\n

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

9.11.9600.17498      0\nNow you know how to get started creating cmdlets for working with the registry. This series will continue tomorrow when I will show you how to change the code to enable you to use friendly names for the registry hives, make parameters mandatory, and perform validation on the values input to parameters.\nWe invite you to follow The Scripting Guys on Twitter<\/a> and Facebook<\/a>. If you have any questions, send an email to The Scripting Guys at scripter@microsoft.com<\/a>, or post your questions on the Official Scripting Guys Forum<\/a>. Until then, remember eat your cmdlets every day with a dash of creativity.\nRichard Siddaway, <\/b>Windows PowerShell MVP and Honorary Scripting Guy<\/p>\n","protected":false},"excerpt":{"rendered":"

Summary: Richard Siddaway shows how to start creating CDXML cmdlets. Honorary Scripting Guy, Richard Siddaway, here today filling in for my good friend, The Scripting Guy. This is the second post in a series. Yesterday, in Registry Cmdlets: Working with the Registry, I explained that there aren’t any cmdlets for working directly with the registry. […]<\/p>\n","protected":false},"author":596,"featured_media":87096,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[385,26,189,45],"class_list":["post-74209","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-scripting","tag-cim","tag-registry","tag-richard-siddaway","tag-windows-powershell"],"acf":[],"blog_post_summary":"

Summary: Richard Siddaway shows how to start creating CDXML cmdlets. Honorary Scripting Guy, Richard Siddaway, here today filling in for my good friend, The Scripting Guy. This is the second post in a series. Yesterday, in Registry Cmdlets: Working with the Registry, I explained that there aren’t any cmdlets for working directly with the registry. […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts\/74209","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\/596"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/comments?post=74209"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/posts\/74209\/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=74209"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/categories?post=74209"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/scripting\/wp-json\/wp\/v2\/tags?post=74209"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}