New-MarkdownHelp fails with "Unable to find Type..."-Error for defined Output Type

DEberhardt commented 2 years ago

Prerequisites

[X] Write a descriptive title.
[X] Make sure you are able to repro it on the latest released version
[X] Search the existing issues.

Steps to reproduce

When running the MarkDownhelp in a Github action, I get a different behaviours despite running the command from the same version.

"It worked on my machine", but it doesn't work on the build runner :/

only one similar issue "Unable to find type" was found, but resolution there was not suitable for me.

Am I missing some "using..." statement which would allow me to use the OutputType, should I not use it or is this something else?

Cheers, David

Expected behavior

New-MarkdownHelp -Module TeamsFunctions -OutputFolder .\docs -Force -AlphabeticParamsOrder:$false

    Directory: D:\code\Personal\TeamsFunctions\docs

Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
-a----   Wed 29 Jun 2022     18:29           1706 Assert-AzureADConnection.md
-a----   Wed 29 Jun 2022     18:29           1769 Assert-MicrosoftTeamsConnection.md
-a----   Wed 29 Jun 2022     18:29           2698 Assert-Module.md
-a----   Wed 29 Jun 2022     18:29           3307 Assert-TeamsCallableEntity.md
-a----   Wed 29 Jun 2022     18:29           5200 Assert-TeamsUserVoiceConfig.md
-a----   Wed 29 Jun 2022     18:29           2293 Backup-TeamsEV.md
-a----   Wed 29 Jun 2022     18:29           2402 Backup-TeamsTenant.md
-a----   Wed 29 Jun 2022     18:29           4810 Connect-Me.md
-a----   Wed 29 Jun 2022     18:29           4557 Disable-AzureAdAdminRole.md
-a----   Wed 29 Jun 2022     18:29           1642 Disable-MyAzureAdAdminRole.md
-a----   Wed 29 Jun 2022     18:29           2651 Disconnect-Me.md
-a----   Wed 29 Jun 2022     18:29           6117 Enable-AzureAdAdminRole.md
-a----   Wed 29 Jun 2022     18:29           1636 Enable-MyAzureAdAdminRole.md
-a----   Wed 29 Jun 2022     18:29           3987 Enable-TeamsUserForEnterpriseVoice.md
-a----   Wed 29 Jun 2022     18:29           2154 Find-AzureAdGroup.md
-a----   Wed 29 Jun 2022     18:29           2782 Find-AzureAdUser.md
-a----   Wed 29 Jun 2022     18:29           3397 Find-TeamsCallableEntity.md
-a----   Wed 29 Jun 2022     18:29           6852 Find-TeamsEmergencyCallRoute.md
-a----   Wed 29 Jun 2022     18:29           3186 Find-TeamsResourceAccount.md
-a----   Wed 29 Jun 2022     18:29          10883 Find-TeamsUserVoiceConfig.md
-a----   Wed 29 Jun 2022     18:29           4541 Find-TeamsUserVoiceRoute.md
-a----   Wed 29 Jun 2022     18:29           4128 Format-StringForUse.md
-a----   Wed 29 Jun 2022     18:29           2835 Format-StringRemoveSpecialCharacter.md
-a----   Wed 29 Jun 2022     18:29           3095 Get-AzureAdAdminRole.md
-a----   Wed 29 Jun 2022     18:29           2755 Get-AzureAdLicense.md
-a----   Wed 29 Jun 2022     18:29           2704 Get-AzureAdLicenseServicePlan.md
-a----   Wed 29 Jun 2022     18:29           3172 Get-AzureAdUserLicense.md
-a----   Wed 29 Jun 2022     18:29           3890 Get-AzureAdUserLicenseServicePlan.md
-a----   Wed 29 Jun 2022     18:29           1748 Get-CurrentConnectionInfo.md
-a----   Wed 29 Jun 2022     18:29           2237 Get-ISO3166Country.md
-a----   Wed 29 Jun 2022     18:29           2244 Get-MyAzureAdAdminRole.md
-a----   Wed 29 Jun 2022     18:29           2318 Get-PublicHolidayCountry.md
-a----   Wed 29 Jun 2022     18:29           3088 Get-PublicHolidayList.md
-a----   Wed 29 Jun 2022     18:29           2455 Get-RegionFromCountryCode.md
-a----   Wed 29 Jun 2022     18:29           2500 Get-SkypeOnlineConferenceDialInNumbers.md
-a----   Wed 29 Jun 2022     18:29           5815 Get-TeamsAutoAttendant.md
-a----   Wed 29 Jun 2022     18:29           4083 Get-TeamsAutoAttendantAudioFile.md
-a----   Wed 29 Jun 2022     18:29           4947 Get-TeamsAutoAttendantSchedule.md
-a----   Wed 29 Jun 2022     18:29           5225 Get-TeamsCallableEntity.md
-a----   Wed 29 Jun 2022     18:29           5474 Get-TeamsCallQueue.md
-a----   Wed 29 Jun 2022     18:29           2993 Get-TeamsCLI.md
-a----   Wed 29 Jun 2022     18:29           3746 Get-TeamsCommonAreaPhone.md
-a----   Wed 29 Jun 2022     18:29           2935 Get-TeamsCP.md
-a----   Wed 29 Jun 2022     18:29           2940 Get-TeamsECP.md
-a----   Wed 29 Jun 2022     18:29           2893 Get-TeamsECRP.md
-a----   Wed 29 Jun 2022     18:29           2931 Get-TeamsIPP.md
-a----   Wed 29 Jun 2022     18:29           2837 Get-TeamsMGW.md
-a----   Wed 29 Jun 2022     18:29           2888 Get-TeamsObjectType.md
-a----   Wed 29 Jun 2022     18:29           2382 Get-TeamsOPU.md
-a----   Wed 29 Jun 2022     18:29           3037 Get-TeamsOVP.md
-a----   Wed 29 Jun 2022     18:29           2970 Get-TeamsOVR.md
-a----   Wed 29 Jun 2022     18:29           7091 Get-TeamsPhoneNumber.md
-a----   Wed 29 Jun 2022     18:29           5672 Get-TeamsResourceAccount.md
-a----   Wed 29 Jun 2022     18:29           2467 Get-TeamsResourceAccountAssociation.md
-a----   Wed 29 Jun 2022     18:29           4042 Get-TeamsResourceAccountLineIdentity.md
-a----   Wed 29 Jun 2022     18:29           2806 Get-TeamsTDP.md
-a----   Wed 29 Jun 2022     18:29           3953 Get-TeamsTeamChannel.md
-a----   Wed 29 Jun 2022     18:29           7393 Get-TeamsTelephoneNumber.md
-a----   Wed 29 Jun 2022     18:29           1507 Get-TeamsTenant.md
-a----   Wed 29 Jun 2022     18:29           3291 Get-TeamsTenantLicense.md
-a----   Wed 29 Jun 2022     18:29           3103 Get-TeamsTenantVoiceConfig.md
-a----   Wed 29 Jun 2022     18:29           2968 Get-TeamsUserLicense.md
-a----   Wed 29 Jun 2022     18:29           3088 Get-TeamsUserLicenseServicePlan.md
-a----   Wed 29 Jun 2022     18:29           5729 Get-TeamsUserVoiceConfig.md
-a----   Wed 29 Jun 2022     18:29           5864 Get-TeamsVoiceNormalizationRule.md
-a----   Wed 29 Jun 2022     18:29           4088 Get-TeamsVoiceRoutingChain.md
-a----   Wed 29 Jun 2022     18:29           4983 Grant-TeamsEmergencyAddress.md
-a----   Wed 29 Jun 2022     18:29           2654 Import-TeamsAudioFile.md
-a----   Wed 29 Jun 2022     18:29           2584 New-AzureAdLicenseObject.md
-a----   Wed 29 Jun 2022     18:29          18217 New-TeamsAutoAttendant.md
-a----   Wed 29 Jun 2022     18:29           5321 New-TeamsAutoAttendantCallFlow.md
-a----   Wed 29 Jun 2022     18:29           2631 New-TeamsAutoAttendantDialScope.md
-a----   Wed 29 Jun 2022     18:29          11584 New-TeamsAutoAttendantMenu.md
-a----   Wed 29 Jun 2022     18:29           6518 New-TeamsAutoAttendantMenuOption.md
-a----   Wed 29 Jun 2022     18:29           4048 New-TeamsAutoAttendantPrompt.md
-a----   Wed 29 Jun 2022     18:29           9323 New-TeamsAutoAttendantSchedule.md
-a----   Wed 29 Jun 2022     18:29           4788 New-TeamsCallableEntity.md
-a----   Wed 29 Jun 2022     18:29          17550 New-TeamsCallQueue.md
-a----   Wed 29 Jun 2022     18:29           7626 New-TeamsCommonAreaPhone.md
-a----   Wed 29 Jun 2022     18:29           5427 New-TeamsHolidaySchedule.md
-a----   Wed 29 Jun 2022     18:29           7274 New-TeamsResourceAccount.md
-a----   Wed 29 Jun 2022     18:29           4258 New-TeamsResourceAccountAssociation.md
-a----   Wed 29 Jun 2022     18:29           4993 New-TeamsResourceAccountLineIdentity.md
-a----   Wed 29 Jun 2022     18:29           8506 New-TeamsUserVoiceConfig.md
-a----   Wed 29 Jun 2022     18:29           9278 New-TeamsVoiceRoutingChain.md
-a----   Wed 29 Jun 2022     18:29           2623 Remove-TeamsAutoAttendant.md
-a----   Wed 29 Jun 2022     18:29           2341 Remove-TeamsCallQueue.md
-a----   Wed 29 Jun 2022     18:29           3343 Remove-TeamsCommonAreaPhone.md
-a----   Wed 29 Jun 2022     18:29           3594 Remove-TeamsResourceAccount.md
-a----   Wed 29 Jun 2022     18:29           3453 Remove-TeamsResourceAccountAssociation.md
-a----   Wed 29 Jun 2022     18:29           5873 Remove-TeamsUserVoiceConfig.md
-a----   Wed 29 Jun 2022     18:29           4204 Remove-TeamsVoiceNormalizationRule.md
-a----   Wed 29 Jun 2022     18:29           4161 Remove-TeamsVoiceRoutingChain.md
-a----   Wed 29 Jun 2022     18:29           3280 Remove-TenantDialPlanNormalizationRule.md
-a----   Wed 29 Jun 2022     18:29           3567 Restore-TeamsEV.md
-a----   Wed 29 Jun 2022     18:29           4978 Set-AzureAdUserLicenseServicePlan.md
-a----   Wed 29 Jun 2022     18:29          16481 Set-TeamsCallQueue.md
-a----   Wed 29 Jun 2022     18:29           8074 Set-TeamsCommonAreaPhone.md
-a----   Wed 29 Jun 2022     18:29           4922 Set-TeamsPhoneNumber.md
-a----   Wed 29 Jun 2022     18:29           8500 Set-TeamsResourceAccount.md
-a----   Wed 29 Jun 2022     18:29           6775 Set-TeamsUserEmergencyConfiguration.md
-a----   Wed 29 Jun 2022     18:29           8640 Set-TeamsUserLicense.md
-a----   Wed 29 Jun 2022     18:29           9108 Set-TeamsUserVoiceConfig.md
-a----   Wed 29 Jun 2022     18:29           1588 Test-AzureADConnection.md
-a----   Wed 29 Jun 2022     18:29           2118 Test-AzureAdGroup.md
-a----   Wed 29 Jun 2022     18:29           2309 Test-AzureAdLicenseContainsServicePlan.md
-a----   Wed 29 Jun 2022     18:29           2182 Test-AzureAdUser.md
-a----   Wed 29 Jun 2022     18:29           1680 Test-ExchangeOnlineConnection.md
-a----   Wed 29 Jun 2022     18:29           3648 Test-TeamsUserLicense.md
-a----   Wed 29 Jun 2022     18:29           5902 Test-TeamsUserVoiceConfig.md
-a----   Wed 29 Jun 2022     18:29           7704 Write-BetterProgress.md
-a----   Wed 29 Jun 2022     18:29           3052 Write-TFErrorLog.md

