(#3539) Add design documentation for C# cmdlets #3601
Conversation
|
One other thing that's occurred to me: Should we consider linking to this from the higher up contributing document? I'm a little concerned about the discoverability of the document if it's just a file in a directory where you might not look for it as you're in Visual Studio... |
That's something I thought about and... am not really sure about. I suppose it can't hurt, I did have a bit of a difficult time trying to figure out a sensible place in the main CONTRIBUTING doc to reference it, but I can always add a new section... It also should probably be put into the sln file just to make it more visible in VS, I think. I'll do both. |
vexx32
force-pushed
the
design-doc
branch
3 times, most recently
from
411b3ac to
a7ea3de
Compare
|
@corbob I have incorporated your suggestions, and added a section about helpers to indicate they should not be directly writing to PowerShell output/error streams and suggest a common pattern to be used for those cases. |
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.
| > To facilitate this, we can put the core logic of `Install-ChocolateyInstallPackage` into a helper class, and the actual `InstallChocolateyInstallPackageCommand` class we would write would only define parameters, then call into the helper class. | ||
| > Then, when we write the `InstallChocolateyPackageCommand`, it can download files and then call into the same helper class to run the other cmdlet's logic seamlessly. | ||
|
|
||
| ### Helpers should return data or throw exceptions, not write output or errors |
There was a problem hiding this comment.
For completeness @gep13 could you review this section as it was added after your approval.
| Additionally, since all cmdlets are initialised by the PowerShell runtime, we cannot use a dependency injection framework to make things work. | ||
| As a result, many of the helpers will be a little more bare-bones and not make as heavy use of interfaces as other code areas in this repository. | ||
|
|
||
| ## Interop with Chocolatey CLI |
There was a problem hiding this comment.
For completeness @gep13 could you review this section as it was added after your approval.
Description Of Changes
Motivation and Context
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.
Testing
N/A, doc only.
Operating Systems Testing
N/A
Change Types Made
Change Checklist
Related Issue
Fixes #3539