Enable Get-FabricWorkspaceUser to accept pipeline input

CHANGELOG.md

@@ -6,9 +6,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
+- added unit tests for `Get-FabricWorkspaceUser` function to ensure it works correctly with multiple workspaces both in the pipeline and passed to a parameter.
+- Added unit tests for Aliases for `Get-FabricWorkspaceUser` function to ensure backward compatibility.
 - Added credits for authors to all functions and Unit tests to verify the existence of such tags #89
 
 ### Changed
+- Updated `Get-FabricWorkspaceUser` to support pipeline input for `WorkspaceId` and `WorkspaceName` parameters.
+- Renamed `Get-FabricWorkspaceUsers` to match the singular form
 - Get-FabricSqlDatabase accepts Workspace as a pipeline, handles errors correctly and can filter by name (#117).
 
 ### Fixed

source/Public/Workspace/Get-FabricWorkspaceUser.ps1

@@ -0,0 +1,107 @@
+function Get-FabricWorkspaceUser
+{
+    <#
+.SYNOPSIS
+Retrieves the user(s) of a workspace.
+
+.DESCRIPTION
+The Get-FabricWorkspaceUser function retrieves the details of the users of a workspace.
+
+.PARAMETER WorkspaceId
+The ID of the workspace. This is a mandatory parameter if Workspace is not provided.
+
+.PARAMETER Workspace
+The workspace object. This normally comes from the Get-FabricWorkspace cmdlet. This is a mandatory parameter if WorkspaceId is not provided.
+
+.EXAMPLE
+Get-FabricWorkspaceUser -WorkspaceId '12345678-1234-1234-1234-123456789012
+
+This example retrieves the users of a workspace of the workspace with the ID '12345678-1234-1234-1234-123456789012'.
+
+.EXAMPLE
+$workspace = Get-FabricWorkspace -WorkspaceName 'prod-workspace'
+$workspace | Get-FabricWorkspaceUser
+
+This example retrieves the users of the prod-workspace workspace by piping the object.
+
+.EXAMPLE
+Get-FabricWorkspaceUser -Workspace (Get-FabricWorkspace -WorkspaceName 'prod-workspace')
+
+This example retrieves the users of the prod-workspace workspace by piping the object.
+
+.EXAMPLE
+Get-FabricWorkspace| Get-FabricWorkspaceUser
+
+This example retrieves the users of all of the workspaces. IMPORTANT: This will not return the workspace name or ID at present.
+
+.EXAMPLE
+Get-FabricWorkspace| Foreach-Object {
+Get-FabricWorkspaceUser -WorkspaceId $_.Id | Select-Object @{Name='WorkspaceName';Expression={$_.displayName;}}, *
+}
+
+This example retrieves the users of all of the workspaces. It will also add the workspace name to the output.
+
+.NOTES
+It supports multiple aliases for backward compatibility.
+The function defines parameters for the workspace ID and workspace object. If the parameter set name is 'WorkspaceId', it retrieves the workspace object. It then makes a GET request to the PowerBI API to retrieve the users of the workspace and returns the 'value' property of the response, which contains the users.
+
+Author: Ioana Bouariu
+
+    #>
+
+    # This function retrieves the users of a workspace.
+    # Define aliases for the function for flexibility.
+    [Alias("Get-FabWorkspaceUsers")]
+    [Alias("Get-FabricWorkspaceUsers")]
+
+    # Define parameters for the workspace ID and workspace object.
+    param(
+        [Parameter(Mandatory = $true, ParameterSetName = 'WorkspaceId')]
+        [string]$WorkspaceId,
+
+        [Parameter(Mandatory = $true, ParameterSetName = 'WorkspaceObject', ValueFromPipeline = $true )]
+        [object[]]
+        $Workspace
+    )
+
+    begin
+    {
+        Confirm-TokenState
+        # If the parameter set name is 'WorkspaceId', return the workspace object so that it can be used in the process block.
+        if ($PSCmdlet.ParameterSetName -eq 'WorkspaceId')
+        {
+            $Workspace = Get-FabricWorkspace -WorkspaceId $WorkspaceId
+        }
+        $returnValue = @()
+    }
+
+    process
+    {
+
+        foreach ($space in $Workspace)
+        {
+
+            $Uri = "groups/{0}/users" -f $space.id
+
+            # Make a GET request to the PowerBI API to retrieve the users of the workspace.
+            # The function returns the 'value' property of the response, which contains the users.
+
+            $response = (Invoke-FabricRestMethod -Method get -PowerBIApi -Uri $Uri).value
+            if ($response)
+            {
+
+                # Add the users to the return value.
+                $returnValue += $response
+            }
+        }
+    }
+    end
+    {
+        # We should not be using the return keyword.
+        # This will enable future improvements such as adding additional value to the returned object such as the workspace name and better column headings
+        # It will also allow for future improvements such as filtering the returned object.
+        # Uses the code as defined https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_functions_advanced_methods?view=powershell-7.5&viewFallbackFrom=powershell-7.2#input-processing-methods
+        # Return the users of the workspace.
+        $returnValue
+    }
+}

tests/Unit/Get-FabricWorkspaceUser.Tests.ps1

@@ -0,0 +1,107 @@
+#Requires -Module @{ ModuleName="Pester"; ModuleVersion="5.0"}
+param(
+    $ModuleName = "FabricTools",
+    $expectedParams = @(
+        "WorkspaceId"
+        "Workspace"
+        "Verbose"
+        "Debug"
+        "ErrorAction"
+        "WarningAction"
+        "InformationAction"
+        "ProgressAction"
+        "ErrorVariable"
+        "WarningVariable"
+        "InformationVariable"
+        "OutVariable"
+        "OutBuffer"
+        "PipelineVariable"
+
+    )
+)
+
+Describe "Get-FabricWorkspaceUser" -Tag "UnitTests" {
+
+    BeforeDiscovery {
+        $command = Get-Command -Name Get-FabricWorkspaceUser
+        $expected = $expectedParams
+    }
+
+    Context "Parameter validation" {
+        BeforeAll {
+            $command = Get-Command -Name Get-FabricWorkspaceUser
+            $expected = $expectedParams
+        }
+
+        It "Has parameter: <_>" -ForEach $expected {
+            $command | Should -HaveParameter $PSItem
+        }
+
+        It "Should have exactly the number of expected parameters $($expected.Count)" {
+            $hasparms = $command.Parameters.Values.Name
+            #$hasparms.Count | Should -BeExactly $expected.Count
+            Compare-Object -ReferenceObject $expected -DifferenceObject $hasparms | Should -BeNullOrEmpty
+        }
+    }
+
+    Context "Alias validation" {
+        $testCases = @('Get-FabWorkspaceUsers', 'Get-FabricWorkspaceUsers')
+
+        It "Should have the alias <_>" -TestCases $TestCases {
+            $Alias = Get-Alias -Name $_ -ErrorAction SilentlyContinue
+            $Alias | Should -Not -BeNullOrEmpty
+            $Alias.ResolvedCommand.Name | Should -Be  'Get-FabricWorkspaceUser'
+        }
+    }
+
+    Context "Multiple Workspaces" {
+
+        BeforeEach {
+
+            function Confirm-TokenState {}
+            Mock Confirm-TokenState {}
+
+            Mock Get-FabricWorkspace {
+                return @(
+                    @{
+                        displayName = 'prod-workspace'
+                        # until the guid datatype is added
+                        Id          = [guid]::NewGuid().Guid.ToString()
+                    }, @{
+                        displayName = "test-workspace"
+                        # until the guid datatype is added
+                        Id          = [guid]::NewGuid().Guid.ToString()
+                    }
+                )
+            }
+            Mock Invoke-FabricRestMethod {
+                return @{
+                    value = @(
+                        @{
+                            emailAddress         = 'name@domain.com'
+                            groupUserAccessRight = 'Admin'
+                            displayName          = 'Fabric'
+                            identifier           = 'name@domain.com'
+                            principalType        = 'User'
+                        }, @{
+                            emailAddress         = 'viewer@domain.com'
+                            groupUserAccessRight = 'Viewer'
+                            displayName          = 'Fabric viewer'
+                            identifier           = 'viewer@domain.com'
+                            principalType        = 'User'
+                        }
+                    )
+                }
+            }
+        }
+
+        It "Should return users for multiple workspaces passed to the Workspace parameter" {
+            {Get-FabricWorkspaceUser -Workspace (Get-FabricWorkspace) }| Should -Not -BeNullOrEmpty
+        }
+
+        It "Should return users for multiple workspaces passed to the Workspace parameter from the pipeline" {
+            { Get-FabricWorkspace | Get-FabricWorkspaceUser
+            } | Should -Not -BeNullOrEmpty
+        }
+    }
+}