Actual behavior

Import-Module $ModuleDir\TeamsFunctions.psd1
$ModuleLoaded = Get-Module TeamsFunctions
if (-not $ModuleLoaded) { throw "Module '$Module' not found" }
$DocsFolder = '.\docs\'

New-MarkdownHelp -Module $ModuleLoaded.Name -OutputFolder $DocsFolder -Force -AlphabeticParamsOrder:$false

Updating Documentation & ReadMe
VERBOSE: Updating Component Status in ReadMe
VERBOSE: Creating MarkDownHelp with PlatyPs
    Directory: D:\a\TeamsFunctions\TeamsFunctions\packages\module\docs
Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
-a---           6/29/2022  6:24 PM           1704 Assert-AzureADConnection.md
-a---           6/29/2022  6:24 PM           1767 Assert-MicrosoftTeamsConnection.md
-a---           6/29/2022  6:24 PM           2692 Assert-Module.md
-a---           6/29/2022  6:24 PM           3305 Assert-TeamsCallableEntity.md
-a---           6/29/2022  6:24 PM           5193 Assert-TeamsUserVoiceConfig.md
-a---           6/29/2022  6:24 PM           2291 Backup-TeamsEV.md
-a---           6/29/2022  6:24 PM           2400 Backup-TeamsTenant.md
-a---           6/29/2022  6:24 PM           4804 Connect-Me.md
-a---           6/29/2022  6:24 PM           4553 Disable-AzureAdAdminRole.md
-a---           6/29/2022  6:23 PM           1642 Disable-MyAzureAdAdminRole.md
-a---           6/29/2022  6:24 PM           2649 Disconnect-Me.md
-a---           6/29/2022  6:24 PM           6109 Enable-AzureAdAdminRole.md
-a---           6/29/2022  6:23 PM           1636 Enable-MyAzureAdAdminRole.md
-a---           6/29/2022  6:24 PM           3985 Enable-TeamsUserForEnterpriseVoice.md
-a---           6/29/2022  6:24 PM           2150 Find-AzureAdGroup.md
Get-Help: Unable to find type [Microsoft.Open.AzureAD.Model.User].

