From: Ardis Lu <ardisglu@gmail.com>
Date: Mon, 4 Jul 2022 23:20:41 +0000 (-0700)
Subject: Add Test-TcpPort
X-Git-Url: https://git.ardis.lu/?a=commitdiff_plain;h=0cb61fc80eb1d6fa38a9b2feefe6d4d0f2636c7f;p=ArdisUtilities

Add Test-TcpPort
---

diff --git a/ArdisUtilities/ArdisUtilities.psd1 b/ArdisUtilities/ArdisUtilities.psd1
index 12d7444..29bc17a 100644
--- a/ArdisUtilities/ArdisUtilities.psd1
+++ b/ArdisUtilities/ArdisUtilities.psd1
@@ -4,7 +4,7 @@
   GUID              = '57a6bea3-0ea5-44b3-95d2-71d122772f1c'
   Author            = 'Ardis Lu'
   Description       = 'My personal utility functions.'
-  FunctionsToExport = @('Invoke-RandomFile', 'ConvertTo-Base64String', 'Get-StringHash', 'Get-SizeDurationRatio', 'Get-ExtendedFileProperty', 'Get-DocumentationIP')
+  FunctionsToExport = @('Invoke-RandomFile', 'ConvertTo-Base64String', 'Get-StringHash', 'Get-SizeDurationRatio', 'Get-ExtendedFileProperty', 'Get-DocumentationIP', 'Test-TcpPort')
   CmdletsToExport   = @()
   VariablesToExport = @()
   AliasesToExport   = @()
diff --git a/ArdisUtilities/ArdisUtilities.psm1 b/ArdisUtilities/ArdisUtilities.psm1
index 46393ed..b7af8e1 100644
--- a/ArdisUtilities/ArdisUtilities.psm1
+++ b/ArdisUtilities/ArdisUtilities.psm1
@@ -485,3 +485,80 @@ function Get-DocumentationIP {
     }
   }
 }
+
+class PortStatus {
+  [String]$RemoteHost
+  [String]$Protocol
+  [Int]$Port
+  [Boolean]$PortOpen
+}
+
+function Test-TcpPort {
+  <#
+  .SYNOPSIS
+    Tests if a TCP port is open or not.
+
+  .DESCRIPTION
+    Uses System.Net.Sockets.TcpClient to connect to a given TCP port and return whether the remote host responded or not.
+    Similar to Test-NetConnection but the timeout duration is adjustable and much smaller by default.
+
+  .PARAMETER RemoteHost
+    The name of the remote host to test TCP ports against.
+
+  .PARAMETER Port
+    The port number to test. Valid values are integers between 1 and 65535. The default value is 80.
+
+  .PARAMETER Timeout
+    The duration (in milliseconds) to wait for a response from the remote host. The default value is 200.
+
+  .EXAMPLE
+    PS> Test-TcpPort example.com
+
+    RemoteHost  Protocol Port PortOpen
+    ----------  -------- ---- --------
+    example.com TCP      80       True
+
+  .EXAMPLE
+    PS> @(25, 80, 443) | Test-TcpPort example.com  
+
+    RemoteHost  Protocol Port PortOpen
+    ----------  -------- ---- --------
+    example.com TCP      25      False
+    example.com TCP      80       True
+    example.com TCP      443      True
+  
+  .LINK
+    Test-Connection
+  
+  .LINK
+    Test-NetConnection
+  #>
+
+  [OutputType([PortStatus])]
+  [CmdletBinding()]
+  param(
+    [Parameter(Mandatory)]
+    [String]$RemoteHost,
+
+    [Parameter(ValueFromPipeline)]
+    [ValidateRange(1, 65535)]
+    [Int]$Port = 80,
+
+    [ValidateRange(1, [Int]::MaxValue)]
+    [Int]$Timeout = 200
+  )
+  
+  process {
+    $client = New-Object System.Net.Sockets.TcpClient
+    $signal = $client.BeginConnect($RemoteHost, $Port, $null, $null).AsyncWaitHandle.WaitOne($Timeout, $false)
+
+    [PortStatus] @{
+      RemoteHost = $RemoteHost
+      Protocol   = 'TCP'
+      Port       = $Port
+      PortOpen   = $signal
+    }
+
+    $client.Close()
+  }
+}