From 3201e762033e2934fafef01ad27900971aeeca9b Mon Sep 17 00:00:00 2001 From: Steve Mutungi <132555836+SteveMutungi254@users.noreply.github.com> Date: Tue, 26 Nov 2024 10:20:24 +0300 Subject: [PATCH 1/9] Adding beta code --- .../Get-EntraDeletedDevice.ps1 | 113 ++++++++++++++++++ .../Get-EntraBetaDeletedDevice.ps1 | 113 ++++++++++++++++++ 2 files changed, 226 insertions(+) create mode 100644 module/Entra/AdditionalFunctions/Get-EntraDeletedDevice.ps1 create mode 100644 module/EntraBeta/AdditionalFunctions/Get-EntraBetaDeletedDevice.ps1 diff --git a/module/Entra/AdditionalFunctions/Get-EntraDeletedDevice.ps1 b/module/Entra/AdditionalFunctions/Get-EntraDeletedDevice.ps1 new file mode 100644 index 0000000000..624ace4bc0 --- /dev/null +++ b/module/Entra/AdditionalFunctions/Get-EntraDeletedDevice.ps1 @@ -0,0 +1,113 @@ +# ------------------------------------------------------------------------------ +# Copyright (c) Microsoft Corporation. All Rights Reserved. +# Licensed under the MIT License. See License in the project root for license information. +# ------------------------------------------------------------------------------ + +function Get-EntraDeletedServicePrincipal { + [CmdletBinding(DefaultParameterSetName = 'GetQuery')] + param ( + [Parameter(ParameterSetName = "GetQuery", ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, HelpMessage = "Filter to apply to the query.")] + [System.String] $Filter, + + [Parameter(ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, HelpMessage = "Retrieve all deleted devices.")] + [switch] $All, + + [Parameter(ParameterSetName = "GetVague", ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, HelpMessage = "Search for devices.")] + [System.String] $SearchString, + + [Alias('Id')] + [Parameter(ParameterSetName = "GetById", Mandatory = $true, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, HelpMessage = "Device Object ID to retrieve.")] + [System.String] $DeviceObjectId, + + [Alias('Limit')] + [Parameter(ParameterSetName = "GetQuery", ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, HelpMessage = "Maximum number of results to return.")] + [System.Nullable`1[System.Int32]] $Top, + + [Alias('Select')] + [Parameter(Mandatory = $false, ValueFromPipeline = $false, ValueFromPipelineByPropertyName = $true, HelpMessage = "Properties to include in the results.")] + [System.String[]] $Property + ) + + PROCESS { + $params = @{} + $customHeaders = New-EntraCustomHeaders -Command $MyInvocation.MyCommand + $keysChanged = @{ SearchString = "Filter" } + + if ($null -ne $PSBoundParameters["ErrorAction"]) { + $params["ErrorAction"] = $PSBoundParameters["ErrorAction"] + } + if ($null -ne $PSBoundParameters["DeviceObjectId"]) { + $params["DirectoryObjectId"] = $PSBoundParameters["DeviceObjectId"] + } + if ($PSBoundParameters.ContainsKey("Verbose")) { + $params["Verbose"] = $PSBoundParameters["Verbose"] + } + if ($null -ne $PSBoundParameters["OutVariable"]) { + $params["OutVariable"] = $PSBoundParameters["OutVariable"] + } + if ($null -ne $PSBoundParameters["InformationAction"]) { + $params["InformationAction"] = $PSBoundParameters["InformationAction"] + } + if ($null -ne $PSBoundParameters["WarningVariable"]) { + $params["WarningVariable"] = $PSBoundParameters["WarningVariable"] + } + if ($PSBoundParameters.ContainsKey("Debug")) { + $params["Debug"] = $PSBoundParameters["Debug"] + } + if ($null -ne $PSBoundParameters["PipelineVariable"]) { + $params["PipelineVariable"] = $PSBoundParameters["PipelineVariable"] + } + if ($null -ne $PSBoundParameters["SearchString"]) { + $TmpValue = $PSBoundParameters["SearchString"] + $Value = "displayName eq '$TmpValue' or startsWith(displayName,'$TmpValue')" + $params["Filter"] = $Value + } + if ($null -ne $PSBoundParameters["ErrorVariable"]) { + $params["ErrorVariable"] = $PSBoundParameters["ErrorVariable"] + } + if ($null -ne $PSBoundParameters["Top"]) { + $params["Top"] = $PSBoundParameters["Top"] + } + if ($null -ne $PSBoundParameters["OutBuffer"]) { + $params["OutBuffer"] = $PSBoundParameters["OutBuffer"] + } + if ($null -ne $PSBoundParameters["All"]) { + if ($PSBoundParameters["All"]) { + $params["All"] = $PSBoundParameters["All"] + } + } + if ($null -ne $PSBoundParameters["WarningAction"]) { + $params["WarningAction"] = $PSBoundParameters["WarningAction"] + } + if ($null -ne $PSBoundParameters["Filter"]) { + $TmpValue = $PSBoundParameters["Filter"] + foreach ($i in $keysChanged.GetEnumerator()) { + $TmpValue = $TmpValue.Replace($i.Key, $i.Value) + } + $Value = $TmpValue + $params["Filter"] = $Value + } + if ($null -ne $PSBoundParameters["InformationVariable"]) { + $params["InformationVariable"] = $PSBoundParameters["InformationVariable"] + } + if ($null -ne $PSBoundParameters["Property"]) { + $params["Property"] = $PSBoundParameters["Property"] + } + + # Debug logging for transformations + Write-Debug "============================ TRANSFORMATIONS ============================" + $params.Keys | ForEach-Object { "$_ : $($params[$_])" } | Write-Debug + Write-Debug "=========================================================================`n" + + try { + # Make the API call + $response = Get-MgDirectoryDeletedItemAsDevice @params -Headers $customHeaders + + return $response + } + catch { + # Handle any errors that occur during the API call + Write-Error "An error occurred while retrieving the deleted devices: $_" + } + } +} \ No newline at end of file diff --git a/module/EntraBeta/AdditionalFunctions/Get-EntraBetaDeletedDevice.ps1 b/module/EntraBeta/AdditionalFunctions/Get-EntraBetaDeletedDevice.ps1 new file mode 100644 index 0000000000..80131d76c9 --- /dev/null +++ b/module/EntraBeta/AdditionalFunctions/Get-EntraBetaDeletedDevice.ps1 @@ -0,0 +1,113 @@ +# ------------------------------------------------------------------------------ +# Copyright (c) Microsoft Corporation. All Rights Reserved. +# Licensed under the MIT License. See License in the project root for license information. +# ------------------------------------------------------------------------------ + +function Get-EntraBetaDeletedDevice { + [CmdletBinding(DefaultParameterSetName = 'GetQuery')] + param ( + [Parameter(ParameterSetName = "GetQuery", ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, HelpMessage = "Filter to apply to the query.")] + [System.String] $Filter, + + [Parameter(ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, HelpMessage = "Retrieve all deleted devices.")] + [switch] $All, + + [Parameter(ParameterSetName = "GetVague", ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, HelpMessage = "Search for devices.")] + [System.String] $SearchString, + + [Alias('Id')] + [Parameter(ParameterSetName = "GetById", Mandatory = $true, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, HelpMessage = "Device Object ID to retrieve.")] + [System.String] $DeviceObjectId, + + [Alias('Limit')] + [Parameter(ParameterSetName = "GetQuery", ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, HelpMessage = "Maximum number of results to return.")] + [System.Nullable`1[System.Int32]] $Top, + + [Alias('Select')] + [Parameter(Mandatory = $false, ValueFromPipeline = $false, ValueFromPipelineByPropertyName = $true, HelpMessage = "Properties to include in the results.")] + [System.String[]] $Property + ) + + PROCESS { + $params = @{} + $customHeaders = New-EntraBetaCustomHeaders -Command $MyInvocation.MyCommand + $keysChanged = @{ SearchString = "Filter" } + + if ($null -ne $PSBoundParameters["ErrorAction"]) { + $params["ErrorAction"] = $PSBoundParameters["ErrorAction"] + } + if ($null -ne $PSBoundParameters["DeviceObjectId"]) { + $params["DirectoryObjectId"] = $PSBoundParameters["DeviceObjectId"] + } + if ($PSBoundParameters.ContainsKey("Verbose")) { + $params["Verbose"] = $PSBoundParameters["Verbose"] + } + if ($null -ne $PSBoundParameters["OutVariable"]) { + $params["OutVariable"] = $PSBoundParameters["OutVariable"] + } + if ($null -ne $PSBoundParameters["InformationAction"]) { + $params["InformationAction"] = $PSBoundParameters["InformationAction"] + } + if ($null -ne $PSBoundParameters["WarningVariable"]) { + $params["WarningVariable"] = $PSBoundParameters["WarningVariable"] + } + if ($PSBoundParameters.ContainsKey("Debug")) { + $params["Debug"] = $PSBoundParameters["Debug"] + } + if ($null -ne $PSBoundParameters["PipelineVariable"]) { + $params["PipelineVariable"] = $PSBoundParameters["PipelineVariable"] + } + if ($null -ne $PSBoundParameters["SearchString"]) { + $TmpValue = $PSBoundParameters["SearchString"] + $Value = "displayName eq '$TmpValue' or startsWith(displayName,'$TmpValue')" + $params["Filter"] = $Value + } + if ($null -ne $PSBoundParameters["ErrorVariable"]) { + $params["ErrorVariable"] = $PSBoundParameters["ErrorVariable"] + } + if ($null -ne $PSBoundParameters["Top"]) { + $params["Top"] = $PSBoundParameters["Top"] + } + if ($null -ne $PSBoundParameters["OutBuffer"]) { + $params["OutBuffer"] = $PSBoundParameters["OutBuffer"] + } + if ($null -ne $PSBoundParameters["All"]) { + if ($PSBoundParameters["All"]) { + $params["All"] = $PSBoundParameters["All"] + } + } + if ($null -ne $PSBoundParameters["WarningAction"]) { + $params["WarningAction"] = $PSBoundParameters["WarningAction"] + } + if ($null -ne $PSBoundParameters["Filter"]) { + $TmpValue = $PSBoundParameters["Filter"] + foreach ($i in $keysChanged.GetEnumerator()) { + $TmpValue = $TmpValue.Replace($i.Key, $i.Value) + } + $Value = $TmpValue + $params["Filter"] = $Value + } + if ($null -ne $PSBoundParameters["InformationVariable"]) { + $params["InformationVariable"] = $PSBoundParameters["InformationVariable"] + } + if ($null -ne $PSBoundParameters["Property"]) { + $params["Property"] = $PSBoundParameters["Property"] + } + + # Debug logging for transformations + Write-Debug "============================ TRANSFORMATIONS ============================" + $params.Keys | ForEach-Object { "$_ : $($params[$_])" } | Write-Debug + Write-Debug "=========================================================================`n" + + try { + # Make the API call + $response = Get-MgBetaDirectoryDeletedItemAsDevice @params -Headers $customHeaders + + return $response + } + catch { + # Handle any errors that occur during the API call + Write-Error "An error occurred while retrieving the deleted devices: $_" + } + } +} \ No newline at end of file From ffec0d29b4dfa2fe32a354f27f170ed03098ed8f Mon Sep 17 00:00:00 2001 From: Steve Mutungi <132555836+SteveMutungi254@users.noreply.github.com> Date: Tue, 26 Nov 2024 10:23:42 +0300 Subject: [PATCH 2/9] Renaming function name --- module/Entra/AdditionalFunctions/Get-EntraDeletedDevice.ps1 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/module/Entra/AdditionalFunctions/Get-EntraDeletedDevice.ps1 b/module/Entra/AdditionalFunctions/Get-EntraDeletedDevice.ps1 index 624ace4bc0..319ecb2ae9 100644 --- a/module/Entra/AdditionalFunctions/Get-EntraDeletedDevice.ps1 +++ b/module/Entra/AdditionalFunctions/Get-EntraDeletedDevice.ps1 @@ -3,7 +3,7 @@ # Licensed under the MIT License. See License in the project root for license information. # ------------------------------------------------------------------------------ -function Get-EntraDeletedServicePrincipal { +function Get-EntraDeletedDevice { [CmdletBinding(DefaultParameterSetName = 'GetQuery')] param ( [Parameter(ParameterSetName = "GetQuery", ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, HelpMessage = "Filter to apply to the query.")] From 0cc861062f4d557ce7301626930e623084266b2e Mon Sep 17 00:00:00 2001 From: Steve Mutungi <132555836+SteveMutungi254@users.noreply.github.com> Date: Tue, 26 Nov 2024 10:31:54 +0300 Subject: [PATCH 3/9] Adding page size --- module/Entra/AdditionalFunctions/Get-EntraDeletedDevice.ps1 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/module/Entra/AdditionalFunctions/Get-EntraDeletedDevice.ps1 b/module/Entra/AdditionalFunctions/Get-EntraDeletedDevice.ps1 index 319ecb2ae9..e2429d387e 100644 --- a/module/Entra/AdditionalFunctions/Get-EntraDeletedDevice.ps1 +++ b/module/Entra/AdditionalFunctions/Get-EntraDeletedDevice.ps1 @@ -101,7 +101,7 @@ function Get-EntraDeletedDevice { try { # Make the API call - $response = Get-MgDirectoryDeletedItemAsDevice @params -Headers $customHeaders + $response = Get-MgDirectoryDeletedItemAsDevice -PageSize 999 @params -Headers $customHeaders return $response } From 9868408292aa58842fb6fb9e681f13a2bbdf46e1 Mon Sep 17 00:00:00 2001 From: Steve Mutungi <132555836+SteveMutungi254@users.noreply.github.com> Date: Tue, 26 Nov 2024 10:33:41 +0300 Subject: [PATCH 4/9] Adding page size --- .../Entra/AdditionalFunctions/Get-EntraDeletedDevice.ps1 | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/module/Entra/AdditionalFunctions/Get-EntraDeletedDevice.ps1 b/module/Entra/AdditionalFunctions/Get-EntraDeletedDevice.ps1 index e2429d387e..7e03a69209 100644 --- a/module/Entra/AdditionalFunctions/Get-EntraDeletedDevice.ps1 +++ b/module/Entra/AdditionalFunctions/Get-EntraDeletedDevice.ps1 @@ -100,8 +100,12 @@ function Get-EntraDeletedDevice { Write-Debug "=========================================================================`n" try { - # Make the API call - $response = Get-MgDirectoryDeletedItemAsDevice -PageSize 999 @params -Headers $customHeaders + # Make the API call with -PageSize 999 if -All is used + if ($PSBoundParameters.ContainsKey("All") -and $All) { + $response = Get-MgDirectoryDeletedItemAsDevice @params -PageSize 999 -Headers $customHeaders + } else { + $response = Get-MgDirectoryDeletedItemAsDevice @params -Headers $customHeaders + } return $response } From 6d737234b68cf15fa11a922646873c7f6d67e632 Mon Sep 17 00:00:00 2001 From: Steve Mutungi <132555836+SteveMutungi254@users.noreply.github.com> Date: Tue, 26 Nov 2024 10:34:06 +0300 Subject: [PATCH 5/9] Adding formatting --- module/Entra/AdditionalFunctions/Get-EntraDeletedDevice.ps1 | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/module/Entra/AdditionalFunctions/Get-EntraDeletedDevice.ps1 b/module/Entra/AdditionalFunctions/Get-EntraDeletedDevice.ps1 index 7e03a69209..ed091924be 100644 --- a/module/Entra/AdditionalFunctions/Get-EntraDeletedDevice.ps1 +++ b/module/Entra/AdditionalFunctions/Get-EntraDeletedDevice.ps1 @@ -103,7 +103,8 @@ function Get-EntraDeletedDevice { # Make the API call with -PageSize 999 if -All is used if ($PSBoundParameters.ContainsKey("All") -and $All) { $response = Get-MgDirectoryDeletedItemAsDevice @params -PageSize 999 -Headers $customHeaders - } else { + } + else { $response = Get-MgDirectoryDeletedItemAsDevice @params -Headers $customHeaders } From ebdad86c438db4c3fe6d41a9f73b18b6fd060468 Mon Sep 17 00:00:00 2001 From: Steve Mutungi <132555836+SteveMutungi254@users.noreply.github.com> Date: Tue, 26 Nov 2024 10:38:39 +0300 Subject: [PATCH 6/9] Adding pagesize option --- .../AdditionalFunctions/Get-EntraBetaDeletedDevice.ps1 | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/module/EntraBeta/AdditionalFunctions/Get-EntraBetaDeletedDevice.ps1 b/module/EntraBeta/AdditionalFunctions/Get-EntraBetaDeletedDevice.ps1 index 80131d76c9..5c57b40dbf 100644 --- a/module/EntraBeta/AdditionalFunctions/Get-EntraBetaDeletedDevice.ps1 +++ b/module/EntraBeta/AdditionalFunctions/Get-EntraBetaDeletedDevice.ps1 @@ -100,8 +100,13 @@ function Get-EntraBetaDeletedDevice { Write-Debug "=========================================================================`n" try { - # Make the API call - $response = Get-MgBetaDirectoryDeletedItemAsDevice @params -Headers $customHeaders + # Make the API call with -PageSize 999 if -All is used + if ($PSBoundParameters.ContainsKey("All") -and $All) { + $response = Get-MgBetaDirectoryDeletedItemAsDevice @params -PageSize 999 -Headers $customHeaders + } + else { + $response = Get-MgBetaDirectoryDeletedItemAsDevice @params -Headers $customHeaders + } return $response } From ccf8b7afc77de2c3030317d5196681ee07f488eb Mon Sep 17 00:00:00 2001 From: Steve Mutungi <132555836+SteveMutungi254@users.noreply.github.com> Date: Tue, 26 Nov 2024 10:55:18 +0300 Subject: [PATCH 7/9] Add test --- .../Entra/Get-EntraDeletedDevice.Tests.ps1 | 93 +++++++++++++++++++ 1 file changed, 93 insertions(+) create mode 100644 test/module/Entra/Get-EntraDeletedDevice.Tests.ps1 diff --git a/test/module/Entra/Get-EntraDeletedDevice.Tests.ps1 b/test/module/Entra/Get-EntraDeletedDevice.Tests.ps1 new file mode 100644 index 0000000000..57e6e8583e --- /dev/null +++ b/test/module/Entra/Get-EntraDeletedDevice.Tests.ps1 @@ -0,0 +1,93 @@ +# ------------------------------------------------------------------------------ +# Copyright (c) Microsoft Corporation. All Rights Reserved. +# Licensed under the MIT License. See License in the project root for license information. +# ------------------------------------------------------------------------------ + +BeforeAll { + if ((Get-Module -Name Microsoft.Graph.Entra) -eq $null) { + Import-Module Microsoft.Graph.Entra + } + Import-Module (Join-Path $psscriptroot "..\Common-Functions.ps1") -Force + + $scriptblock = { + return @( + [PSCustomObject]@{ + "DisplayName" = "iPhone 12 Pro" + "Id" = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb" + "DeviceCategory" = "Test" + "AccountEnabled" = "True" + "DeletedDateTime" = "10/28/2024 4:16:02 PM" + "DeviceId" = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb" + } + ) + } + + Mock -CommandName Get-MgDirectoryDeletedItemAsDevice -MockWith $scriptblock -ModuleName Microsoft.Graph.Entra +} + +Describe "Get-EntraDeletedDevice" { + Context "Test for Get-EntraDeletedDevice" { + It "Should return all devices" { + $result = Get-EntraDeletedDevice + $result | Should -Not -BeNullOrEmpty + Should -Invoke -CommandName Get-MgDirectoryDeletedItemAsDevice -ModuleName Microsoft.Graph.Entra -Times 1 + } + + It "Should return specific device by searchstring" { + $result = Get-EntraDeletedDevice -SearchString 'iPhone 12 Pro' + $result | Should -Not -BeNullOrEmpty + $result.DisplayName | Should -Be 'iPhone 12 Pro' + Should -Invoke -CommandName Get-MgDirectoryDeletedItemAsDevice -ModuleName Microsoft.Graph.Entra -Times 1 + } + + It "Should return specific device by filter" { + $result = Get-EntraDeletedDevice -Filter "DisplayName -eq 'iPhone 12 Pro'" + $result | Should -Not -BeNullOrEmpty + $result.DisplayName | Should -Be 'iPhone 12 Pro' + Should -Invoke -CommandName Get-MgDirectoryDeletedItemAsDevice -ModuleName Microsoft.Graph.Entra -Times 1 + } + + It "Should return top device" { + $result = Get-EntraDeletedDevice -Top 1 + $result | Should -Not -BeNullOrEmpty + Should -Invoke -CommandName Get-MgDirectoryDeletedItemAsDevice -ModuleName Microsoft.Graph.Entra -Times 1 + } + + It "Property parameter should work" { + $result = Get-EntraDeletedDevice -Property "DisplayName" + $result | Should -Not -BeNullOrEmpty + $result.DisplayName | Should -Be "iPhone 12 Pro" + Should -Invoke -CommandName Get-MgDirectoryDeletedItemAsDevice -ModuleName Microsoft.Graph.Entra -Times 1 + } + + It "Should fail when Property is empty" { + { Get-EntraDeletedDevice -Property } | Should -Throw "Missing an argument for parameter 'Property'*" + } + + It "Should contain 'User-Agent' header" { + $userAgentHeaderValue = "PowerShell/$psVersion EntraPowershell/$entraVersion Get-EntraDeletedDevice" + $result = Get-EntraDeletedDevice -Filter "DisplayName -eq 'iPhone 12 Pro'" + $result | Should -Not -BeNullOrEmpty + $userAgentHeaderValue = "PowerShell/$psVersion EntraPowershell/$entraVersion Get-EntraDeletedDevice" + Should -Invoke -CommandName Get-MgDirectoryDeletedItemAsDevice -ModuleName Microsoft.Graph.Entra -Times 1 -ParameterFilter { + $Headers.'User-Agent' | Should -Be $userAgentHeaderValue + $true + } + } + + It "Should execute successfully without throwing an error" { + # Disable confirmation prompts + $originalDebugPreference = $DebugPreference + $DebugPreference = 'Continue' + + try { + # Act & Assert: Ensure the function doesn't throw an exception + { Get-EntraDeletedDevice -Debug } | Should -Not -Throw + } + finally { + # Restore original confirmation preference + $DebugPreference = $originalDebugPreference + } + } + } +} \ No newline at end of file From 3ce9598ef551d6a43c7615b4fac2832970cf5756 Mon Sep 17 00:00:00 2001 From: Steve Mutungi <132555836+SteveMutungi254@users.noreply.github.com> Date: Tue, 26 Nov 2024 10:59:36 +0300 Subject: [PATCH 8/9] Adding beta tests --- .../Get-EntraBetaDeletedDevice.Tests.ps1 | 93 +++++++++++++++++++ 1 file changed, 93 insertions(+) create mode 100644 test/module/EntraBeta/Get-EntraBetaDeletedDevice.Tests.ps1 diff --git a/test/module/EntraBeta/Get-EntraBetaDeletedDevice.Tests.ps1 b/test/module/EntraBeta/Get-EntraBetaDeletedDevice.Tests.ps1 new file mode 100644 index 0000000000..e9eb15279b --- /dev/null +++ b/test/module/EntraBeta/Get-EntraBetaDeletedDevice.Tests.ps1 @@ -0,0 +1,93 @@ +# ------------------------------------------------------------------------------ +# Copyright (c) Microsoft Corporation. All Rights Reserved. +# Licensed under the MIT License. See License in the project root for license information. +# ------------------------------------------------------------------------------ + +BeforeAll { + if ((Get-Module -Name Microsoft.Graph.Entra.Beta) -eq $null) { + Import-Module Microsoft.Graph.Entra.Beta + } + Import-Module (Join-Path $psscriptroot "..\Common-Functions.ps1") -Force + + $scriptblock = { + return @( + [PSCustomObject]@{ + "DisplayName" = "iPhone 12 Pro" + "Id" = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb" + "DeviceCategory" = "Test" + "AccountEnabled" = "True" + "DeletedDateTime" = "10/28/2024 4:16:02 PM" + "DeviceId" = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb" + } + ) + } + + Mock -CommandName Get-MgBetaDirectoryDeletedItemAsDevice -MockWith $scriptblock -ModuleName Microsoft.Graph.Entra.Beta +} + +Describe "Get-EntraBetaDeletedDevice" { + Context "Test for Get-EntraBetaDeletedDevice" { + It "Should return all devices" { + $result = Get-EntraBetaDeletedDevice + $result | Should -Not -BeNullOrEmpty + Should -Invoke -CommandName Get-MgBetaDirectoryDeletedItemAsDevice -ModuleName Microsoft.Graph.Entra.Beta -Times 1 + } + + It "Should return specific device by searchstring" { + $result = Get-EntraBetaDeletedDevice -SearchString 'iPhone 12 Pro' + $result | Should -Not -BeNullOrEmpty + $result.DisplayName | Should -Be 'iPhone 12 Pro' + Should -Invoke -CommandName Get-MgBetaDirectoryDeletedItemAsDevice -ModuleName Microsoft.Graph.Entra.Beta -Times 1 + } + + It "Should return specific device by filter" { + $result = Get-EntraBetaDeletedDevice -Filter "DisplayName -eq 'iPhone 12 Pro'" + $result | Should -Not -BeNullOrEmpty + $result.DisplayName | Should -Be 'iPhone 12 Pro' + Should -Invoke -CommandName Get-MgBetaDirectoryDeletedItemAsDevice -ModuleName Microsoft.Graph.Entra.Beta -Times 1 + } + + It "Should return top device" { + $result = Get-EntraBetaDeletedDevice -Top 1 + $result | Should -Not -BeNullOrEmpty + Should -Invoke -CommandName Get-MgBetaDirectoryDeletedItemAsDevice -ModuleName Microsoft.Graph.Entra.Beta -Times 1 + } + + It "Property parameter should work" { + $result = Get-EntraBetaDeletedDevice -Property "DisplayName" + $result | Should -Not -BeNullOrEmpty + $result.DisplayName | Should -Be "iPhone 12 Pro" + Should -Invoke -CommandName Get-MgBetaDirectoryDeletedItemAsDevice -ModuleName Microsoft.Graph.Entra.Beta -Times 1 + } + + It "Should fail when Property is empty" { + { Get-EntraBetaDeletedDevice -Property } | Should -Throw "Missing an argument for parameter 'Property'*" + } + + It "Should contain 'User-Agent' header" { + $userAgentHeaderValue = "PowerShell/$psVersion EntraPowershell/$entraVersion Get-EntraBetaDeletedDevice" + $result = Get-EntraBetaDeletedDevice -Filter "DisplayName -eq 'iPhone 12 Pro'" + $result | Should -Not -BeNullOrEmpty + $userAgentHeaderValue = "PowerShell/$psVersion EntraPowershell/$entraVersion Get-EntraBetaDeletedDevice" + Should -Invoke -CommandName Get-MgBetaDirectoryDeletedItemAsDevice -ModuleName Microsoft.Graph.Entra.Beta -Times 1 -ParameterFilter { + $Headers.'User-Agent' | Should -Be $userAgentHeaderValue + $true + } + } + + It "Should execute successfully without throwing an error" { + # Disable confirmation prompts + $originalDebugPreference = $DebugPreference + $DebugPreference = 'Continue' + + try { + # Act & Assert: Ensure the function doesn't throw an exception + { Get-EntraBetaDeletedDevice -Debug } | Should -Not -Throw + } + finally { + # Restore original confirmation preference + $DebugPreference = $originalDebugPreference + } + } + } +} \ No newline at end of file From 877f6243d0f6cc5a3351c01d4cb24e21d64f26de Mon Sep 17 00:00:00 2001 From: Steve Mutungi <132555836+SteveMutungi254@users.noreply.github.com> Date: Tue, 26 Nov 2024 11:36:13 +0300 Subject: [PATCH 9/9] Adding documentation --- .../Get-EntraBetaDeletedDevice.md | 277 ++++++++++++++++++ .../Get-EntraDeletedDevice.md | 277 ++++++++++++++++++ 2 files changed, 554 insertions(+) create mode 100644 module/docs/entra-powershell-beta/Microsoft.Graph.Entra.Beta/Get-EntraBetaDeletedDevice.md create mode 100644 module/docs/entra-powershell-v1.0/Microsoft.Graph.Entra/Get-EntraDeletedDevice.md diff --git a/module/docs/entra-powershell-beta/Microsoft.Graph.Entra.Beta/Get-EntraBetaDeletedDevice.md b/module/docs/entra-powershell-beta/Microsoft.Graph.Entra.Beta/Get-EntraBetaDeletedDevice.md new file mode 100644 index 0000000000..63323911c0 --- /dev/null +++ b/module/docs/entra-powershell-beta/Microsoft.Graph.Entra.Beta/Get-EntraBetaDeletedDevice.md @@ -0,0 +1,277 @@ +--- +title: Get-EntraBetaDeletedDevice +description: This article provides details on the Get-EntraBetaDeletedDevice command. + + +ms.topic: reference +ms.date: 11/14/2024 +ms.author: eunicewaweru +ms.reviewer: stevemutungi +manager: CelesteDG + +external help file: Microsoft.Graph.Entra.Beta-Help.xml +Module Name: Microsoft.Graph.Entra.Beta +online version: https://learn.microsoft.com/powershell/module/Microsoft.Graph.Entra.Beta/Get-EntraBetaDeletedDevice + +schema: 2.0.0 +--- + +# Get-EntraBetaDeletedDevice + +## Synopsis + +Retrieves the list of previously deleted devices. + +## Syntax + +### GetQuery (Default) + +```powershell +Get-EntraBetaDeletedDevice + [-Filter ] + [-All] + [-Top ] + [-Property ] + [] +``` + +### GetByValue + +```powershell +Get-EntraBetaDeletedDevice + [-SearchString ] + [-All] + [-Property ] + [] +``` + +### GetById + +```powershell +Get-EntraBetaDeletedDevice + -DeviceObjectId + [-All] + [-Property ] + [] +``` + +## Description + +The `Get-EntraBetaDeletedDevice` cmdlet Retrieves the list of previously deleted devices. + +## Examples + +### Example 1: Get list of deleted devices + +```powershell +Connect-Entra -Scopes 'Device.Read.All' +Get-EntraBetaDeletedDevice +``` + +```Output +DeletedDateTime Id AccountEnabled ApproximateLastSignInDateTime DeviceId DisplayName +--------------- -- -------------- ----------------------------- -------- ----------- +11/11/2024 5:16:25 PM bbbbbbbb-1111-2222-3333-cccccccccccc False 7/12/2024 8:36:17 PM aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb Network +11/6/2024 7:24:39 PM dddddddd-3333-4444-5555-eeeeeeeeeeee True 10/29/2024 9:07:18 PM eeeeeeee-4444-5555-6666-ffffffffffff iPhone 12 Pro +10/28/2024 4:16:02 PM cccccccc-2222-3333-4444-dddddddddddd True 6/24/2024 8:00:39 PM bbbbbbbb-1111-2222-3333-cccccccccccc Contoso Desktop +``` + +This cmdlet retrieves the list of deleted devices. + +### Example 2: Get list of deleted devices using All parameter + +```powershell +Connect-Entra -Scopes 'Device.Read.All' +Get-EntraBetaDeletedDevice -All +``` + +```Output +DeletedDateTime Id AccountEnabled ApproximateLastSignInDateTime DeviceId DisplayName +--------------- -- -------------- ----------------------------- -------- ----------- +11/11/2024 5:16:25 PM bbbbbbbb-1111-2222-3333-cccccccccccc False 7/12/2024 8:36:17 PM aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb Network +11/6/2024 7:24:39 PM dddddddd-3333-4444-5555-eeeeeeeeeeee True 10/29/2024 9:07:18 PM eeeeeeee-4444-5555-6666-ffffffffffff iPhone 12 Pro +10/28/2024 4:16:02 PM cccccccc-2222-3333-4444-dddddddddddd True 6/24/2024 8:00:39 PM bbbbbbbb-1111-2222-3333-cccccccccccc Contoso Desktop +``` + +This cmdlet retrieves the list of deleted devices using All parameter. + +### Example 3: Get top two deleted devices + +```powershell +Connect-Entra -Scopes 'Device.Read.All' +Get-EntraBetaDeletedDevice -Top 2 +``` + +```Output +DeletedDateTime Id AccountEnabled ApproximateLastSignInDateTime DeviceId DisplayName +--------------- -- -------------- ----------------------------- -------- ----------- +11/11/2024 5:16:25 PM bbbbbbbb-1111-2222-3333-cccccccccccc False 7/12/2024 8:36:17 PM aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb Network +11/6/2024 7:24:39 PM dddddddd-3333-4444-5555-eeeeeeeeeeee True 10/29/2024 9:07:18 PM eeeeeeee-4444-5555-6666-ffffffffffff iPhone 12 +``` + +This cmdlet retrieves top two deleted devices. + +### Example 4: Get deleted devices using SearchString parameter + +```powershell +Connect-Entra -Scopes 'Device.Read.All' +Get-EntraBetaDeletedDevice -SearchString 'Woodgrove Desktop' +``` + +```Output +DeletedDateTime Id AccountEnabled ApproximateLastSignInDateTime DeviceId DisplayName +--------------- -- -------------- ----------------------------- -------- ------ +10/28/2024 4:16:02 PM cccccccc-2222-3333-4444-dddddddddddd True 6/24/2024 8:00:39 PM bbbbbbbb-1111-2222-3333-cccccccccccc Woodgrove Desktop +``` + +This cmdlet retrieves deleted devices using SearchString parameter. + +### Example 5: Get deleted devices filter by display name + +```powershell +Connect-Entra -Scopes 'Device.Read.All' +Get-EntraBetaDeletedDevice -Filter "DisplayName eq 'Woodgrove Desktop'" +``` + +```Output +DeletedDateTime Id AccountEnabled ApproximateLastSignInDateTime DeviceId DisplayName +--------------- -- -------------- ----------------------------- -------- ------ +10/28/2024 4:16:02 PM cccccccc-2222-3333-4444-dddddddddddd True 6/24/2024 8:00:39 PM bbbbbbbb-1111-2222-3333-cccccccccccc Woodgrove Desktop +``` + +This cmdlet retrieves deleted devices having specified display name. + +### Example 6: Get deleted device by DeviceObjectId + +```powershell +Connect-Entra -Scopes 'Device.Read.All' +Get-EntraBetaDeletedDevice -DeviceObjectId 'cccccccc-2222-3333-4444-dddddddddddd' +``` + +```Output +DeletedDateTime Id AccountEnabled ApproximateLastSignInDateTime DeviceId DisplayName +--------------- -- -------------- ----------------------------- -------- ------ +10/28/2024 4:16:02 PM cccccccc-2222-3333-4444-dddddddddddd True 6/24/2024 8:00:39 PM bbbbbbbb-1111-2222-3333-cccccccccccc Woodgrove Desktop +``` + +This cmdlet retrieves the deleted device specified by DeviceObjectId. + +- `-DeviceObjectId` parameter specifies the deleted device Id. + +## Parameters + +### -All + +List all pages. + +```yaml +Type: System.Management.Automation.SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Filter + +Retrieve only those deleted devices that satisfy the filter. + +```yaml +Type: System.String +Parameter Sets: GetQuery +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName, ByValue) +Accept wildcard characters: False +``` + +### -SearchString + +Retrieve only those devices that satisfy the -SearchString value. + +```yaml +Type: System.String +Parameter Sets: GetVague +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName, ByValue) +Accept wildcard characters: False +``` + +### -Top + +The maximum number of devices. + +```yaml +Type: System.Int32 +Parameter Sets: GetQuery +Aliases: Limit + +Required: False +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName, ByValue) +Accept wildcard characters: False +``` + +### -Property + +Specifies properties to be returned + +```yaml +Type: System.String[] +Parameter Sets: (All) +Aliases: Select + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -DeviceObjectId + +The unique ID of the deleted device to be retrieved. + +```yaml +Type: System.String +Parameter Sets: GetById +Aliases: Id + +Required: True +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName, ByValue) +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: `-Debug`, `-ErrorAction`, `-ErrorVariable`, `-InformationAction`, `-InformationVariable`, `-OutVariable`, `-OutBuffer`, `-PipelineVariable`, `-Verbose`, `-WarningAction`, and `-WarningVariable`. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). + +## Inputs + +### System.String + +System.Nullable\`1\[\[System.Boolean, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089\]\] System.Nullable\`1\[\[System.Int32, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089\]\] + +## Outputs + +### System.Object + +## Notes + +## Related Links + +[Get-EntraBetaDevice](Get-EntraBetaDevice.md) diff --git a/module/docs/entra-powershell-v1.0/Microsoft.Graph.Entra/Get-EntraDeletedDevice.md b/module/docs/entra-powershell-v1.0/Microsoft.Graph.Entra/Get-EntraDeletedDevice.md new file mode 100644 index 0000000000..9e46ff6b5a --- /dev/null +++ b/module/docs/entra-powershell-v1.0/Microsoft.Graph.Entra/Get-EntraDeletedDevice.md @@ -0,0 +1,277 @@ +--- +title: Get-EntraDeletedDevice +description: This article provides details on the Get-EntraDeletedDevice command. + + +ms.topic: reference +ms.date: 11/14/2024 +ms.author: eunicewaweru +ms.reviewer: stevemutungi +manager: CelesteDG + +external help file: Microsoft.Graph.Entra-Help.xml +Module Name: Microsoft.Graph.Entra +online version: https://learn.microsoft.com/powershell/module/Microsoft.Graph.Entra/Get-EntraDeletedDevice + +schema: 2.0.0 +--- + +# Get-EntraDeletedDevice + +## Synopsis + +Retrieves the list of previously deleted devices. + +## Syntax + +### GetQuery (Default) + +```powershell +Get-EntraDeletedDevice + [-Filter ] + [-All] + [-Top ] + [-Property ] + [] +``` + +### GetByValue + +```powershell +Get-EntraDeletedDevice + [-SearchString ] + [-All] + [-Property ] + [] +``` + +### GetById + +```powershell +Get-EntraDeletedDevice + -DeviceObjectId + [-All] + [-Property ] + [] +``` + +## Description + +The `Get-EntraDeletedDevice` cmdlet Retrieves the list of previously deleted devices. + +## Examples + +### Example 1: Get list of deleted devices + +```powershell +Connect-Entra -Scopes 'Device.Read.All' +Get-EntraDeletedDevice +``` + +```Output +DeletedDateTime Id AccountEnabled ApproximateLastSignInDateTime DeviceId DisplayName +--------------- -- -------------- ----------------------------- -------- ----------- +11/11/2024 5:16:25 PM bbbbbbbb-1111-2222-3333-cccccccccccc False 7/12/2024 8:36:17 PM aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb Network +11/6/2024 7:24:39 PM dddddddd-3333-4444-5555-eeeeeeeeeeee True 10/29/2024 9:07:18 PM eeeeeeee-4444-5555-6666-ffffffffffff iPhone 12 Pro +10/28/2024 4:16:02 PM cccccccc-2222-3333-4444-dddddddddddd True 6/24/2024 8:00:39 PM bbbbbbbb-1111-2222-3333-cccccccccccc Contoso Desktop +``` + +This cmdlet retrieves the list of deleted devices. + +### Example 2: Get list of deleted devices using All parameter + +```powershell +Connect-Entra -Scopes 'Device.Read.All' +Get-EntraDeletedDevice -All +``` + +```Output +DeletedDateTime Id AccountEnabled ApproximateLastSignInDateTime DeviceId DisplayName +--------------- -- -------------- ----------------------------- -------- ----------- +11/11/2024 5:16:25 PM bbbbbbbb-1111-2222-3333-cccccccccccc False 7/12/2024 8:36:17 PM aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb Network +11/6/2024 7:24:39 PM dddddddd-3333-4444-5555-eeeeeeeeeeee True 10/29/2024 9:07:18 PM eeeeeeee-4444-5555-6666-ffffffffffff iPhone 12 Pro +10/28/2024 4:16:02 PM cccccccc-2222-3333-4444-dddddddddddd True 6/24/2024 8:00:39 PM bbbbbbbb-1111-2222-3333-cccccccccccc Contoso Desktop +``` + +This cmdlet retrieves the list of deleted devices using All parameter. + +### Example 3: Get top two deleted devices + +```powershell +Connect-Entra -Scopes 'Device.Read.All' +Get-EntraDeletedDevice -Top 2 +``` + +```Output +DeletedDateTime Id AccountEnabled ApproximateLastSignInDateTime DeviceId DisplayName +--------------- -- -------------- ----------------------------- -------- ----------- +11/11/2024 5:16:25 PM bbbbbbbb-1111-2222-3333-cccccccccccc False 7/12/2024 8:36:17 PM aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb Network +11/6/2024 7:24:39 PM dddddddd-3333-4444-5555-eeeeeeeeeeee True 10/29/2024 9:07:18 PM eeeeeeee-4444-5555-6666-ffffffffffff iPhone 12 +``` + +This cmdlet retrieves top two deleted devices. + +### Example 4: Get deleted devices using SearchString parameter + +```powershell +Connect-Entra -Scopes 'Device.Read.All' +Get-EntraDeletedDevice -SearchString 'Woodgrove Desktop' +``` + +```Output +DeletedDateTime Id AccountEnabled ApproximateLastSignInDateTime DeviceId DisplayName +--------------- -- -------------- ----------------------------- -------- ------ +10/28/2024 4:16:02 PM cccccccc-2222-3333-4444-dddddddddddd True 6/24/2024 8:00:39 PM bbbbbbbb-1111-2222-3333-cccccccccccc Woodgrove Desktop +``` + +This cmdlet retrieves deleted devices using SearchString parameter. + +### Example 5: Get deleted devices filter by display name + +```powershell +Connect-Entra -Scopes 'Device.Read.All' +Get-EntraDeletedDevice -Filter "DisplayName eq 'Woodgrove Desktop'" +``` + +```Output +DeletedDateTime Id AccountEnabled ApproximateLastSignInDateTime DeviceId DisplayName +--------------- -- -------------- ----------------------------- -------- ------ +10/28/2024 4:16:02 PM cccccccc-2222-3333-4444-dddddddddddd True 6/24/2024 8:00:39 PM bbbbbbbb-1111-2222-3333-cccccccccccc Woodgrove Desktop +``` + +This cmdlet retrieves deleted devices having specified display name. + +### Example 6: Get deleted device by DeviceObjectId + +```powershell +Connect-Entra -Scopes 'Device.Read.All' +Get-EntraDeletedDevice -DeviceObjectId 'cccccccc-2222-3333-4444-dddddddddddd' +``` + +```Output +DeletedDateTime Id AccountEnabled ApproximateLastSignInDateTime DeviceId DisplayName +--------------- -- -------------- ----------------------------- -------- ------ +10/28/2024 4:16:02 PM cccccccc-2222-3333-4444-dddddddddddd True 6/24/2024 8:00:39 PM bbbbbbbb-1111-2222-3333-cccccccccccc Woodgrove Desktop +``` + +This cmdlet retrieves the deleted device specified by DeviceObjectId. + +- `-DeviceObjectId` parameter specifies the deleted device Id. + +## Parameters + +### -All + +List all pages. + +```yaml +Type: System.Management.Automation.SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Filter + +Retrieve only those deleted devices that satisfy the filter. + +```yaml +Type: System.String +Parameter Sets: GetQuery +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName, ByValue) +Accept wildcard characters: False +``` + +### -SearchString + +Retrieve only those devices that satisfy the -SearchString value. + +```yaml +Type: System.String +Parameter Sets: GetVague +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName, ByValue) +Accept wildcard characters: False +``` + +### -Top + +The maximum number of devices. + +```yaml +Type: System.Int32 +Parameter Sets: GetQuery +Aliases: Limit + +Required: False +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName, ByValue) +Accept wildcard characters: False +``` + +### -Property + +Specifies properties to be returned + +```yaml +Type: System.String[] +Parameter Sets: (All) +Aliases: Select + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -DeviceObjectId + +The unique ID of the deleted device to be retrieved. + +```yaml +Type: System.String +Parameter Sets: GetById +Aliases: Id + +Required: True +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName, ByValue) +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: `-Debug`, `-ErrorAction`, `-ErrorVariable`, `-InformationAction`, `-InformationVariable`, `-OutVariable`, `-OutBuffer`, `-PipelineVariable`, `-Verbose`, `-WarningAction`, and `-WarningVariable`. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). + +## Inputs + +### System.String + +System.Nullable\`1\[\[System.Boolean, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089\]\] System.Nullable\`1\[\[System.Int32, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089\]\] + +## Outputs + +### System.Object + +## Notes + +## Related Links + +[Get-EntraDevice](Get-EntraDevice.md)