Error details

the offending Function has defined the Type that isn't found as the OutputType as I am querying AzureAdUsers and jugging them out unaltered:

function Find-AzureAdUser {
  <#
  .SYNOPSIS
    Returns User Objects from Azure AD based on a search string or UserPrincipalName
    [..]
  #>

  [CmdletBinding()]
  [OutputType([Microsoft.Open.AzureAD.Model.User])]
  [..]
}

I don't want to switch to v2 yet as it changes the output quite a bit (and I lose some functionality that I otherwise do not

Environment data

My machine:

❯ Get-Module Platyps -ListAvailable

    Directory: C:\Users\David\Documents\WindowsPowerShell\Modules

ModuleType Version    Name                                ExportedCommands
---------- -------    ----                                ----------------
Binary     2.0.0      platyPS                             {New-MarkdownHelp, Get-MarkdownMetadata}
Script     0.14.1     platyPS                             {New-MarkdownHelp, Get-MarkdownMetadata, New-ExternalHelp, New-YamlHelp...}

❯ Get-Module Platyps  

ModuleType Version    Name                                ExportedCommands
---------- -------    ----                                ----------------
Script     0.14.1     platyps                             {Get-HelpPreview, Get-MarkdownMetadata, Merge-MarkdownHelp, New-ExternalHelp...}

