Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Amend contributing documentation with a guide on how we write C# Cmdlets for PowerShell #3539

Closed
2 tasks done
Tracked by #3477
vexx32 opened this issue Oct 28, 2024 · 1 comment
Closed
2 tasks done
Tracked by #3477

Amend contributing documentation with a guide on how we write C# Cmdlets for PowerShell #3539

vexx32 opened this issue Oct 28, 2024 · 1 comment
Labels
4 - Done Documentation
Milestone
3.0.0

Comments

@vexx32
Copy link
Member

vexx32 commented Oct 28, 2024

Checklist

  • I have verified this is the correct repository for opening this issue.
  • I have verified no other issues exist related to my request.

Is Your Feature Request Related To A Problem? Please describe.

No response

Describe The Solution. Why is it needed?

We need to amend the contribution documentation in this repository to include some information about how we tend to author C# cmdlets, classes and design patterns to make use of and those to avoid as well.

Specifically, we should include the following information:

  • Cmdlets should inherit from ChocolateyCmdlet and not Cmdlet or PSCmdlet
  • When and how to make use of SupportsShouldProcess aka -WhatIf / -Confirm
  • Cmdlets should contain minimal to no core logic, anything that other cmdlets need to make use of should be provided as part of a helper class, since calling into other C# cmdlets is not something that can or should really be done directly.
  • Usage and extension of existing helpers like PSHelper or ChocolateyCmdlet and so forth
  • How to manage error handling, and where
    • Exceptions should be thrown in core logic, caught and rethrown using ThrowTerminatingError() or WriteError() in the cmdlet layer itself
  • Dependency injection must be avoided, at least in anything that's in the cmdlet layer itself (inheriting ChocolateyCmdlet) as PowerShell does not support this.
  • Some guidance on communication between Chocolatey CLI and cmdlets, which is typically mediated with environment variables.
  • Under no circumstances should there be a direct dependency on CLI code from the cmdlets project, they need to remain separate.

Additional Context

No response

Related Issues
@vexx32 vexx32 mentioned this issue Oct 28, 2024
Open
2 tasks
vexx32 added a commit to vexx32/choco that referenced this issue Jan 15, 2025
@vexx32
(chocolatey#3539) Add design documentation for C# cmdlets
da6465d 
Given we use some slightly custom bits in Chocolatey.PowerShell that
will alter how contributors are expected to work with the cmdlets in
this project compared to how more bare-bones projects handle C# cmdlets,
this document outlines some of the more notable changes as well as the
common design practices we will be using here.
@vexx32 vexx32 mentioned this issue Jan 15, 2025
Merged
10 tasks
vexx32 added a commit to vexx32/choco that referenced this issue Jan 16, 2025
@vexx32
(chocolatey#3539) Add design documentation for C# cmdlets
5186e34 
Given we use some slightly custom bits in Chocolatey.PowerShell that
will alter how contributors are expected to work with the cmdlets in
this project compared to how more bare-bones projects handle C# cmdlets,
this document outlines some of the more notable changes as well as the
common design practices we will be using here.
@gep13
Copy link
Member

gep13 commented Jan 20, 2025

@vexx32 when are we planning on shipping the work associated with this? Can we agree a milestone for this, and then get that assigned?

@vexx32 vexx32 added this to the 3.0.0 milestone Jan 21, 2025
corbob pushed a commit that referenced this issue Jan 23, 2025
@vexx32
(#3539) Add design documentation for C# cmdlets
2c05442 
Given we use some slightly custom bits in Chocolatey.PowerShell that
will alter how contributors are expected to work with the cmdlets in
this project compared to how more bare-bones projects handle C# cmdlets,
this document outlines some of the more notable changes as well as the
common design practices we will be using here.
corbob added a commit that referenced this issue Jan 23, 2025
@corbob
Merge pull request #3601 from vexx32/design-doc
663ac55 
(#3539) Add design documentation for C# cmdlets
@corbob corbob closed this as completed Jan 23, 2025
vexx32 added a commit that referenced this issue Jan 24, 2025
@vexx32
(#3539) Add design documentation for C# cmdlets
46fa7bf 
Given we use some slightly custom bits in Chocolatey.PowerShell that
will alter how contributors are expected to work with the cmdlets in
this project compared to how more bare-bones projects handle C# cmdlets,
this document outlines some of the more notable changes as well as the
common design practices we will be using here.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
4 - Done Documentation
Projects
None yet
Milestone
3.0.0
Development

No branches or pull requests
3 participants
@gep13 @corbob @vexx32