Edit

Share via

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.

PowerShell 
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.

Output 
    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.

PowerShell 
Import-Module .\AzCmAgent.psd1
Get-Command -Module AzCmAgent
Output 
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.

PowerShell 
Show-AzCmAgent
Output 
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.

PowerShell 
Show-AzCmAgent | Select-Object -ExpandProperty services
Output 
displayName       serviceName      status
-----------       -----------      ------
GC Service        gcarcservice     running
Extension Service extensionservice running
Agent Service     himds            running

Next we test the Get-AzCmAgentConfigProperty cmdlet.

PowerShell 
Get-AzCmAgentConfigProperty -Property proxy.url
Output 
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.

PowerShell 
Test-IsCrescendoCommand -Command Get-AzCmAgentConfigProperty
Output 
   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.