documentation build fails with odd error

[DBHeise]

IF You add a blank HelpMessage on a cmdlet parameter code generation will fail trying to look for the System.Management.Automation.resources.dll file.

This is admittedly a very minor deal...

Specifically this code:

    [Parameter(Mandatory = true, ParameterSetName = "id", HelpMessage = "")]
    public int Id { get; set; }

Fails with the attached exception.
exception.txt

[ChrisLambrou]

Hi,

I have a few questions for you to help track this down.

• Does this only happen when the HelpMessage property is an empty string (rather than absent or is a non-empty string)?
• Can you browse to the definition of the ParameterAttribute class within your own project (not the one shipped with XmlDoc2CmdletDoc), and tell me its version and expected location?
• In the attached log file, on line 3, you've redacted the path of the assembly. Can you include more of the path? Enough to tell me whether it's coming from the GAC, one of your own dependencies, the unpacked folder of the XmlDoc2CmdletDoc package, or somewhere else entirely?

Exception: Could not load file or assembly 'file:///{REDACTED2}\System.Management.Automation.resources.dll' or one of its dependencies. The system cannot find the file specified.

Thanks,

Chris

[DBHeise]

1. Yes its only when the HelpMessage property is an empty string
2. The Parameter Attribute is defined in: System.Management.Automation, Version=3.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35 in file C:\Program Files (x86)\Reference Assemblies\Microsoft\WindowsPowerShell\3.0\System.Management.Automation.dll
3. The redacted path is build output folder, or in other words the same location as the cmdlet dll

[ChrisLambrou]

Thanks. I'll try to have a look at this over the weekend.

[ChrisLambrou]

Okay, I had a look at the HelpMessage property of the ParameterAttribute class, and it's implementation looks like this:

public string HelpMessage
{
  get
  {
    return this.helpMessage;
  }
  set
  {
    if (string.IsNullOrEmpty(value))
      throw CmdletMetadataAttribute.tracer.NewArgumentException("value");
    this.helpMessage = value;
  }
}

It seems that, whilst it's okay to leave it unspecified (where it defaults to null), if you do specify a value, it cannot be null or an empty string. The XmlDoc2CmdletDoc tool is trying to instantiate the ParameterAttribute instance on your cmdlet's parameter, but it's constructor is failing due to an illegal empty HelpMessage property. Basically, it's a code error in your cmdlet. Not only is XmlDoc2CmdletDoc failing becaise of this, but you're also likely to get unexpected behaviour in your cmdlet, since the PowerShell will likely run into trouble loading your cmdlet.

I'll look into getting XmlDoc2CmdletDoc to fail more gracefully (i.e. with a more meaningful error message) when it fails to load a ParameterAttribute on a parameter, but the basic issue is that users must make sure they don't have any null or empty HelpMessage properties on their parameters.

[ChrisLambrou]

I should also add that XmlDoc2CmdletDoc ignores the HelpMessage property of the ParameterAttribute. The intention is that all the help text be defined in the XML Doc comments. Maybe it could fall back to the HelpMessage property if there's no appropriate XML Doc help content found? Maybe the two could be merged? I'm not sure - I'll have a think about it...

[ChrisLambrou]

Superseded by #30.