PowerShell Suggestions

Dec 16, 2010 at 7:55 PM
Edited Dec 16, 2010 at 8:02 PM

Missing Examples in Cmdlet help

Every Cmdlet should have least one example.

Module Design

I think there's room to consolidate the binary module (nuget.visualstudio.dll) and the script (nuget.psm1) under a single manifest. Currently, executing "get-command -module nuget" returns nothing. This is unexpected, and impedes discovery. So, I would suggest that you move the Nuget.VisualStudio*.* stuff under scripts and drop in a module manifest named "NuGet.psd1" with contents similar to the following:

@{

# Script module or binary module file associated with this manifest
ModuleToProcess = 'NuGet.VisualStudio.dll'

# Version number of this module.
ModuleVersion = '1.0'

# ID used to uniquely identify this module
GUID = '76e6f9c4-7045-44c0-a557-17fab0835c12'

# Author of this module
Author = 'NuGet Team'

# Company or vendor of this module
CompanyName = 'NuGet'

# Copyright statement for this module
Copyright = '(c) 2010 NuGet Team. All rights reserved.'

# Description of the functionality provided by this module
Description = 'NuGet PowerShell Command Line Module'

# Minimum version of the Windows PowerShell engine required by this module
PowerShellVersion = '2.0'

# Name of the Windows PowerShell host required by this module
PowerShellHostName = 'Package Manager Host'

# Minimum version of the Windows PowerShell host required by this module
PowerShellHostVersion = ''  # 1.0.10128.89 ?

# Minimum version of the .NET Framework required by this module
DotNetFrameworkVersion = ''

# Minimum version of the common language runtime (CLR) required by this module
CLRVersion = ''

# Processor architecture (None, X86, Amd64, IA64) required by this module
ProcessorArchitecture = ''

# Modules that must be imported into the global environment prior to importing this module
RequiredModules = @()

# Assemblies that must be loaded prior to importing this module
RequiredAssemblies = @()

# Script files (.ps1) that are run in the caller's environment prior to importing this module
ScriptsToProcess = @()

# Type files (.ps1xml) to be loaded when importing this module
TypesToProcess = @()

# Format files (.ps1xml) to be loaded when importing this module
FormatsToProcess = @()

# Modules to import as nested modules of the module specified in ModuleToProcess
NestedModules = @((join-path $psscriptroot 'NuGet.psm1'))

# Functions to export from this module
FunctionsToExport = '*'

# Cmdlets to export from this module
CmdletsToExport = '*'

# Variables to export from this module
VariablesToExport = '*'

# Aliases to export from this module
AliasesToExport = '*'

# List of all modules packaged with this module
ModuleList = @()

# List of all files packaged with this module
FileList = @()

# Private data to pass to the module specified in ModuleToProcess
PrivateData = ''

}

Then, in your bootstrap code load the NuGet.psd1 module - it will in turn import nuget.psm1 and also import the commands in the DLL. In script, this would be as simple as "import-module <path>\nuget.psd1" All functions, aliases and commands will then appear when you try "get-module nuget" or "get-command -module nuget" This is a much more desirable and expected experience. You must place the dll-help.xml file in the scripts folder also. Instead of using Export-ModuleMember within the psm1, you can trim exported functions and aliases by placing them in the manifest above (left blank at the moment.) Remember that bringing commands into the caller's session is a two-step process. The nested module nuget.psm1 and the DLL actively export (the psm1 with export-modulemember, the dll exports all by default) and the manifest (nuget.psd1) passively imports, trimming with directives in the psd1.

List-Packages

"List" is not an approved verb and works against powershell's notion of discoverability. I suggest removing any dependencies on this before RTM. It's ok to have a compatibilty alias for v2, but even then I would still never expect non-standard verbs in either the target or alias. Aliases are typically not in the verb-noun syntax anyway. Get rid of it now before it becomes a wart on the pristine hide of NuGet.

Add-BindingRedirects

Nouns should always be singular unless the returned output is always guaranteed to be multiple objects. The singular form is standard - consider changing the Cmdlet name to Add-BindingRedirect.

Dec 16, 2010 at 8:49 PM

Thanks for the suggestions. I'll copy this into a work item to track this.

Dec 16, 2010 at 8:49 PM
This discussion has been copied to a work item. Click here to go to the work item and continue the discussion.