Test-LocalPortFree #

ÜBERSICHT #

Prüft, ob ein lokaler TCP-Port frei (nicht im Listen-Zustand) ist.

SYNTAX #

Test-LocalPortFree [-Port] <int> [-Show] [<CommonParameters>]

BESCHREIBUNG #

Die Funktion Test-LocalPortFree prüft, ob auf dem lokalen Rechner ein Prozess auf dem angegebenen TCP-Port lauscht. Sie ist als Pre-Flight-Check gedacht vor Funktionen, die einen lokalen HttpListener öffnen müssen (z.B. Get-GraphToken im User-Flow mit Redirect-URI auf http://localhost:<Port>/).

Liefert $true, wenn der Port frei ist. Bei belegtem Port:

Rückgabewert $false,
per Write-Verbose Klartext mit Prozessname, PID und einem Lösungshinweis. Bekannte Übeltäter wie cti_client (vioNetworks CTI-Client für Telefonie), httpd (Apache/XAMPP), java/tomcat, node und vergessene PowerShell-Sessions werden über eine Hint-Tabelle erkannt und mit konkretem Stichwort erläutert.
Mit -Show wird zusätzlich eine native Windows-MessageBox mit der Diagnose angezeigt – nützlich für interaktive Skripte ohne sichtbare Konsole (Doppelklick-Verknüpfungen, geplante Aufgaben mit UI-Trigger).

Die Funktion nutzt Get-NetTCPConnection und benötigt keine Administrator-Rechte.

PARAMETER #

-Port #

Type: int

Portnummer im Bereich 1 bis 65535, die geprüft werden soll.

-Show #

Type: switch

Bei belegtem Port zusätzlich eine native Windows-MessageBox mit der Klartext-Diagnose anzeigen. Ohne -Show läuft die Funktion stumm (nur Rückgabewert und Verbose-Stream).

AUSGABEN #

[bool]

$true = Port frei, $false = Port belegt.

BEISPIELE #

# Einfacher Check
if (Test-LocalPortFree -Port 8080) { 'frei' }

# Mit Verbose-Diagnose im Konfliktfall
if (-not (Test-LocalPortFree -Port 8080 -Verbose)) {
  throw 'Port 8080 belegt - siehe Verbose für Details.'
}

# Mit Popup für interaktive Endanwender
if (-not (Test-LocalPortFree -Port 8080 -Show)) {
  return
}

HINWEISE #

Typischer Einsatz: vor HttpListener.Start() aufrufen, damit der Anwender bei Port-Kollision eine sprechende Meldung bekommt statt eines kryptischen Zugriff verweigert oder eines Browser-ERR_CONNECTION_REFUSED.

Häufige Übeltäter auf einer EULANDA-Arbeitsplatz-Box: vioNetworks CTI-Client (8080), Apache/XAMPP (80, 8080), Tomcat (8080), Start-MiniWebserver aus einer vergessenen PowerShell-Session (8080).