Edit

Generate and test a Crescendo module

  • Article

In the previous article we created configurations for two new cmdlets. Using this configuration, Crescendo can generate a new PowerShell script module.

Generate your new module

Now you're ready to create your module. Use the Export-CrescendoModule cmdlet to generate the new PowerShell script module.

Export-CrescendoModule -ConfigurationFile AzCmAgent.json -ModuleName AzCmAgent.psm1

The ConfigurationFile can take an array of filenames. This allows you to create separate JSON files for each cmdlet. The ModuleName parameter specifies the full path and filename for the module file being created. In this example, the files are being created in the current directory.

As seen the following output, Export-CrescendoModule creates two files -- the module (PSM1) file and the module manifest (PSD1) file. These are the only files that end user of your module needs to install.

    Directory: D:\temp\azcmagent

Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
-a---            3/9/2022  1:59 PM           2167 AzCmAgent.json
-a---            3/9/2022  2:33 PM           4365 AzCmAgent.psd1
-a---            3/9/2022  2:33 PM           8017 AzCmAgent.psm1

Test the cmdlets in your module

To test your module, import it into your PowerShell session and run the cmdlets.

Import-Module .\AzCmAgent.psd1
Get-Command -Module AzCmAgent

CommandType     Name                                               Version    Source
-----------     ----                                               -------    ------
Function        Get-AzCmAgentConfigProperty                        0.0.1      AzCmAgent
Function        Show-AzCmAgent                                     0.0.1      AzCmAgent

In the previous article we defined two cmdlets.

Important

The azcmagent tool requires elevation to run. This means that you must run your module in an elevated PowerShell session.

Show-AzCmAgent

resourceName      :
resourceGroup     :
resourceNamespace :
subscriptionId    :
tenantId          :
vmId              :
correlationId     :
vmUuid            :
location          :
privateLinkScope  :
cloud             :
agentVersion      : 1.15.01879.114
logs              : C:\ProgramData\AzureConnectedMachineAgent\Log\himds.log
status            : Disconnected
lastHeartbeat     :
agentErrorCode    :
agentErrorDetails :
agentErrorTime    :
httpsProxy        :
proxyBypass       :
cloudProvider     : N/A
cloudMetadata     :
manufacturer      : LENOVO
model             : 30BFS07500
sql               : false
services          : {@{displayName=GC Service; serviceName=gcarcservice; status=running},
                    @{displayName=Extension Service; serviceName=extensionservice; status=running},
                    @{displayName=Agent Service; serviceName=himds; status=running}}

Now that the we have amplified the azcmagent show command, it can participate in the PowerShell pipeline.

Show-AzCmAgent | Select-Object -ExpandProperty services

displayName       serviceName      status
-----------       -----------      ------
GC Service        gcarcservice     running
Extension Service extensionservice running
Agent Service     himds            running

Next we test the Get-AzCmAgentConfigProperty cmdlet.

Get-AzCmAgentConfigProperty -Property proxy.url

Type Status  Messages                     Data
---- ------  --------                     ----
   0 success {proxy.url has not been set}

Finding Crescendo-created cmdlets

As you create and deploy more Crescendo-based modules, it may be beneficial to determine if a cmdlet was generated by Crescendo. Crescendo provides Test-IsCrescendoCommand cmdlet to help.

Test-IsCrescendoCommand -Command Get-AzCmAgentConfigProperty

   Module: AzCmAgent

Name                        IsCrescendoCommand RequiresElevation
----                        ------------------ -----------------
Get-AzCmAgentConfigProperty True               False

Note

As previously discussed, your new module must be run in an elevated session. In this example, Test-IsCrescendoCommand returned RequiresElevation as False. Crescendo provides methods for privilege elevation for all platforms. However, we didn't include elevation in our configuration examples.