❯ $PSversionTable

Name                           Value
----                           -----
PSVersion                      5.1.22621.1
PSEdition                      Desktop
PSCompatibleVersions           {1.0, 2.0, 3.0, 4.0...}
BuildVersion                   10.0.22621.1
CLRVersion                     4.0.30319.42000
WSManStackVersion              3.0
PSRemotingProtocolVersion      2.3
SerializationVersion           1.1.0.1

build runner
```powershell
# this runs in PWSH
Preparing Environment
VERBOSE: Installing Package Provider
VERBOSE: Installing PowerShell Modules
Installing Pester
Installing posh-git
Installing platyPS
Installing InvokeBuild
Installing BuildHelpers
Installing MicrosoftTeams
ModuleType Version    PreRelease Name                                ExportedCommands
---------- -------    ---------- ----                                ----------------
Script     2.0.16                BuildHelpers                        {Add-TestResultToAppveyor, Export-Metadata, Find-…
Binary     7.0.0.0               CimCmdlets                          {Get-CimAssociatedInstance, Get-CimClass, Get-Cim…
Script     5.9.10                InvokeBuild                         {Build-Checkpoint, Build-Parallel, Invoke-Build}
Manifest   7.0.0.0               Microsoft.PowerShell.Management     {Add-Content, Clear-Content, Clear-Item, Clear-It…
Manifest   7.0.0.0               Microsoft.PowerShell.Utility        {Add-Member, Add-Type, Clear-Variable, Compare-Ob…
Script     4.4.1                 MicrosoftTeams                      {Add-TeamChannelUser, Add-TeamUser, Connect-Micro…
Script     1.4.7                 PackageManagement                   {Find-Package, Find-PackageProvider, Get-Package,…
Script     5.3.3                 Pester                              {Add-ShouldOperator, AfterAll, AfterEach, Assert-…
Script     0.14.1                platyPS                             {Get-HelpPreview, Get-MarkdownMetadata, Merge-Mar…
Script     1.1.0                 posh-git                            {Add-PoshGitToProfile, Expand-GitCommand, Format-…
Script     2.2.5                 PowerShellGet                       {Find-Command, Find-DscResource, Find-Module, Fin…

Didn't run $PSversionTable in the runner, but it is running PWSH:

Current runner version: '2.294.0'
Operating System
  Microsoft Windows Server 2022
  10.0.20348
  Datacenter
Virtual Environment
  Environment: windows-2022
  Version: 20220626.1
  Included Software: https://github.com/actions/virtual-environments/blob/win22/20220626.1/images/win/Windows2022-Readme.md
  Image Release: https://github.com/actions/virtual-environments/releases/tag/win22%2F20220626.1
Virtual Environment Provisioner
  1.0.0.0-main-20220531-1

just to be safe, I also tried on PWSH on my machine, works OK

❯ Get-Module Platyps -ListAvailable

    Directory: C:\Users\David\Documents\PowerShell\Modules

ModuleType Version    PreRelease Name                                PSEdition ExportedCommands
---------- -------    ---------- ----                                --------- ----------------
Script     0.14.2                platyPS                             Desk      {New-MarkdownHelp, Get-MarkdownMetadata…

❯ Get-Module Platyps

ModuleType Version    PreRelease Name                                ExportedCommands
---------- -------    ---------- ----                                ----------------
Script     0.14.2                platyPS                             {Get-HelpPreview, Get-MarkdownMetadata, Merge-Mar…

❯ $Psversiontable

Name                           Value
----                           -----
PSVersion                      7.2.5
PSEdition                      Core
GitCommitId                    7.2.5
OS                             Microsoft Windows 10.0.22621
Platform                       Win32NT
PSCompatibleVersions           {1.0, 2.0, 3.0, 4.0…}
PSRemotingProtocolVersion      2.3
SerializationVersion           1.1.0.1
WSManStackVersion              3.0

I also tried 0.14.1 and 0.14.2, but it didn't make a difference... in fact, I think I just found a different issue with 0.14.2...



### Visuals

![image](https://user-images.githubusercontent.com/44290340/176512915-e6d0e196-3a15-47d5-8d52-0632fb4e0565.png)

martin9700 commented 2 years ago

I'm encountering the same issue. The New-MarkdownHelp is consistently failing on this:

[CmdletBinding()] param ( [Parameter(Mandatory = $true)] [Microsoft.ActiveDirectory.Management.ADOrganizationalUnit]$Ou )

When running in an interactive PowerShell window, this can be suppressed using -ErrorAction SilentlyContinue, but when run from Jenkins it is a full stop error regardless.

DEberhardt commented 2 years ago

checked the v2-preview1 in the runner - same result.

I will continue to update my docs manually for now, with v0.14.x

I would like to help you guys get to the bottom of this issue, but I don't know where to start looking in the code, sorry.

DEberhardt commented 2 years ago

HA! Turns out, I am suffering an ISO/OSI 8 error^^ If you don't install and import the Module providing the Type, New-MarkdownHelp will complain about the type not being present.

Going through the only differences between my environment and the runner environment, I could find that I had removed the pre-requisite (Module AzureAd in my case) because of a clash with the AzureAdPreview Module (Assembly with this name already loaded error).

Leaving this one open for @martin9700 - maybe this helps you resolve your issue as well. :smile:

martin9700 commented 2 years ago

Yah, that works for me too. Unfortunately mine is for a module creation pipeline and we often use implied module loads (lazy, I know). So now we're going to have to require people to load any dependencies. It's just a change people might not love, but I can live with that.

One question I do have: Why is New-MarkdownHelp needing to load these types in the first place? Is it completely necessary when just creating markdown from the help?

sdwheeler commented 2 years ago

This is expected behavior.

PowerShell / platyPS