IotHub Commandlets

[rkmanda]

Description

---

This checklist is used to make sure that common guidelines for a pull request are followed. You can find a more complete discussion of PowerShell cmdlet best practices here.

• I have read the contribution guidelines.
• If changes were made to any cmdlet, the XML help was regenerated using the platyPSHelp module.
• If any large changes are made to a service, they are reflected in the respective change log.

General Guidelines

• Title of the pull request is clear and informative.
• There are a small number of commits, each of which have an informative message. This means that previously merged commits do not appear in the history of the PR. For more information on cleaning up the commits in your PR, see this page.
• The pull request does not introduce breaking changes (unless a major version change occurs in the assembly and module).

Testing Guidelines

• Pull request includes test coverage for the included changes.
• PowerShell scripts used in tests should do any necessary setup as part of the test or suite setup, and should not use hard-coded values for locations or existing resources.

Cmdlet Signature Guidelines

• New cmdlets that make changes or have side effects should implement ShouldProcess and have SupportShouldProcess=true specified in the cmdlet attribute. You can find more information on ShouldProcess here.
• Cmdlet specifies OutputType attribute if any output is produced - if the cmdlet produces no output, it should implement a PassThrough parameter.

Cmdlet Parameter Guidelines

• Parameter types should not expose types from the management library - complex parameter types should be defined in the module.
• Complex parameter types are discouraged - a parameter type should be simple types as often as possible. If complex types are used, they should be shallow and easily creatable from a constructor or another cmdlet.
• Cmdlet parameter sets should be mutually exclusive - each parameter set must have at least one mandatory parameter not in other parameter sets.

[azurecla]

Hi @rkmanda, I'm your friendly neighborhood Azure Pull Request Bot (You can call me AZPRBOT). Thanks for your contribution!

It looks like you're working at Microsoft (rmanda). If you're full-time, we DON'T require a contribution license agreement.

If you are a vendor, DO please sign the electronic contribution license agreement. It will take 2 minutes and there's no faxing! https://cla.azure.com.

TTYL, AZPRBOT;

[azuresdkci]

Can one of the admins verify this patch?

[markcowl]

@azuresdkci add to whitelist

[markcowl]

@rkmanda Since this is your first cmdlet release, please schedule a cmldte design review with our team

[markcowl]

@rkmanda please fix build failures.

[cormacpayne]

@rkmanda can you address the comment above?

[cormacpayne]

@rkmanda a few extra comments:

• There are a few cmdlets that have ResourceGroupName and Name as positional parameters, and the rest of the mandatory parameters do not have positions. Please resolve this issue and keep in mind that you should have at most four positional parameters in a cmdlet
• All of the cmdlets that make changes implement SupportsShouldProcess, however, you didn't implement the prompt in the cmdlet execution code in any of the cmdlets except for one. Please resolve this issue.

[cormacpayne]

@rkmanda why not 0.0.1?

[cormacpayne]

@rkmanda this needs to match your module version, 0.0.1

[cormacpayne]

@rkmanda this needs to be the same as the module version, 0.0.1

[cormacpayne]

@rkmanda is there a reason why the first two parameters have a position and the last two do not? Currently these are the two scenarios you support:

Add-AzureRmIotHubEventHubConsumerGroup -ResourceGroupName "rgname" -Name "name" -EventHubEndpointName "endpoint" -EventHubConsumerGroupName "groupname"
Add-AzureRmIotHubEventHubConsumerGroup "rgname" "name" -EventHubEndpointName "endpoint" -EventHubConsumerGroupName "groupname"

The first scenario is great, but I think the second scenario should be fixed so that all of the parameters have a position (since they are all mandatory). This would allow users to do the following:

Add-AzureRmIotHubEventHubConsumerGroup "rgname" "name" "endpoint" "groupname"

Let me know what you think

[rkmanda]

The only motivation for pattern 2 was a guideline I remember reading on one of the docs which suggested making the rg name and name positional . It makes sense to make the others positional too . SO I will make that change

[cormacpayne]

@rkmanda this cmdlet implements SupportsShouldProcess, but the execution of the cmdlet is not wrapped in the if-statement containing the ShouldProcess prompt.

View this document for more information.

[cormacpayne]

@rkmanda why do you need two parameter sets if the only difference between the two is the KeyName parameter? Why not make it optional and then you can get rid of the switch statement and just do

if (KeyName == null)
{
    IEnumerable<SharedAccessSignatureAuthorizationRule> authPolicies = this.IotHubClient.IotHubResource.ListKeys(this.ResourceGroupName, this.Name);
    this.WriteObject(IotHubUtils.ToPSIotHubConnectionStrings(authPolicies, hostName), true);
}
else
{
    SharedAccessSignatureAuthorizationRule authPolicy = this.IotHubClient.IotHubResource.GetKeysForKeyName(this.ResourceGroupName, this.Name, this.KeyName);
    this.WriteObject(authPolicy.ToPSIotHubConnectionString(hostName), false);
}

[cormacpayne]

@rkmanda this will not work; the following command will throw an error because PowerShell will be unable to determine which parameter set you are using:

Get-AzureRmIotHubJob -ResourceGroupName "rgname" -Name "name"

I would recommend getting rid of the parameter sets and keeping this parameter optional. Then use the same solution suggested for GetAzureRmIotHubConnectionString

[cormacpayne]

@rkmanda same comment as GetAzureRmIotHubConnectionString

[cormacpayne]

@rkmanda I would recommend getting rid of positional parameters for this cmdlet

[cormacpayne]

@rkmanda you will also need to add a reference to your test project after this line: https://github.com/Azure/azure-powershell/blob/dev/AzurePowershell.Test.targets#L87

[markcowl]

@rkmanda need to fix the build break and respond to comments

[rkmanda]

Just back from a vacation. :) Thanks for the comments. Will be working on this early next week.

[markcowl]

@rkmanda. Please open a new PR when you are ready to respond to comments