Dotnet Standards

Playbook: dotnet-standards

C# 12 / .NET 8 and PowerShell cmdlet design rules for this repository. Referenced by code-review, new-cmdlet and cmdlet-scaffolder.

Two rule sets apply at once, and where they disagree the PowerShell one wins: this is a module whose users are shell users, not a class library.

PowerShell cmdlet design

These come from Microsoft's cmdlet development guidelines. Violations are user-facing.

Naming

• Verb-PnPNoun, one approved verb (Get-Verb), singular noun even when returning many objects.
• PnP prefix always. New cmdlet names should not collide with other modules' nouns.
• Parameter names should match the ones used by comparable cmdlets in this module before inventing a new one — -Identity, -Connection, -Force, -Includes, -Batch have established meanings.

Output

• Emit objects, never formatted text. WriteObject(x) — and WriteObject(collection, true) to enumerate, so the pipeline sees items rather than one array.
• [OutputType(typeof(T))] on every cmdlet that returns something.
• Never Console.WriteLine. Channels: WriteObject (data), WriteWarning (recoverable), WriteVerbose (diagnostics), WriteDebug, WriteProgress (long operations).
• Do not return null to mean "not found" where the user asked for a specific item — write an error. Returning nothing for a filter that matched nothing is correct.

Input

• [Parameter] per parameter with deliberate Mandatory, Position, ValueFromPipeline. Positional only for the one obvious parameter; everything else named.
• Use PipeBind types (ListPipeBind, SitePipeBind, …) so a name, an ID or an object all bind.
• ParameterSpecified(nameof(X)) to distinguish "not supplied" from "supplied as the default".
• [ValidateNotNull] on any reference-typed parameter dereferenced in ExecuteCmdlet — otherwise -Param $null is a NullReferenceException rather than a message.
• [ValidateSet] / [ValidateRange] / [ValidateCount] rather than hand-rolled checks in the body.
• Prefer SwitchParameter over bool for flags. A bool parameter forces -Flag $true and reads wrong in PowerShell.

Safety

• Anything destructive or overwriting: SupportsShouldProcess = true, then actually call ShouldProcess. Adding a prompt where none existed breaks unattended scripts — see api-surface-diff.

• -Force may bypass ShouldContinue, never ShouldProcess. ShouldProcess is what implements -WhatIf and -Confirm, so short-circuiting it breaks simulation:

  if (Force || ShouldContinue($"Remove {Identity}?", Resources.Confirm))   // correct — the repo's pattern
  if (Force || ShouldProcess($"{target}", "Remove"))                       // WRONG — -Force -WhatIf deletes

  In the second form -Force short-circuits the ||, ShouldProcess is never called, and -Force -WhatIf performs the operation instead of simulating it. Where both are wanted, gate on ShouldProcess first and use Force || only on the inner ShouldContinue. This is a live defect in src/Commands/Apps/RemoveEntraIDServicePrincipalAppRoleAssignment.cs:52 — flag it if you touch that file, and never copy that line as a model.

• Never hardcode credentials, tenant names or endpoints.

Errors

• ThrowTerminatingError(new ErrorRecord(...)) for fatal errors, with a meaningful ErrorCategory and the object that caused it. Prefer it over a bare throw — and this is not only style, it changes what the user receives:
  • WriteError and ThrowTerminatingError surface under -ErrorAction Stop as a pipeline stop, which PnPConnectedCmdlet.ProcessRecord rethrows untouched (src/Commands/Base/PnPConnectedCmdlet.cs:57-60). Your ErrorRecord, its category and its target object survive intact.
  • A raw throw reaches the generic catch. Under the default error action it becomes PSInvalidOperationException with the original as inner; under -ErrorAction Stop or SilentlyContinue it becomes new ErrorRecord(new Exception(message), source, ErrorCategory.NotSpecified, null) — type, inner exception, category and target object are all lost, so everything the user needs must be in the message text. Under -ErrorAction Ignore LogError is skipped, so nothing is written at all.
• Error messages belong in Resources.resx, referenced as Resources.MessageName.