What awaits you here?

• Windows Server Failover Cluster Deployment with Extended AD and DNS Permissions
• Identity Management: Group Managed Service Accounts (gMSA)
• Kerberos and Service Principal Names (SPN)
• Local Security Policies
• Background knowledge on why configurations are done the way they are

Intro

Who hasn’t been there? Before you can even start installing SQL Server, you’ve either repetitively clicked through pages of bad GUIs or, if available, juggled a loose collection of scripts to semi-automatically set up all dependencies and best practices.

Even worse is the case when, as a consultant, you don’t have Domain Admin access (which is how it should be) and you have to guide the customer — who may have never done this before — via Teams & Co. If this isn’t already a planned installation with knowledge transfer, something like this creates pain.

Accordingly, I’ve now gathered all my loose scripts and developed a function for each topic area that automates all these tasks and logs them for archival purposes. Thanks also to Claude for the support. Nobody reviews and documents code better than Claude.

Now you might ask: Aren’t there dbatools and DSC? Sure, I like using those too. But transparent, traceable scripts without framework overhead convey knowledge better — especially when aspiring DBAs lack the big-picture perspective. Operating SQL Server starts at the bare metal, goes through storage, Windows Server, Active Directory, and ends at a Certificate Authority. And for critical infrastructure companies or small mid-sized businesses with 3 clusters, I don’t want to start a fundamental discussion about dbatools or DSC right from the beginning.

Let’s start with a production-ready Windows Server Failover Cluster — including CNO/VCO permissions, DNS registration, and quorum configuration. Everything repeatable, everything logged, everything traceable.

The Lab Scenario

To make the steps tangible, the following environment and naming conventions are used

• Nodes
  • LAB-NODE01 (192.168.100.12)
  • LAB-NODE02 (192.168.100.13)
• Cluster Name
  • MSSQL-CL-01 (192.168.100.14)
• SQL Instance
  • LAB22A
• Domain
  • lab.local
• Service Accounts Group Managed Service Accounts (gMSA)
  • g-LAB22A-oltp
  • g-LAB22A-agnt

Windows Server Failover Cluster Deployment

The WSFC forms the foundation for AlwaysOn Availability Groups. The script manages the entire lifecycle from feature installation to witness configuration.

Feature Installation & Cluster Creation

First, the Failover-Clustering feature is installed on the individual nodes and the cluster is created. An important aspect of automation is the Cluster Name Object (CNO): It needs write permissions in DNS and Active Directory to be able to automatically create listener records later.

.\cluster_manageSQLCluster.ps1 `
    -Operation InstallFeature `
    -Nodes "LAB-NODE01","LAB-NODE02" `
    -LogPath "C:\Temp\Cluster_Feature_$(Get-Date -Format 'yyyyMMdd_HHmmss').log"

Afterwards, the cluster is created. The script additionally sets the corresponding permissions in AD and DNS.

.\cluster_manageSQLCluster.ps1 `
    -Operation CreateCluster `
    -ClusterName "MSSQL-CL-01" `
    -Nodes "LAB-NODE01","LAB-NODE02" `
    -StaticIP "192.168.100.14" `
    -DnsDomain "lab.local" `
    -TargetOU "OU=lab_computer,DC=lab,DC=local" `
    -LogPath "C:\Temp\Cluster_Create_$(Get-Date -Format 'yyyyMMdd_HHmmss').log"

File Share Witness (Quorum)

For a 2-node cluster, a witness is mandatory to avoid split-brain scenarios. Here, a file share on the domain controller (\\LAB-DC\quorum$) is used.

Manual Intermediate Step
The Cluster Computer Object (MSSQL-CL-01$) requires Full Control at both the share and NTFS permission level of the witness path (\\LAB-DC\quorum$). This must be ensured before running the following command.

.\cluster_manageSQLCluster.ps1 `
    -Operation SetWitness `
    -ClusterName "MSSQL-CL-01" `
    -WitnessShare "\\LAB-DC\quorum$" `
    -LogPath "C:\Temp\Cluster_Witness_$(Get-Date -Format 'yyyyMMdd_HHmmss').log"

Microsoft Cmdlets Used

The script primarily uses the FailoverClusters module

• New-Cluster
  • Creates the cluster, adds the nodes, and sets the management IP
• Set-ClusterQuorum
  • Configures the witness mode (here: File Share Witness)
• Install-WindowsFeature
  • Installs the RSAT tools and the cluster service

Identity Management: gMSA

Using standard users as service accounts can lead to expired passwords and downtime. The recommended method for SQL Server is Group Managed Service Accounts (gMSA). Here, the Key Distribution Service (KDS) of Active Directory handles password rotation; nobody needs to know the password.

KDS Root Key

Before the first gMSA can be created, a KDS Root Key must exist once per forest. If a key already exists, the creation will be skipped.

.\security_createGMSA.ps1 `
    -InitializeKDS `
    -LogPath "C:\Temp\KDS_Init.log"

gMSA Creation

Instead of assigning servers directly to a gMSA, it is best practice to create a security group (SQL_LAB_CL01) that contains the computer accounts of the cluster nodes. In addition to setting up the actual gMSA, this script can also create the security groups and handle the assignments. And always keep the descriptions of AD objects well-maintained.

.\security_createGMSA.ps1 `
    -AccountName @( `
        @("g-LAB22A-oltp", "SQL Server Engine Account for LAB22A"), `
        @("g-LAB22A-agnt", "SQL Server Agent Account for LAB22A") ) `
    -SecurityGroupName "SQL_LAB_CL01" `
    -SecurityGroupDescription "SQL Server Cluster CL01 gMSA Group" `
    -ServerNames "LAB-NODE01","LAB-NODE02" `
    -CreateSecurityGroup `
    -SecurityGroupOU "OU=lab_secgrp,DC=lab,DC=local" `
    -PasswordIntervalDays 90 `
    -LogPath "C:\Temp\gMSA_Creation_$(Get-Date -Format 'yyyyMMdd_HHmmss').log"

After this step, a restart of the nodes is required for the new group membership to take effect.

Local Registration

After creation, the gMSAs must be registered locally on the nodes. The following script can be used for this purpose.

# Required for local setup (Local Admin)
Add-WindowsFeature -Name RSAT-AD-PowerShell

$gMSAs = @(
    'g-LAB22A-oltp',
    'g-LAB22A-agnt'
)

foreach ($gMSA in $gMSAs) {

    if (Test-ADServiceAccount -Identity $gMSA -ErrorAction SilentlyContinue) {
        try {
            Install-ADServiceAccount -Identity $gMSA -ErrorAction Stop
            Write-Host "$gMSA installed" -ForegroundColor Green
        } catch {
            Write-Host "$gMSA - Installation error: $($_.Exception.Message)" -ForegroundColor Red
        }
    } else {
        Write-Host "$gMSA does not exist" -ForegroundColor Yellow
    }
}

After this step, a restart of the nodes is required for the new group membership to take effect.

Microsoft Cmdlets Used

The script primarily uses the ActiveDirectory module

• Add-KdsRootKey
  • Creates the root key for the Group Key Distribution Service
• New-ADServiceAccount
  • Creates the gMSA object in AD
• Set-ADServiceAccount
  • Configures which computers (PrincipalsAllowedToRetrieveManagedPassword) are allowed to read the password

Kerberos and Service Principal Names (SPN)

A gMSA does not have the right to write its own SPNs in AD by default. When the SQL service starts, the registration often fails, leading to NTLM fallbacks. Even though I prefer to set SPNs in a controlled and manual manner, the automatic registration must be technically possible to avoid fallbacks.

The script solves this problem by granting the gMSA the rights in AD to manage its own SPNs, in addition to creating the SPNs. It sets ACLs on the nodes for Read, Write, and Validated write on the servicePrincipalName attribute.

.\security_setSqlSpn.ps1 `
    -ServiceAccount "LAB\g-LAB22A-oltp" `
    -InstanceName "LAB22A" `
    -Port 51101 `
    -Hostnames "LAB-NODE01","LAB-NODE02" `
    -Domain "lab.local" `
    -IsGMSA `
    -SetADPermissions `
    -LogPath "C:\Temp\SPN_AlwaysOn_$(Get-Date -Format 'yyyyMMdd_HHmmss').log"

Microsoft Cmdlets Used

On one hand, setspn.exe is used for SPN management, and on the other hand, the ActiveDirectory module is used again to verify accounts and extract SIDs.

Since none of the modules can manipulate Active Directory permissions, the .NET Framework System.DirectoryServices is used directly for this purpose, which provides various classes to completely turn AD inside out.

Local Security Policies

As everywhere in IT, SQL Server should also follow the PoLP, which is why no service account gets local administrator privileges. For SQL Server to still run flawlessly and performantly, the service account needs specific rights in the operating system („User Rights Assignment“). Anyone who has done this manually a few times will be very happy about this solution. This must be executed locally on the respective node.

# ===== Set Engine Permissions for gMSA =====

    .\security_setSqlLocalSec.ps1 `
        -ServiceAccount "g-LAB22A-oltp$" `
        -ServiceType "engine" `
        -IsGMSA `
        -LogPath "C:\Temp\LAB22A_Engine_$(Get-Date -Format 'yyyyMMdd_HHmmss').log"

# ===== Set Agent Permissions for gMSA =====

    .\security_setSqlLocalSec.ps1 `
        -ServiceAccount "g-LAB22A-agnt$" `
        -ServiceType "agent" `
        -IsGMSA `
        -LogPath "C:\Temp\LAB22A_Agent_$(Get-Date -Format 'yyyyMMdd_HHmmss').log"

Microsoft Cmdlets Used

Since PowerShell has no native cmdlets for editing local security policies, the Windows tool secedit.exe is used and its export is manipulated.

Summary

With these four building blocks, the foundation for a SQL Server installation has been laid. It wasn’t just an installation that was performed, but a valid, documented configuration that considers identity (gMSA), network (DNS/SPN), and OS performance. In the next step, the actual SQL Server instance can be installed.

Also check out the linked MD files — they contain background information on best practices and further articles from Microsoft

The post Automate SQL Server HA: AD, SPN, and Cluster Setup first appeared on DBA von Nebenan.

Was erwartet dich hier?

• Windows Server Failover Cluster Deployment mit erweiterten AD- und DNS-Berechtigungen
• Identity Management: Group Managed Service Accounts (gMSA)
• Kerberos und Service Principal Names (SPN)
• Lokale Sicherheitsrichtlinien (Local Security Policies)
• Hintergrundwissen warum Konfigurationen gemacht werden wie sie gemacht werden

Intro

Wer kennt es nicht? Bevor man überhaupt mit der Installation von SQL Server loslegen kann, hat man sich entweder repetitiv durch seitenweise schlechte GUIs geklickt oder wenn verfügbar, mit einer losen Sammlung an Scripten jongliert und semiautomatisch alle Abhängigkeiten und Best Practices eingerichtet.

Noch schlimmer ist der Fall, wenn man als Berater gar keinen Domain Admin hat (was auch so sein sollte) und man den Kunden, der dies vielleicht noch nie gemacht hat, per Teams & Co anleiten muss. Wenn dies nicht eh eine geplante Installation mit Know-how-Transfer ist, erzeugt so etwas Schmerz.

Dementsprechend habe ich nun mal all meine losen Scripte zusammengewürfelt und für jeden Themenbereich eine recht umfangreiche Funktion entwickelt, welche all diese Tasks automatisiert und für Archivzwecke loggt. Danke auch an Claude für die Unterstützung. Keiner kontrolliert und dokumentiert Code besser als Claude.

Nun könnte man sich fragen: Es gibt doch dbatools und DSC? Klar, nutze ich auch gerne. Aber transparente, nachvollziehbare Scripts ohne Framework-Overhead vermitteln Wissen besser – gerade wenn angehenden DBAs der Blick fürs Ganze fehlt. Betrieb von SQL Server fängt auf dem Blech an, geht über Storage, Windows Server, Active Directory und hört bei einer Certificate Authority auf. Und bei KRITIS-Unternehmen oder kleinen Mittelständlern mit 3 Clustern will ich zu Beginn keine Grundsatzdiskussion über dbatools oder DSC führen.

Los geht’s mit einem Production-Ready Windows Server Failover Cluster – inklusive CNO/VCO-Berechtigungen, DNS-Registrierung und Quorum-Konfiguration. Alles wiederholbar, alles geloggt, alles nachvollziehbar.

Das Lab Szenario

Um die Schritte greifbar zu machen, wird folgende Umgebung und Naming-Conventions genutzt

• Nodes
  • LAB-NODE01 (192.168.100.12)
  • LAB-NODE02 (192.168.100.13)
• Cluster Name
  • MSSQL-CL-01 (192.168.100.14)
• SQL Instanz
  • LAB22A
• Domain
  • lab.local
• Service Accounts Group Managed Service Accounts (gMSA)
  • g-LAB22A-oltp
  • g-LAB22A-agnt

Windows Server Failover Cluster Deployment

Der WSFC bildet das Fundament für AlwaysOn Availability Groups. Das Script steuert den gesamten Lifecycle von der Feature-Installation bis zur Witness-Konfiguration.

Feature Installation & Cluster Erstellung

Zunächst wird das Feature Failover-Clustering auf den einzelnen Nodes installiert und der Cluster erstellt. Ein wichtiger Aspekt bei der Automatisierung ist das Cluster-Objekt (CNO): Es benötigt Schreibrechte im DNS und Active Directory um später automatisiert Listener-Records anlegen zu können.

.\cluster_manageSQLCluster.ps1 `
    -Operation InstallFeature `
    -Nodes "LAB-NODE01","LAB-NODE02" `
    -LogPath "C:\Temp\Cluster_Feature_$(Get-Date -Format 'yyyyMMdd_HHmmss').log"

Anschließend wird der Cluster erstellt. Das Script setzt zusätzlich die entsprechenden Berechtigungen in AD und DNS.

.\cluster_manageSQLCluster.ps1 `
    -Operation CreateCluster `
    -ClusterName "MSSQL-CL-01" `
    -Nodes "LAB-NODE01","LAB-NODE02" `
    -StaticIP "192.168.100.14" `
    -DnsDomain "lab.local" `
    -TargetOU "OU=lab_computer,DC=lab,DC=local" `
    -LogPath "C:\Temp\Cluster_Create_$(Get-Date -Format 'yyyyMMdd_HHmmss').log"

File Share Witness (Quorum)

Für einen 2-Node Cluster ist ein Witness zwingend erforderlich, um Split-Brain-Szenarien zu vermeiden. Hier wird ein File Share auf dem Domain Controller (\\LAB-DC\quorum$) genutzt.

Manueller Zwischenschritt
Das Cluster-Computer-Objekt (MSSQL-CL-01$) benötigt Full Control auf Ebene der Share- und NTFS-Berechtigungen des Witness-Pfads (\\LAB-DC\quorum$). Dies muss vor dem folgenden Befehl sichergestellt sein.

.\cluster_manageSQLCluster.ps1 `
    -Operation SetWitness `
    -ClusterName "MSSQL-CL-01" `
    -WitnessShare "\\LAB-DC\quorum$" `
    -LogPath "C:\Temp\Cluster_Witness_$(Get-Date -Format 'yyyyMMdd_HHmmss').log"

Verwendete Microsoft Cmdlets

Das Script nutzt primär das FailoverClusters Modul

• New-Cluster
  • Erstellt den Cluster, bindet die Nodes ein und setzt die Management-IP
• Set-ClusterQuorum
  • Konfiguriert den Witness-Modus (hier: File Share Witness)
• Install-WindowsFeature
  • Installiert die RSAT-Tools und den Cluster-Dienst

Identity Management: gMSA

Die Nutzung von Standard-Usern als Service Accounts kann zu abgelaufenen Passwörtern und Downtime führen. Die empfohlene Methode für SQL Server sind Group Managed Service Accounts (gMSA). Hierbei übernimmt der Key Distribution Service (KDS) des Active Directory die Passwortrotation; Niemand muss das Passwort kennen.

KDS Root Key

Bevor der erste gMSA erstellt werden kann, muss einmalig pro Forest ein KDS Root Key existieren. Sollte bereits ein Key existieren, wird die Erstellung übersprungen.

.\security_createGMSA.ps1 `
    -InitializeKDS `
    -LogPath "C:\Temp\KDS_Init.log"

gMSA Erstellung

Anstatt Server direkt einem gMSA zuzuordnen, ist es Best Practice, eine Security Group zu erstellen (SQL_LAB_CL01), welche die Computerkonten der Cluster-Nodes enthält. Neben der Einrichtung der eigentlichen gMSA kann dieses Script auch die Security Gruppen erstellen und die Zuordnungen vornehmen. Und immer schön die Beschreibungen bei AD-Objekten pflegen.

.\security_createGMSA.ps1 `
    -AccountName @( `
        @("g-LAB22A-oltp", "SQL Server Engine Account for LAB22A"), `
        @("g-LAB22A-agnt", "SQL Server Agent Account for LAB22A") ) `
    -SecurityGroupName "SQL_LAB_CL01" `
    -SecurityGroupDescription "SQL Server Cluster CL01 gMSA Group" `
    -ServerNames "LAB-NODE01","LAB-NODE02" `
    -CreateSecurityGroup `
    -SecurityGroupOU "OU=lab_secgrp,DC=lab,DC=local" `
    -PasswordIntervalDays 90 `
    -LogPath "C:\Temp\gMSA_Creation_$(Get-Date -Format 'yyyyMMdd_HHmmss').log"

Nach diesem Schritt ist ein Neustart der Nodes erforderlich, damit die neue Gruppenmitgliedschaft wirksam wird.

Lokale Registrierung

Nach der Erstellung müssen die gMSA lokal auf den Nodes registriert werden. Hierzu kann folgendes Script genutzt werden.

# Wichtig für lokale Einrichtung ( Local Admin )
Add-WindowsFeature -Name RSAT-AD-PowerShell

$gMSAs = @(
    'g-LAB22A-oltp',
    'g-LAB22A-agnt'
)

foreach ($gMSA in $gMSAs) {

    if (Test-ADServiceAccount -Identity $gMSA -ErrorAction SilentlyContinue) {
        try {
            Install-ADServiceAccount -Identity $gMSA -ErrorAction Stop
            Write-Host "$gMSA installiert" -ForegroundColor Green
        } catch {
            Write-Host "$gMSA - Fehler bei Installation: $($_.Exception.Message)" -ForegroundColor Red
        }
    } else {
        Write-Host "$gMSA existiert nicht" -ForegroundColor Yellow
    }
}

Nach diesem Schritt ist ein Neustart der Nodes erforderlich, damit die neue Gruppenmitgliedschaft (TGT) wirksam wird.

Verwendete Microsoft Cmdlets

Das Script nutzt primär das ActiveDirectory Modul

• Add-KdsRootKey
  • Erzeugt den Root Key für den Group Key Distribution Service
• New-ADServiceAccount
  • Erstellt das gMSA Objekt im AD
• Set-ADServiceAccount
  • Konfiguriert, welche Computer (PrincipalsAllowedToRetrieveManagedPassword) das Passwort lesen dürfen

Kerberos und Service Principal Names (SPN)

Ein gMSA besitzt standardmäßig nicht das Recht, seine eigenen SPNs im AD zu schreiben. Startet der SQL Dienst, schlägt die Registrierung oft fehl, was zu NTLM-Fallbacks führt. Auch wenn ich SPNs bevorzugt kontrolliert und manuell setze, muss die automatische Registrierung technisch möglich sein, um Fallbacks zu vermeiden.

Das Script löst dieses Problem, indem es zusätzlich zur SPN Erstellung dem gMSA die Rechte im AD gewährt, seine eigenen SPNs zu verwalten. Es setzt ACLs der Nodes für Read, Write und Validated write auf das Attribut servicePrincipalName.

.\security_setSqlSpn.ps1 `
    -ServiceAccount "LAB\g-LAB22A-oltp" `
    -InstanceName "LAB22A" `
    -Port 51101 `
    -Hostnames "LAB-NODE01","LAB-NODE02" `
    -Domain "lab.local" `
    -IsGMSA `
    -SetADPermissions `
    -LogPath "C:\Temp\SPN_AlwaysOn_$(Get-Date -Format 'yyyyMMdd_HHmmss').log"

Verwendete Microsoft Cmdlets

Zum einen wird setspn.exe für Verwaltung der SPN genutzt, zum anderen wieder das ActiveDirectory Modul, um Accounts zu verifizieren und die SIDs zu extrahieren.

Da keines der Module Active Directory Permsission manipulieren kann, wird hierfür direkt das .NET Framework System.DirectoryServices genutzt, welches diverse Klassen bereitstellt, um das AD komplett auf Links zu drehen.

Lokale Sicherheitsrichtlinien (Local Security Policies)

Wie überall in der IT sollte auch beim Sql Server nach dem PoLP gearbeitet werden, weshalb kein Service Account den lokalen Administrator bekommt.Damit SQL Server trotzdem fehlerfrei und performant läuft, benötigt der Service Account spezifische Rechte im Betriebssystem („User Rights Assignment“). Wer dies ein paar mal manuell gemacht hat, wird sich sehr über diese Lösung freuen. Diese muss lokal auf dem jeweiligen Node ausgeführt werden.

# ===== Set Engine Permissions for gMSA =====

    .\security_setSqlLocalSec.ps1 `
        -ServiceAccount "g-LAB22A-oltp$" `
        -ServiceType "engine" `
        -IsGMSA `
        -LogPath "C:\Temp\LAB22A_Engine_$(Get-Date -Format 'yyyyMMdd_HHmmss').log"

# ===== Set Agent Permissions for gMSA =====

    .\security_setSqlLocalSec.ps1 `
        -ServiceAccount "g-LAB22A-agnt$" `
        -ServiceType "agent" `
        -IsGMSA `
        -LogPath "C:\Temp\LAB22A_Agent_$(Get-Date -Format 'yyyyMMdd_HHmmss').log"

Verwendete Microsoft Cmdlets

Da PowerShell keine nativen Cmdlets besitzt, um lokale Sicherheitsrichtlinien (LSA) zu bearbeiten, wird das Windows-Tool secedit.exe genutzt und der Export manipuliert.

Summary

Mit diesen vier Bausteinen wurde das Fundament für eine Sql Server Installation gelegt. Es wurde nicht nur eine Installation durchgeführt, sondern eine valide, dokumentierte Konfiguration geschaffen, die Identität (gMSA), Netzwerk (DNS/SPN) und OS-Performance (LSA) berücksichtigt. Im nächsten Schritt kann die eigentliche SQL Server Instanz installiert werden.

Schaut euch auch die verlinkten MD-Files an, dort stehen Hintergrundinfos zu den Best Practices und weiterführende Artikel von Microsoft

The post SQL Server HA: AD, SPN und Cluster Setup automatisieren first appeared on DBA von Nebenan.

• Changelog
• Documentation

Intro

Windows Performance Counters are absolutely powerful, but when I need something quick or monitoring tailored to a specific problem, I get frustrated fast. Usually I fall back on other options – PowerShell native Get-Counter, CIM, or existing monitoring solutions at my clients. But that’s never truly ad-hoc either, and I’ve accepted it.

Recently I had the chance to join Uwe Ricken’s Performance Tuning Workshop at DataSaturday, and he clearly named Performance Counters as a must-have in every DBA’s toolkit. What I didn’t know until then: SQL Server creates individual counters like Compile/sec, AdHoc Queries/sec, etc.

The possibilities to visualize dependencies directly – endless. But how long should I sit there configuring that in Windows Performance Monitor, especially ad-hoc at a client site?

Uwe showed the capabilities in Windows Admin Center, which enables templates you can use flexibly across servers. For systems or environments where Admin Center is used strategically, definitely a great choice.
But two problems remain: As a consultant, I can’t install software at every client, and if Admin Center happens to be running, my English templates fail on German systems.

Still, I was so incredibly hooked by the template idea and the SQL Server possibilities that 4 weeks of after-work crunchtime were spinning in my head. So let me introduce my first module in the PowerShell Gallery:

psTerminalPerfCounter 0.1.0-preview A PowerShell module for displaying real-time graphs of Windows Performance Counters directly in the terminal console. This module provides an easy way to visualize system performance metrics without requiring external graphing tools or GUI applications by using templates and multilanguage support.

You’ll find all technical details and development status in the repository – I just want to show the different possibilities here.

Main Features

100% PowerShell

• no external dependencies

Terminal Graphics

• obviously it’s not a real engine, the more counters the choppier it gets, but it’s sufficient
• The foundation comes from Prateek Singh solution. Without finding this, I would have had to solve this problem first, for which I probably wouldn’t have had time. THANKS!!!

Configuration Templates

• every output element is controlled via configuration files
• flexible, portable

Data Output Customization

• each counter in the configuration file can use its own output
  • Table, Graph, or Both
• arbitrary axis scaling in steps and max values
• arbitrary value coloring based on user-defined ColorMap per counter
• value conversion via configuration file (Byte -> KB -> MB -> GB)

Language Independent

• configuration files are based on counter IDs, not paths
  • portable, regardless of system language translation from ID to counter path happens at runtime
  • no external dependencies
• I had no idea this was possible with Windows built-in tools. Here too I stumbled across a blog at PowerShell.ONE by chance. Again, a big THANKS!!! My original solution had multiple language variants (DE, EN, FR, ES) which would be set by reading system locale.

Demo with CPU Configuration

# Install module with required dependency (GripDevJsonSchemaValidator)
Install-Module -Name psTerminalPerfCounter -AllowPrerelease

# Import the module
Import-Module psTerminalPerfCounter

# Start Default Cpu Configuration
Start-tpcMonitor -ConfigName CPU

When loading the configuration, counter IDs are translated to counter paths and tested

If successful, the first samples are collected so a graph can be displayed

Thats IT!

Within 10 seconds, 2 Performance Counters running, no installation, no language issues.

Demo Counter Translation

# Translate ID -> Path
Get-tpcPerformanceCounterInfo 238-6

# Search Counter -> Including ID
Get-tpcPerformanceCounterInfo "Queue"

Output is heavily truncated since the ResultSet is enormous

# Search Counter -> Including ID
Get-tpcPerformanceCounterInfo "Processor Queue"

What’s next?

The foundation works, the planned feature list is long, and what I really need for SQL Server is still far off. I hope I haven’t solved a problem that doesn’t exist, but this module simply addresses all the issues I’ve always had with Performance Counters, as mentioned above.

Furthermore, this is my first larger project that I’m developing publicly, so GitHub might not always meet expected standards. I’m always happy about feedback and suggestions.

The post psTerminalPerfCounter – SpeedUp your Performance Counters in Terminal first appeared on DBA von Nebenan.

• Changelog
• Documentation

Intro

Die Windows Performance Counter sind absolut mächtig, aber wenn es mal schnell gehen muss oder ich genau passend zu einem Problem ein Monitoring benötige, bin ich schnell genervt. Meistens nutze ich dann doch andere Möglichkeiten, PowerShell Native Get-Counter, CIM oder greife auf vorhandene Monitoring-Lösungen bei meinen Kunden zurück. Aber auch das geht nie AdHoc aber ich habe es akzeptiert.

Nun habe ich beim letzten DataSaturday Uwe Ricken beim Performance Tuning Workshop begleiten dürfen und auch er hat die Performance Counter noch mal klar als Musthave im Werkzeugkoffer eines jeden DBA benannt. Was mir bis dahin nicht bewusst war: SQL Server legt individuelle Counter wie Compile/sec, AdHoc Queries/sec usw. an.

Die Möglichkeiten, Abhängigkeiten direkt zu visualisieren – endlos. Aber wie lange soll ich da sitzen, bis ich das im Windows Performance Monitor abgebildet habe, am besten Adhoc bei einem Kunden?

Uwe zeigte die Möglichkeiten im Windows Admin Center auf, welches Templates ermöglicht, die man flexibel auf Servern nutzen kann. Für System oder Umgebungen, in denen das Admin Center strategisch genutzt wird, definitiv eine sehr gut Wahl.

Aber zwei Probleme bleiben: Als Berater kann ich nicht bei jedem Kunden erst Software installieren und wenn das Admin Center doch läuft, scheitern meine englischen Templates an deutschen Systemen.

Nun war ich trotzdem so unglaublich angefixt von der Template-Idee und den Sql Server Möglichkeiten, dass nach Feierabend 4 Wochen Crunchtime im Kopf waren. Somit möchte ich euch an dieser Stelle mein erstes Modul in der PowerShell Gallery vorstellen

Die technischen Details, Entwicklungsstand findet ihr alle im Repository, ich möchte hier einfach die verschiedenen Möglichkeiten zeigen.

Main Features

100% PowerShell

• keine externen Abhängigkeiten

Terminal-Grafiken

• natürlich ist es keine richtige Engine, je mehr Counter desto Hakeliger wird es, aber es reicht
• Als Basis dient die Lösung von Prateek Singh. Ohne diesen Fund hätte ich wohl dieses Problem erst lösen müssen, wofür ich vermutlich keine Zeit gehabt hätte. DANKE!!!

Configuration Templates

• jedes Element der Ausgabe wird über Configuration Files gesteuert
• flexibel, transportabel

Individualisierung der Datenausgaben

• für jeden Counter im Configuration-File kann eine eigene Ausgabe genutzt werden
  • Table, Graph oder Beide
• beliebige Skalierungen der Achsen in Steps und Max
• beliebige Einfärbung der Values auf Basis einer benutzerdefinierten ColorMap per Counter
• Konvertierung der Values per Configuration-File ( Byte -> KB -> MB -> GB )

Sprachunabhängig

• Configuration Files basieren nicht auf den Counter-Pfaden sondern IDs
• immer noch transportabel, egal welche Systemsprache
• Translation von ID zu Counterpfad erfolgt erst zur Laufzeit

• keine externen Abhängigkeiten
• Ich wusste gar nicht, dass dies möglich ist mit Windows Bordmitteln. Auch hier bin ich durch Zufall über einen Blog gestolpert bei PowerShell.ONE. Auch hier ein dickes DANKE!!! Meine eigentliche Lösung sah mehrere Sprachvarianten ( DE, EN, FR, ES) vor, welche dann per auslesen der Systemlokalen gesetzt wurden.

Demo mit CPU Configuration

# Install module with required dependency (GripDevJsonSchemaValidator)
Install-Module -Name psTerminalPerfCounter -AllowPrerelease

# Import the module
Import-Module psTerminalPerfCounter

# Start Default Cpu Configuration
Start-tpcMonitor -ConfigName CPU

Beim Laden der Konfiguration werden die Counter IDs zu Counterpfaden übersetzt und getestet

Wenn das erfolgreich war, werden die ersten Samples gesammelt, damit ein Graph angezeigt werden kann

Thats IT!

Innerhalb von 10 Sekunden 2 Performance Counter am Laufen, ohne Installation, ohne Sprachprobleme.

Demo Counter Translation

# Translate ID -> Path
Get-tpcPerformanceCounterInfo 238-6

# Search Counter -> Including ID
Get-tpcPerformanceCounterInfo "Queue"

Die Ausgabe ist stark beschnitten, da das ResultSet enorm ist

# Search Counter -> Including ID
Get-tpcPerformanceCounterInfo "Processor Queue"

Wie geht’s weiter?

Die Basis läuft, die planned Feature Liste ist lang und das, was ich wirklich brauche bezüglich Sql Server ist noch in weiter Ferne. Ich hoffe ich habe nicht ein Problem bedient, was es gar nicht gibt, aber dieses Modul adressiert einfach alle Probleme, die ich schon immer mit den Performance Countern hatte, siehe oben.

Weiterhin ist das mein erstes größeres Projekt, was ich Public entwickle, somit könnte Github nicht immer den erwarteten Standards entsprechen. Über Feedback und Hinweise freue ich mich immer.

The post psTerminalPerfCounter – SpeedUp your Performance Counters in Terminal first appeared on DBA von Nebenan.

I’ve always used PowerShell following the same pattern, that’s roughly how my learning path followed the PowerShell Best Practices.

• Quick and Dirty one-liners in the console, nowadays Terminal
• Gradually, those one-liners evolved into PowerShell scripts with better organized one-liners
• Variables came along, then functions, reusability increased
• Functions became modules, persistent data storage in JSON and technologically that was the end for a while
• The last highlight was threading and runspaces

I’ve been operating on these last two levels for quite a long time now, of course getting more efficient and generally my PowerShell knowledge became broader.

During this development, however, I noticed a problem: I’m a very organized person, at least in my professional environment 😉, and so should my code be, structured. I don’t think much of Clean Code, comments are just important at certain points, for me, for others, for my customers. Besides comments, structure is also important – what good do comments do me in a ‚bucket of chars‘? I also love symmetrical code, yeah go ahead and laugh, but it immediately makes clear what’s a variable, what’s an assignment and what’s the value. When I see something like this…

$userInfo = @{
   Name = $varSurename
   Address = $varStreet
   Data = $varRandomLongVar
}

$configSettings = @{
   ServerName = 'localhost'
   Port = 5432
   Database = 'mydb'
   Timeout = 30
}

$employee = @{
   Personal = @{
       FirstName = $varSurename
       LastName = 'Doe'
       Street = $varStreet
   }
   Work = @{
       Department = 'IT'
       Position = 'Developer'
   }
}

… my insides turn outward 🤣 Maybe it’s also a disease. This is a normal writing style that’s considered clean, I know, but it should look like this …

$userInfo = @{
   Name 	= $varSurename
   Address 	= $varStreet
   Data 	= $varRandomLongVar
}

$configSettings = @{
   ServerName 	= 'localhost'
   Port 		= 5432
   Database 	= 'mydb'
   Timeout 		= 30
}

$employee = @{
   Personal = @{
       FirstName 	= $varSurename
       LastName 	= 'Doe'
       Street 		= $varStreet
   }
   Work 	= @{
       Department 	= 'IT'
       Position 	= 'Developer'
   }
}

$users = @(
   @{ Name = 'Alice'; 		Role = 'Admin' }
   @{ Name = $varSurename; 	Role = 'User' }
)

Anyway, that’s not what this is about. It’s basically the case that structure and order gradually decrease in larger projects and classes play exactly into this topic. But why only now? Classes have existed since PowerShell 5.0.

AI Assisted Coding

Of course I was an early adopter of all the AI chatbots and was amazed at what ChatGPT could already do 2 years ago. Of course the code, regardless of language, was unusable, but definitely useful for knowledge generation. As the quality progressed, the code got better and the solution approaches became more and more interesting.

At some point, classes started appearing in the suggestions and I consistently ignored them 😝. Through my C# journeys, I knew that classes are simply the standard, but you should fundamentally know what you want to do with them in the project to design them cleanly. And I didn’t want to make that effort.

The New Project

It was time to adapt a 4-year-old solution to new requirements, as is sometimes the case. Since my knowledge doesn’t stand still either, after briefly skimming through the code, I decided:

I’M NOT TOUCHING THIS ANYMORE, THIS ALL HAS TO BE NEW!!

Now I was in the relaxed position that everything was available for the solution:

• Program flow chart
• Function descriptions
• Programmatic solution of the required functions at the lowest level
• 4 years of lessons learned

So I only had to worry about orchestrating all the steps and decided to give classes a chance. In theory, this is namely the cleanest and most structured way to code.

The result hasn’t completely changed my way of coding, but it has sustainably changed it – but more on that later.

Conclusion After 5 Weeks in the Project

Classes in PowerShell are so incredibly simple, so structured, so beautiful❤️. Of course the use case has to fit, since the implementation initially requires more structure, but when that’s given, there will be no way around classes for me anymore.

Why This Article, Aren’t There Enough Already?

There are some articles about classes in PowerShell and object orientation, but still this topic is hardly covered in a classic tutorial. It’s always the functions and you have to know about this topic to find it. So I’m simply writing another article, also in german this time, to maybe reach one or the other additionally, because…

Background Info on PowerShell Classes – OOP Since Version 5.0

Classes have existed in PowerShell since PowerShell 5.0, so 2016… and I only learned about them a year ago 🤦‍♂️. PowerShell classes bring object-oriented programming concepts to PowerShell and thus also have all the basic features of a class.

• Properties: Properties are strongly typed and support most validation attributes like [ValidateNotNull()], [ValidateRange()], etc.
• Methods: Methods are functions bound to an object and must explicitly define the return type
• Constructors: Enable initialization of objects with specific values
• Inheritance: Allows creating new classes from existing classes and extending their functionality

A class, after loading, is its own data type – more on that later.

And How Does This Work Now?

I still remember how I struggled with OOP many years ago and it’s generally assumed that rather admins than full-blood software developers initially deal with PowerShell. So I’ll try to keep it totally simple.

I’ll take a fictional module that queries server properties via remoting and evaluates them locally, a classic admin task.

ATTENTION: Of course this example is very constructed and not necessarily practical, but in my opinion it shows the relationships quite well.

This PowerShell classes tutorial shows you the most important concepts for object-oriented programming with PowerShell.

Properties

A class has a firmly defined set of properties at all times. This cannot be changed at runtime, but must be described in the definition of the class.

The Class

class Server {
# All Possible properties for the Server class
    [string]        $ServerName
    [string]        $Status
    [ipaddress]     $IP 
    [string]        $Location
    [datetime]      $LastBootTime
    [string]        $OperatingSystem
# -------------------------------------------
}

Constructors

A constructor creates the instance of a class. The class can receive default values, or the constructor expects parameters. In our case, a server name makes sense. So I give the property ServerName a value directly when loading.

class Server {
# All Possible properties for the Server class
    [string]        $ServerName
    [string]        $Status
    [ipaddress]     $IP 
    [string]        $Location
    [datetime]      $LastBootTime
    [string]        $OperatingSystem
# -------------------------------------------

    # Constructor
    Server([string]$name) {
        $this.ServerName = $name
    }
}

Now we have a class, but how do we get a server in there? By loading the class into a variable and preferably also dynamically for all servers.

class Server {
# All Possible properties for the Server class
    [string]        $ServerName
    [string]        $Status
    [ipaddress]     $IP 
    [string]        $Location
    [datetime]      $LastBootTime
    [string]        $OperatingSystem
# -------------------------------------------

    # Constructor
    Server([string]$name) {
        $this.ServerName = $name
    }
}

$serverlist = @('Server1','Server2','Server3')

foreach ( $server in $serverlist ) {
    
    # Create a new Server object for each server name
    New-Variable -Name "obj_$server" -Value ([Server]::new($server)) -Force

}

Methods

Methods make classes really interesting in my opinion. Methods are the functions with which I can manipulate properties of classes or generate RETURNS based on arguments that I add to the call. Here I already specify the type of return in the method definition. VOID thus logically creates no return.

class Server {
    [string]        $ServerName
    [string]        $Status
    [ipaddress]     $IP 
    [string]        $Location
    [datetime]      $LastBootTime
    [string]        $OperatingSystem

    Server([string]$name) {
        $this.ServerName = $name
    }

    [void] GetServerInfo() {

        try {

            $osInfo = Invoke-Command -ComputerName $this.ServerName -ScriptBlock {
                Get-CimInstance Win32_OperatingSystem | Select-Object Caption, LastBootUpTime
            } -ErrorAction Stop

            $this.IP = Invoke-Command -ComputerName $this.ServerName -ScriptBlock {
                (Get-NetIPAddress -AddressFamily IPv4 | Where-Object {$_.IPAddress -notlike '169.*'} | Select-Object -First 1).IPAddress
            } -ErrorAction Stop

            $this.OperatingSystem = $osInfo.Caption
            $this.LastBootTime    = $osInfo.LastBootUpTime
            $this.Status          = "Online"

        } catch {

            $this.Status = "Offline"

        }
    }
}

$serverlist = @('Server1','Server2','Server3')

foreach ($server in $serverlist) {
    New-Variable -Name "obj_$server" -Value ([Server]::new($server)) -Force
}

$obj_Server1.GetServerInfo()
$obj_Server2.GetServerInfo()
$obj_Server3.GetServerInfo()

Here I’ve inserted the method GetServerInfo(), which now collects the information about the server. I don’t need to pass an argument or start a cmdlet, since the instance (server name) of the class (Server) has inherited everything. I don’t need external functions, variables or anything else, everything is available in the class. ❤️ Following an example from the LAB:

And Now, Where’s the Benefit?

Of course this isn’t the most optimal use case, but it’s understandable. One possibility would be to create a logging class. Here from my project:

class PatchLogger {
     [string]        $ServerName
     [string]        $LogPathServer
     [string]        $LogLevel = 'INFO'
     [hashtable]     $LogTargets
     [bool]          $ConsoleOutput
     [bool]          $StreamOutput
     [string]        $VerbosePreference
     [string]        $DebugPreference

     # Constructor
     PatchLogger(	[string]$LogPathServer,
					[string]$ServerName,
					[string]$MessageFile,
					[string]$ErrorFile,
					[string]$VerboseFile,
					[string]$DebugFile,
					[string]$SqlServerFile,
					[bool]$ConsoleOutput 	= $true,
					[bool]$StreamOutput 	= $false) {
					
          $this.LogPathServer   = $LogPathServer
          $this.ServerName      = $ServerName
          $this.ConsoleOutput   = $ConsoleOutput
          $this.StreamOutput    = $StreamOutput
          $this.LogTargets      = @{
               Main           = $MessageFile
               Error          = $ErrorFile
               Verbose        = $VerboseFile
               Debug          = $DebugFile
               SqlServer      = $SqlServerFile
          }

          $this.VerbosePreference = $Global:VerbosePreference
          $this.DebugPreference   = $Global:DebugPreference

          if ( -not (Test-Path $this.LogPathServer) ) {
               New-Item -Path $this.LogPathServer -ItemType Directory -Force | Out-Null
          }
    }
	
}

An instance of the class is loaded directly into the variable $PatchLogger when the module loads, and from now on I can start right away with $PatchLogger.Info($message). How? Such a short command with such a complex class? Let’s get to the last thing, which in my opinion is the advantage par excellence: Overloading.

Overloading

Overloading means nothing other than the number of arguments I pass to a method. Based on the number, the engine can distinguish which method is used, since I can have several with the same name. The technical term would be Method Overloading.

The added value lies in the fact that I don’t have to work with BoundParams, Switch or IF loops like with functions. When a helper method is called with only one argument, the missing arguments are filled in internally and the main method is called.

Let’s take the example $PatchLogger.Info($message)

# Hauptmethode
[hashtable] WriteLog([string]$Level, [string]$Message, [string]$MessageCode, [int]$Severity, [string]$Target, [bool]$ReturnObject) {...}

# Helfermethode
[hashtable] Info([string]$Message) {
      return $this.WriteLog('INFO', $Message, $null, 0, 'Main', $true)
}

# Helfermethode 2
[hashtable] Info([string]$Message, [string]$MessageCode) {
      return $this.WriteLog('INFO', $Message, $MessageCode, 0, 'Main', $true)
}

What will be most needed in a large module? A simple message to the main log, without message code and frills. So the helper method calls the main method with the default values that do exactly that.

Let’s look at helper method 2. This expects 2 arguments, namely a MessageCode. Now I can write a registered message with $PatchLogger.Info(„Process XY completed“,“I0002″).

Of course I can also implement all this with functions, but I don’t think it’s as structured and pretty.

class PatchLogger {
     [string]        $ServerName
     [string]        $LogPathServer
     [string]        $LogLevel = 'INFO'
     [hashtable]     $LogTargets
     [bool]          $ConsoleOutput
     [bool]          $StreamOutput
     [string]        $VerbosePreference
     [string]        $DebugPreference

     # Constructor
     PatchLogger([string]$LogPathServer, [string]$ServerName, [string]$MessageFile, [string]$ErrorFile, [string]$VerboseFile, [string]$DebugFile, [string]$SqlServerFile, [bool]$ConsoleOutput = $true, [bool]$StreamOutput = $false) {
          $this.LogPathServer   = $LogPathServer
          $this.ServerName      = $ServerName
          $this.ConsoleOutput   = $ConsoleOutput
          $this.StreamOutput    = $StreamOutput
          $this.LogTargets      = @{
               Main           = $MessageFile
               Error          = $ErrorFile
               Verbose        = $VerboseFile
               Debug          = $DebugFile
               SqlServer      = $SqlServerFile
          }

          $this.VerbosePreference = $Global:VerbosePreference
          $this.DebugPreference   = $Global:DebugPreference

          if ( -not (Test-Path $this.LogPathServer) ) {
               New-Item -Path $this.LogPathServer -ItemType Directory -Force | Out-Null
          }
     }

     [void] UpdatePreferences([string]$VerbosePreference, [string]$DebugPreference) {
          $this.VerbosePreference = $VerbosePreference
          $this.DebugPreference   = $DebugPreference
     }

     # Central WriteLog method - all other methods call this one
     [object] WriteLog([string]$Level, [string]$Message, [string]$MessageCode, [int]$Severity, [string]$Target, [bool]$ReturnObject) {

          $timestamp          = Get-Date -Format "yyyy-MM-dd HH:mm:ss"
          $severityText       = if ($Severity -ne 9999) { "S$Severity" } else { "" }
          $messageCodeText    = if ($MessageCode) { " $MessageCode" } else { "" }

          $paddedLevel        = "{0,-9}" -f "[$Level]"

          $additionalInfo     = "$severityText$messageCodeText"
          $logEntry           = if ( $level -eq 'BLANK' ) {
                                   ""
                                } elseif ( $Level -notin @('VERBOSE','DEBUG') -and -not [string]::IsNullOrEmpty($additionalInfo) ) {
                                   "[$timestamp] $paddedLevel [$($this.ServerName)] $Message ($additionalInfo)"
                                } else {
                                   "[$timestamp] $paddedLevel [$($this.ServerName)] $Message"
                              }

          $targetFile = $this.LogTargets[$Target]
          if ( $targetFile ) {
               try {
                    Add-Content -Path $targetFile -Value $logEntry -Encoding UTF8

                    $verboseFile = $this.LogTargets['Verbose']
                    if ( $verboseFile -and $Level -ne 'VERBOSE' ) {
                         Add-Content -Path $verboseFile -Value $logEntry -Encoding UTF8 # for unbroken verbose stream
                    }

               } catch {
                    Invoke-ScriptError $_
               }
          }

          if ( $this.ConsoleOutput ) {
               switch ( $Level ) {
                    'ERROR'        { Write-Host $logEntry -ForegroundColor Red }
                    'WARNING'      { Write-Host $logEntry -ForegroundColor Yellow }
                    'INFO'         { Write-Host $logEntry -ForegroundColor Green }
                    'BLANK'        { Write-Host $logEntry}
                    'VERBOSE'      {
                         if ( $this.VerbosePreference -ne 'SilentlyContinue' ) {
                              Write-Host $logEntry -ForegroundColor Cyan
                         }
                    }
                    'DEBUG'        {
                         if ( $this.DebugPreference -ne 'SilentlyContinue' ) {
                              Write-Host $logEntry -ForegroundColor Magenta
                         }
                    }
               }
          }

          # PowerShell streams for integration - only if explicitly enabled
          if ( $this.StreamOutput ) {
               switch ($Level) {
                    'ERROR'   { Write-Error       $Message -ErrorAction Continue }
                    'WARNING' { Write-Warning     $Message }
                    'VERBOSE' { Write-Verbose     $Message }
                    'DEBUG'   { Write-Debug       $Message }
               }
          }

          # Return object only when requested
          if ( $ReturnObject ) {
               return @{
                    HasError    = $Level -eq 'ERROR'
                    HasWarning  = $Level -eq 'WARNING'
                    MessageCode = if ( $MessageCode ) { $MessageCode } else { $null }
                    Message     = $Message
                    Severity    = $Severity
                    Level       = $Level
                    Target      = $Target
               }
          }

          return $null
     }

     # BLANK Line
     [void] BlankLine() {
          $this.WriteLog('BLANK', '', $null, 0, 'Main', $false)
     }

     # INFO Methods - standard return hashtable
     [hashtable] Info([string]$Message) {
          return $this.WriteLog('INFO', $Message, $null, 0, 'Main', $true)
     }

     [hashtable] Info([string]$Message, [string]$MessageCode) {
          return $this.WriteLog('INFO', $Message, $MessageCode, 0, 'Main', $true)
     }

     # INFO NoReturn
     [void] InfoNoReturn([string]$Message) {
          $this.WriteLog('INFO', $Message, $null, 0, 'Main', $false)
     }

     [void] InfoNoReturn([string]$Message, [string]$MessageCode) {
          $this.WriteLog('INFO', $Message, $MessageCode, 0, 'Main', $false)
     }

     # WARNING Methods - standard return hashtable
     [hashtable] Warning([string]$Message) {
          return $this.WriteLog('WARNING', $Message, $null, 1, 'Main', $true)
     }

     [hashtable] Warning([string]$Message, [string]$MessageCode) {
          return $this.WriteLog('WARNING', $Message, $MessageCode, 1, 'Main', $true)
     }

     # WARNING NoReturn
     [void] WarningNoReturn([string]$Message) {
          $this.WriteLog('WARNING', $Message, $null, 1, 'Main', $false)
     }

     [void] WarningNoReturn([string]$Message, [string]$MessageCode) {
          $this.WriteLog('WARNING', $Message, $MessageCode, 1, 'Main', $false)
     }

     # ERROR Methods - standard return hashtable
     [hashtable] Error([string]$Message) {
          return $this.WriteLog('ERROR', $Message, $null, 2, 'Error', $true)
     }

     [hashtable] Error([string]$Message, [string]$MessageCode) {
          return $this.WriteLog('ERROR', $Message, $MessageCode, 2, 'Error', $true)
     }

     # ERROR NoReturn
     [void] ErrorNoReturn([string]$Message) {
          $this.WriteLog('ERROR', $Message, $null, 2, 'Error', $false)
     }

     [void] ErrorNoReturn([string]$Message, [string]$MessageCode) {
          $this.WriteLog('ERROR', $Message, $MessageCode, 2, 'Error', $false)
     }

     # VERBOSE & DEBUG - NoReturn
     [void] Verbose([string]$Message) {
          $this.WriteLog('VERBOSE', $Message, $null, 0, 'Verbose', $false)
     }

     [void] Debug([string]$Message) {
          $this.WriteLog('DEBUG', $Message, $null, 0, 'Debug', $false)
     }

     # Step/SQL/AG Methods - NoReturn
     [void] StepStart([int]$Step, [string]$StepName) {
          $this.BlankLine()
          $message = "========================= STEP $Step START: $StepName ========================="
          $this.WriteLog('INFO', $message, $null, 9999, 'Main', $false)
     }

     [void] StepEnd([int]$Step, [string]$StepName, [bool]$Success) {
          $status   = if ( $Success ) { "SUCCESS" } else { "FAILED" }
          $message  = "========================= STEP $Step END: $StepName - $status ========================="
          $this.WriteLog('INFO', $message, $null, 9999, 'Main', $false)
          $this.BlankLine()
     }

}

Summary

PowerShell classes revolutionize how you structure larger projects. Available since PowerShell 5.0, they offer object-oriented programming with properties, methods, constructors, and method overloading. The initial extra effort pays off through clean, maintainable code – especially for modules and more complex function collections.

The most important advantages at a glance:

• Strongly typed properties with validation
• Encapsulated functionality through methods
• Elegant overloading instead of complex parameter logic and a structure that remains understandable even after months

For daily-doing scripts, the classic approach remains more practical, but as soon as reusability and structure become important, there’s no way around classes for me anymore. 🫡

The post PowerShell Classes for Beginners – Structured Code Instead of Function Chaos first appeared on DBA von Nebenan.

Seit eh und je nutze ich PowerShell nach Schema F, so ungefähr war auch mein Lernpfad entsprechend PowerShell Best Practices.

• Quick and Dirty Einzeiler in der Konsole, mittlerweile Terminal
• Nach und nach wurden aus den Einzeilern PowerShell Scripte mit besser organisierten Einzeilern
• Es kamen Variablen, dann Funktionen, die Wiederverwendbarkeit stieg
• Aus Funktionen wurden Module, persistente Datenhalden in Json und technologisch war das erstmal das Ende
• Das letzte HighLight war Threading und Runspaces

Auf den letzten beiden Ebenen habe ich mich nun sehr lange bewegt, natürlich immer effizienter und allgemein wurde das PowerShell Wissen breiter.

Während dieser Entwicklung merkte ich jedoch ein Problem: Ich bin ein sehr organisierter Mensch, zumindestens im beruflichen Umfeld 😉, und so soll auch mein Code sein, strukturiert. Von Clean Code halte ich nichts, Kommentare sind einfach punktuell wichtig, für mich, für andere, für meine Kunden. Neben Kommentaren ist aber auch die Struktur wichtig, was bringen mir Kommentare an einem ‚Bucket of Chars‘ ? Ebenfalls liebe ich symmetrischen Code, ja lacht ruhig, aber es macht sofort ersichtlich, was ist eine Variable, was eine Zusweisung und was der Value. Wenn ich sowas sehe…

$userInfo = @{
   Name = $varSurename
   Address = $varStreet
   Data = $varRandomLongVar
}

$configSettings = @{
   ServerName = 'localhost'
   Port = 5432
   Database = 'mydb'
   Timeout = 30
}

$employee = @{
   Personal = @{
       FirstName = $varSurename
       LastName = 'Doe'
       Street = $varStreet
   }
   Work = @{
       Department = 'IT'
       Position = 'Developer'
   }
}

… da kehrt sich mein Innerstes nach Außen 🤣 Ist vielleicht auch eine Krankheit. Dies ist eine normale Schreibweise, die als sauber gilt, ich weiß, aber das sollte doch so aussehen..

$userInfo = @{
   Name 	= $varSurename
   Address 	= $varStreet
   Data 	= $varRandomLongVar
}

$configSettings = @{
   ServerName 	= 'localhost'
   Port 		= 5432
   Database 	= 'mydb'
   Timeout 		= 30
}

$employee = @{
   Personal = @{
       FirstName 	= $varSurename
       LastName 	= 'Doe'
       Street 		= $varStreet
   }
   Work 	= @{
       Department 	= 'IT'
       Position 	= 'Developer'
   }
}

$users = @(
   @{ Name = 'Alice'; 		Role = 'Admin' }
   @{ Name = $varSurename; 	Role = 'User' }
)

Wie auch immer, darum solls hier nicht gehen. Es ist grundsätzlich so, dass die Struktur und Ordnung bei größeren Projekten nach und nach abnimmt und Klassen genau auf dieses Thema einspielen. Aber warum jetzt erst? Klassen gibt es seit PowerShell 5.0 .

AI Assisted Coding

Natürlich war ich early Adopter der ganzen KI Chatbots und war erstaunt, was ChatGPT vor 2 Jahren schon konnte. Natürlich war der Code, egal welche Sprache, unbrauchbar, aber für Wissenserzeugung allemal nützlich. So wurde mit fortlaufender Qualität der Code besser und auch die Lösungswege wurden immer interessanter.

Irgendwann sind in den Vorschlägen Klassen aufgetaucht und ich habe es konsequent ignoriert 😝. Durch meine C# Reisen wusste ich, dass Klassen einfach der Standard sind, man aber schon grundlegend Wissen sollte, was ich damit machen will im Projekt, um diese sauber zu entwerfen. Und diesen Aufwand wollte ich mir nicht machen.

Das neue Projekt

Es war an der Zeit, eine 4 Jahre alte Lösung an neue Anforderungen anzupassen, wie das halt manchmal so der Fall ist. Da mein Wissen ja auch nicht stehen bleibt, habe ich nach kurzem überfliegen des Codes entschieden:

DAS FASSE ICH NICHT MEHR AN, DAS MUSS ALLES NEU!!

Nun war ich in der entspannten Lage, dass für die Lösung alles vorhanden war

• Programmablaufplan (PAP)
• Funktionsbeschreibungen
• Programmatische Lösung der benötigten Funktionen auf unterster Ebene
• 4 Jahre Lessons learned

Somit musste ich mich nur um die Orchestrierung aller Schritte kümmern und habe entschieden, dass ich den Klassen mal eine Chance geben werde. In der Theorie ist dies nämlich die sauberste und strukturierteste Möglichkeit zu Coden.

Das Ergebnis hat meine Art zu Coden nicht völlig, aber nachhaltig verändert – aber dazu später mehr.

Fazit nach 5 Wochen im Projekt

Klassen in PowerShell sind so unglaublich simpel, so strukturiert, so wunderschön❤️. Natürlich muss der UseCase passen, da die Implementierung initial mehr Struktur verlangt, aber wenn dieser gegeben ist, wird für mich kein Weg mehr an Klassen vorbei führen.

Warum dieser Artikel, gibt doch genug?

Es gibt einige Artikel über Klassen in PowerShell und Objektorientierung aber trotzdem wird dieses Thema kaum in einem klassischen Tutorial behandelt. Es sind immer die Funktionen und man muss um dieses Thema wissen um es zu finden. Somit schreibe ich einfach noch einen Artikel, auch mal in deutsch, um vielleicht doch den ein oder anderen zusätzlich zu erreichen, weil…

Hintergrundinfos zu PowerShell Klassen – OOP seit Version 5.0

Klassen gibt es in PowerShell seit PowerShell 5.0 also 2016… und ich habe vor einem Jahr erst davon erfahren 🤦‍♂️. PowerShell Klassen bringen objektorientierte Programmierkonzepte in PowerShell und haben somit auch haben alle grundlegenden Features einer Klasse.

• Eigenschaften (Properties): Eigenschaften sind stark typisiert und unterstützen die meisten Validierungsattribute wie [ValidateNotNull()], [ValidateRange()] etc.
• Methoden: Methoden sind Funktionen, die an ein Objekt gebunden sind und explizit den Rückgabetyp definieren müssen
• Konstruktoren: Ermöglichen die Initialisierung von Objekten mit spezifischen Werten
• Vererbung: Erlaubt es, neue Klassen von bestehenden Klassen zu erstellen und deren Funktionalität zu erweitern

Eine Klasse ist nach dem Laden ein eigener Datentyp, später mehr dazu.

Und wie funktioniert das jetzt?

Ich weiß noch, wie ich mich vor vielen Jahren mit OOP schwer tat und allgemein davon auszugehen ist, dass sich doch eher Admins als vollblut Software Entwickler initial mit PowerShell auseinander setzen. Somit versuche ich es mal total simpel.

Ich nehme mal ein fiktives Modul, welche per Remoting Serverproperties abfragt und lokal auswertet, ein klassischer AdminTask.

ACHTUNG: Natürlich ist dieses Beispiel sehr konstruiert und nicht zwingend praktikabel aber es zeigt meiner Meinung nach die Zusammenhänge recht gut.

Dieses PowerShell Klassen Tutorial zeigt dir die wichtigsten Konzepte für objektorientierte Programmierung mit PowerShell.

Eigenschaften (Properties)

Eine Klasse hat zu jeder Zeit ein fest definierten Satz an Eigenschaften. Dieser kann zur Laufzeit nicht geändert werden, sondern muss in der Definition der Klasse beschrieben werden.

Die Klasse

class Server {
# All Possible properties for the Server class
    [string]        $ServerName
    [string]        $Status
    [ipaddress]     $IP 
    [string]        $Location
    [datetime]      $LastBootTime
    [string]        $OperatingSystem
# -------------------------------------------
}

Konstruktoren

Ein Konstruktor erzeugt die Instanz einer Klasse. Dabei kann die Klasse default Values erhalten, oder der Konstruktor erwartet Parameter. In unserem Fall ist ein Servername sinnvoll. Somit gebe ich der Property ServerName direkt beim Laden einen Wert.

class Server {
# All Possible properties for the Server class
    [string]        $ServerName
    [string]        $Status
    [ipaddress]     $IP 
    [string]        $Location
    [datetime]      $LastBootTime
    [string]        $OperatingSystem
# -------------------------------------------

    # Constructor
    Server([string]$name) {
        $this.ServerName = $name
    }
}

Nun haben wir zwar ein Klasse aber wie bekommen wir nun einen Server da rein? Indem wir die Klasse in eine Variable laden und am besten auch noch dynamisch für alle Server.

class Server {
# All Possible properties for the Server class
    [string]        $ServerName
    [string]        $Status
    [ipaddress]     $IP 
    [string]        $Location
    [datetime]      $LastBootTime
    [string]        $OperatingSystem
# -------------------------------------------

    # Constructor
    Server([string]$name) {
        $this.ServerName = $name
    }
}

$serverlist = @('Server1','Server2','Server3')

foreach ( $server in $serverlist ) {
    
    # Create a new Server object for each server name
    New-Variable -Name "obj_$server" -Value ([Server]::new($server)) -Force

}

Methoden

Methoden machen meiner Meinung nach die Klassen erst richtig interessant. Methoden sind die Funktionen mit denen ich Eigenschaften der Klassen manipulieren kann oder auf Basis von Argumenten, welche ich dem Aufruf hinzufüge, RETURNS erzeugen kann. Hierbei gebe ich bereits in der Methodendefintion den Typ der Rückgabe an. VOID erzeugt somit logischerweise keine Rückgabe.

class Server {
    [string]        $ServerName
    [string]        $Status
    [ipaddress]     $IP 
    [string]        $Location
    [datetime]      $LastBootTime
    [string]        $OperatingSystem

    Server([string]$name) {
        $this.ServerName = $name
    }

    [void] GetServerInfo() {

        try {

            $osInfo = Invoke-Command -ComputerName $this.ServerName -ScriptBlock {
                Get-CimInstance Win32_OperatingSystem | Select-Object Caption, LastBootUpTime
            } -ErrorAction Stop

            $this.IP = Invoke-Command -ComputerName $this.ServerName -ScriptBlock {
                (Get-NetIPAddress -AddressFamily IPv4 | Where-Object {$_.IPAddress -notlike '169.*'} | Select-Object -First 1).IPAddress
            } -ErrorAction Stop

            $this.OperatingSystem = $osInfo.Caption
            $this.LastBootTime    = $osInfo.LastBootUpTime
            $this.Status          = "Online"

        } catch {

            $this.Status = "Offline"

        }
    }
}

$serverlist = @('Server1','Server2','Server3')

foreach ($server in $serverlist) {
    New-Variable -Name "obj_$server" -Value ([Server]::new($server)) -Force
}

$obj_Server1.GetServerInfo()
$obj_Server2.GetServerInfo()
$obj_Server3.GetServerInfo()

Hier habe ich die Methode GetServerInfo() eingefügt, die nun die Informationen zum Server sammelt. Dabei muss ich weder ein Argument mitgeben oder ein Cmdlet starten, da die Instanz (Servername) der Klasse (Server) alles vererbt bekommen hat. Ich brauche keine externen Funktionen, Variablen oder sonst was, alles in der Klasse vorhanden. ❤️ Folgend ein Beispiel aus dem LAB

Und jetzt, wo ist der Nutzen?

Natürlich ist das nicht der optimalste Use Case, dafür verständlich. Eine Möglichkeit wäre, eine LoggingKlasse zu erstellen. Anbei aus meinem Projekt:

class PatchLogger {
     [string]        $ServerName
     [string]        $LogPathServer
     [string]        $LogLevel = 'INFO'
     [hashtable]     $LogTargets
     [bool]          $ConsoleOutput
     [bool]          $StreamOutput
     [string]        $VerbosePreference
     [string]        $DebugPreference

     # Constructor
     PatchLogger(	[string]$LogPathServer,
					[string]$ServerName,
					[string]$MessageFile,
					[string]$ErrorFile,
					[string]$VerboseFile,
					[string]$DebugFile,
					[string]$SqlServerFile,
					[bool]$ConsoleOutput 	= $true,
					[bool]$StreamOutput 	= $false) {
					
          $this.LogPathServer   = $LogPathServer
          $this.ServerName      = $ServerName
          $this.ConsoleOutput   = $ConsoleOutput
          $this.StreamOutput    = $StreamOutput
          $this.LogTargets      = @{
               Main           = $MessageFile
               Error          = $ErrorFile
               Verbose        = $VerboseFile
               Debug          = $DebugFile
               SqlServer      = $SqlServerFile
          }

          $this.VerbosePreference = $Global:VerbosePreference
          $this.DebugPreference   = $Global:DebugPreference

          if ( -not (Test-Path $this.LogPathServer) ) {
               New-Item -Path $this.LogPathServer -ItemType Directory -Force | Out-Null
          }
    }
	
}

Eine Instanz der Klasse wird direkt beim Laden des Moduls in die Variable $PatchLogger geladen und ab jetzt kann ich mit $PatchLogger.Info($message) schon direkt loslegen. Wie? So ein kurzer Befehl bei einer so komplexen Klasse? Kommen wir zum letzten, was meiner Meinung nach der Vorteil schlechthin ist: Überladung.

Überladung

Überladung heisst nichts anderes als die Anzahl der Argumente, die ich einer Methode übergebe. Anhand der Anzahl kann die Engine unterscheiden, welche Methode genutzt wird, da ich mehrer mit den gleichen Namen haben kann. Der Fachbegriff wäre Method Overloading.

Der Mehrwert liegt darin, dass ich nicht wie bei Funktionen mit BoundParams, Switch oder IF SChleifen arbeiten muss. Wenn eine Helfer Methode mit nur einem Argument aufgerufen wird, werden intern die fehlenden Argumente aufgefüllt und die Hauptmethode aufgerufen.

Nehmen wir das Beispiel $PatchLogger.Info($message)

# Hauptmethode
[hashtable] WriteLog([string]$Level, [string]$Message, [string]$MessageCode, [int]$Severity, [string]$Target, [bool]$ReturnObject) {...}

# Helfermethode
[hashtable] Info([string]$Message) {
      return $this.WriteLog('INFO', $Message, $null, 0, 'Main', $true)
}

# Helfermethode 2
[hashtable] Info([string]$Message, [string]$MessageCode) {
      return $this.WriteLog('INFO', $Message, $MessageCode, 0, 'Main', $true)
}

Was wird das meiste sein, was ich ich einem großen Modul benötige? Eine einfache Message ins Main Log, ohne Messagecode und SchnickSchnack. Somit ruft die Helfermethode die Hauptmethode mit den Defaultwerten auf, die genau das bewirken.

Schauen wir uns Helfermethode 2 an. Diese erwartet 2 Argumente, nämlich einen MessageCode. Schon kann ich mit $PatchLogger.Info(„Prozess XY abgeschlossen“,“I0002″) eine registrierte Message schreiben.

Natürlich kann ich das auch alles mit Funktionen realisieren aber ich denke nicht so strukturiert und hübsch.

class PatchLogger {
     [string]        $ServerName
     [string]        $LogPathServer
     [string]        $LogLevel = 'INFO'
     [hashtable]     $LogTargets
     [bool]          $ConsoleOutput
     [bool]          $StreamOutput
     [string]        $VerbosePreference
     [string]        $DebugPreference

     # Constructor
     PatchLogger([string]$LogPathServer, [string]$ServerName, [string]$MessageFile, [string]$ErrorFile, [string]$VerboseFile, [string]$DebugFile, [string]$SqlServerFile, [bool]$ConsoleOutput = $true, [bool]$StreamOutput = $false) {
          $this.LogPathServer   = $LogPathServer
          $this.ServerName      = $ServerName
          $this.ConsoleOutput   = $ConsoleOutput
          $this.StreamOutput    = $StreamOutput
          $this.LogTargets      = @{
               Main           = $MessageFile
               Error          = $ErrorFile
               Verbose        = $VerboseFile
               Debug          = $DebugFile
               SqlServer      = $SqlServerFile
          }

          $this.VerbosePreference = $Global:VerbosePreference
          $this.DebugPreference   = $Global:DebugPreference

          if ( -not (Test-Path $this.LogPathServer) ) {
               New-Item -Path $this.LogPathServer -ItemType Directory -Force | Out-Null
          }
     }

     [void] UpdatePreferences([string]$VerbosePreference, [string]$DebugPreference) {
          $this.VerbosePreference = $VerbosePreference
          $this.DebugPreference   = $DebugPreference
     }

     # Central WriteLog method - all other methods call this one
     [object] WriteLog([string]$Level, [string]$Message, [string]$MessageCode, [int]$Severity, [string]$Target, [bool]$ReturnObject) {

          $timestamp          = Get-Date -Format "yyyy-MM-dd HH:mm:ss"
          $severityText       = if ($Severity -ne 9999) { "S$Severity" } else { "" }
          $messageCodeText    = if ($MessageCode) { " $MessageCode" } else { "" }

          $paddedLevel        = "{0,-9}" -f "[$Level]"

          $additionalInfo     = "$severityText$messageCodeText"
          $logEntry           = if ( $level -eq 'BLANK' ) {
                                   ""
                                } elseif ( $Level -notin @('VERBOSE','DEBUG') -and -not [string]::IsNullOrEmpty($additionalInfo) ) {
                                   "[$timestamp] $paddedLevel [$($this.ServerName)] $Message ($additionalInfo)"
                                } else {
                                   "[$timestamp] $paddedLevel [$($this.ServerName)] $Message"
                              }

          $targetFile = $this.LogTargets[$Target]
          if ( $targetFile ) {
               try {
                    Add-Content -Path $targetFile -Value $logEntry -Encoding UTF8

                    $verboseFile = $this.LogTargets['Verbose']
                    if ( $verboseFile -and $Level -ne 'VERBOSE' ) {
                         Add-Content -Path $verboseFile -Value $logEntry -Encoding UTF8 # for unbroken verbose stream
                    }

               } catch {
                    Invoke-ScriptError $_
               }
          }

          if ( $this.ConsoleOutput ) {
               switch ( $Level ) {
                    'ERROR'        { Write-Host $logEntry -ForegroundColor Red }
                    'WARNING'      { Write-Host $logEntry -ForegroundColor Yellow }
                    'INFO'         { Write-Host $logEntry -ForegroundColor Green }
                    'BLANK'        { Write-Host $logEntry}
                    'VERBOSE'      {
                         if ( $this.VerbosePreference -ne 'SilentlyContinue' ) {
                              Write-Host $logEntry -ForegroundColor Cyan
                         }
                    }
                    'DEBUG'        {
                         if ( $this.DebugPreference -ne 'SilentlyContinue' ) {
                              Write-Host $logEntry -ForegroundColor Magenta
                         }
                    }
               }
          }

          # PowerShell streams for integration - only if explicitly enabled
          if ( $this.StreamOutput ) {
               switch ($Level) {
                    'ERROR'   { Write-Error       $Message -ErrorAction Continue }
                    'WARNING' { Write-Warning     $Message }
                    'VERBOSE' { Write-Verbose     $Message }
                    'DEBUG'   { Write-Debug       $Message }
               }
          }

          # Return object only when requested
          if ( $ReturnObject ) {
               return @{
                    HasError    = $Level -eq 'ERROR'
                    HasWarning  = $Level -eq 'WARNING'
                    MessageCode = if ( $MessageCode ) { $MessageCode } else { $null }
                    Message     = $Message
                    Severity    = $Severity
                    Level       = $Level
                    Target      = $Target
               }
          }

          return $null
     }

     # BLANK Line
     [void] BlankLine() {
          $this.WriteLog('BLANK', '', $null, 0, 'Main', $false)
     }

     # INFO Methods - standard return hashtable
     [hashtable] Info([string]$Message) {
          return $this.WriteLog('INFO', $Message, $null, 0, 'Main', $true)
     }

     [hashtable] Info([string]$Message, [string]$MessageCode) {
          return $this.WriteLog('INFO', $Message, $MessageCode, 0, 'Main', $true)
     }

     # INFO NoReturn
     [void] InfoNoReturn([string]$Message) {
          $this.WriteLog('INFO', $Message, $null, 0, 'Main', $false)
     }

     [void] InfoNoReturn([string]$Message, [string]$MessageCode) {
          $this.WriteLog('INFO', $Message, $MessageCode, 0, 'Main', $false)
     }

     # WARNING Methods - standard return hashtable
     [hashtable] Warning([string]$Message) {
          return $this.WriteLog('WARNING', $Message, $null, 1, 'Main', $true)
     }

     [hashtable] Warning([string]$Message, [string]$MessageCode) {
          return $this.WriteLog('WARNING', $Message, $MessageCode, 1, 'Main', $true)
     }

     # WARNING NoReturn
     [void] WarningNoReturn([string]$Message) {
          $this.WriteLog('WARNING', $Message, $null, 1, 'Main', $false)
     }

     [void] WarningNoReturn([string]$Message, [string]$MessageCode) {
          $this.WriteLog('WARNING', $Message, $MessageCode, 1, 'Main', $false)
     }

     # ERROR Methods - standard return hashtable
     [hashtable] Error([string]$Message) {
          return $this.WriteLog('ERROR', $Message, $null, 2, 'Error', $true)
     }

     [hashtable] Error([string]$Message, [string]$MessageCode) {
          return $this.WriteLog('ERROR', $Message, $MessageCode, 2, 'Error', $true)
     }

     # ERROR NoReturn
     [void] ErrorNoReturn([string]$Message) {
          $this.WriteLog('ERROR', $Message, $null, 2, 'Error', $false)
     }

     [void] ErrorNoReturn([string]$Message, [string]$MessageCode) {
          $this.WriteLog('ERROR', $Message, $MessageCode, 2, 'Error', $false)
     }

     # VERBOSE & DEBUG - NoReturn
     [void] Verbose([string]$Message) {
          $this.WriteLog('VERBOSE', $Message, $null, 0, 'Verbose', $false)
     }

     [void] Debug([string]$Message) {
          $this.WriteLog('DEBUG', $Message, $null, 0, 'Debug', $false)
     }

     # Step/SQL/AG Methods - NoReturn
     [void] StepStart([int]$Step, [string]$StepName) {
          $this.BlankLine()
          $message = "========================= STEP $Step START: $StepName ========================="
          $this.WriteLog('INFO', $message, $null, 9999, 'Main', $false)
     }

     [void] StepEnd([int]$Step, [string]$StepName, [bool]$Success) {
          $status   = if ( $Success ) { "SUCCESS" } else { "FAILED" }
          $message  = "========================= STEP $Step END: $StepName - $status ========================="
          $this.WriteLog('INFO', $message, $null, 9999, 'Main', $false)
          $this.BlankLine()
     }

}

Zusammenfassung

PowerShell Klassen revolutionieren die Art, wie du größere Projekte strukturierst. Seit PowerShell 5.0 verfügbar, bieten sie objektorientierte Programmierung mit Eigenschaften, Methoden, Konstruktoren und Method Overloading. Der anfängliche Mehraufwand zahlt sich durch sauberen, wartbaren Code aus – besonders bei Modulen und komplexeren Funktionssammlungen.

Die wichtigsten Vorteile auf einen Blick

• Stark typisierte Properties mit Validierung
• gekapselte Funktionalität durch Methoden
• elegante Überladung statt komplexer Parameter-Logik und eine Struktur, die auch nach Monaten noch verständlich bleibt

Für Daily-Doing-Scripts bleibt der klassische Ansatz praktischer, aber sobald Wiederverwendbarkeit und Struktur wichtig werden, führt für mich kein Weg mehr an Klassen vorbei. 🫡

The post PowerShell Klassen für Anfänger – Strukturierter Code statt Funktions-Chaos first appeared on DBA von Nebenan.

SELECT 
    blocking_session_id   AS blocking_session,
    session_id            AS blocked_session,
    wait_time / 1000.0    AS waiting_sec,
    wait_type             AS waittype,
    resource_description  AS ressource
FROM 
    sys.dm_os_waiting_tasks
WHERE 
    blocking_session_id IS NOT NULL
ORDER BY 
    wait_time DESC

Ich hab auch noch eine eigene Entwicklung dazu, die werde ich in einem späteren Blogpost vorstellen, die meinen individuellen Anforderungen besser entspricht.

Das Problem

Jetzt kann ich AdHoc Blockings anzeigen, aber bei Deadlocks wird’s interessanter. Dafür muss die System Health Session gecheckt werden, die ist auch noch flüchtig.

-- Query System Health Session for Deadlocks

SELECT
    event_data.value('(event/@timestamp)[1]', 'datetime2') AS DeadlockDateTime,
    event_data.query('.')                                  AS DeadlockGraph
FROM
(
    SELECT 
        CAST(target_data AS XML) AS target_data
    FROM 
        sys.dm_xe_session_targets AS st
    JOIN 
        sys.dm_xe_sessions AS s ON s.address = st.event_session_address
    WHERE
             s.name = 'system_health'
        AND st.target_name = 'ring_buffer'
) AS data
CROSS APPLY
    target_data.nodes('//RingBufferTarget/event[@name="xml_deadlock_report"]') AS XEventData(event_data)
ORDER BY 
    DeadlockDateTime DESC;

Dieses Problem hatte ich bei einem Kunden, der extrem mit Deadlocks in einer 3rd Party Anwendung zu kämpfen hatte, aber der Support war bisschen… sagen wir mal zurückhaltend. 😉

Wir mussten denen alles transparent melden, damit die anfangen eine Lösung zu finden. Query-Resultsets kann man natürlich als transparent betrachten, wenn man sie versteht oder verstehen will. Leider sind die XML von Health Sessions oder Extended Events nicht gerade dafür berühmt, lesbar zu sein. Der Kunde wollte aber einfach nur, dass das Problem gelöst wird.

Also haben wir gemeinsam eine Reporting-Lösung entwickelt.

Die Idee

Mit Extended Events hab ich XML-Daten und mit PowerShell kann ich XML parsen wie ich will, auch zu einem Report meiner Wahl.

Das Ziel

Wir wollten eine Möglichkeit, abseits von SQL Server Resultsets, Anwendungsprobleme mit Anomalien in den SQL Server Metriken zu überlagern, um schnell Lösungen herbeizuführen.

In der Woche nach dem Livegang der Lösung gab’s viele, viele „Aha“-Momente. Von falsch konfigurierten ERP-Parametern bis hin zu schlechtem Transaction-Handling.

Der Weg

Persistente Daten

Das Wichtigste ist, Blocking Session und Deadlock Events persistent zu speichern. Das geht perfekt mit Extended Events. Dafür gibt’s zwei Bereiche:

-- SNIPPET!!

ADD EVENT sqlserver.blocked_process_report(
    ACTION(sqlserver.client_app_name,
           sqlserver.client_hostname,
           sqlserver.database_name)
),
ADD EVENT sqlserver.xml_deadlock_report(
    ACTION(sqlserver.client_app_name,
           sqlserver.client_hostname,
           sqlserver.database_name)
)

Das ganze wird in einem eigenen Extended Event konfiguriert und die Aufzeichnungen laufen bereits. Fast! Wir müssen noch SQL Server konfigurieren, damit Blocked Process als Extended Events behandelt werden.

EXEC sp_configure 'show advanced options', 1;
GO
RECONFIGURE;
GO
EXEC sp_configure 'blocked process threshold', '5'; -- 5 Sekunden
RECONFIGURE
GO

Daten auslesen

100% PowerShell

Nachdem die Events geloggt werden, müssen sie ausgewertet werden. Was mir sofort eingefallen ist, waren die dbatools mit Read-DbaXEFile. Das Problem ist, dass die aktuell geschriebene Datei damit nicht gelesen werden kann. Du kannst dir vorstellen, dass Blocking- und Deadlock-Events nicht in solchen Massen auftreten, dass dutzende File-Rotationen innerhalb von 24h durchgeführt werden. Falls doch, hast du definitiv ein anderes Problem als es nur zu reporten. Also haben wir den Umweg über SQL Server genommen, da auch hier die aktuelle Datei gelesen werden kann.

PowerShell + TSql

XML mit Queries zu lesen, fällt mir immer noch sehr schwer, aber DANKE an Brent Ozar, uns allen bekannt, für die grundlegende Query, auf der ich aufbauen konnte. Zumindest hatte ich jetzt ein Resultset zur Orientierung und ein separates XML für jedes Event im Log.

-- Snippet
select
    *
FROM sys.fn_xe_file_target_read_file
   ('C:\temp\XEventSessions\blocked_process*.xel',
    'C:\temp\XEventSessions\blocked_process*.xem',
     null, null)
CROSS APPLY 
    (SELECT CAST(event_data AS XML) AS event_data) as xevents

Finalisierung mit PowerShell

Da ich endlich mein XML-Event hatte, konnte ich es mit PowerShell parsen, transformieren und letztendlich in einen schönen Text-Report verpacken.

Sql Server Deadlock Analysis | Event Time: 2025-04-08T11:16:07.447
================================================================================

SQL STATEMENTS INVOLVED
--------------------------------------------------------------------------------

    Process ID:   process261b00cfc28
    SPID:         643
    Database:     DATABASENAME
    Query:        **DETAILED QUERY**

----------------------------------------

    Process ID:   process258294fbc28
    SPID:         650
    Database:     DATABASENAME
    Query:        **DETAILED QUERY**

----------------------------------------

VICTIM LIST
--------------------------------------------------------------------------------

    Process ID:   process261b00cfc28
    SPID:         643
    Database:     DATABASENAME


PROCESS LIST
--------------------------------------------------------------------------------

    Process ID:               process261b00cfc28
    SPID:                     643
    Isolation Level:          read uncommitted (1)
    Logical Reads:            700
    Wait Resource:            KEY: 6:72058005407662080 (fb04e1bc7788)
    Wait Time (ms):           2247
    Transaction:              user_transaction
    Last Transaction Started: 2025-04-08T11:16:07.447
    Client:                   'dbserver_dll <ID@APPSERVER:34784>'
    Hostname:                 APPSERVER
    User:                     USERNAME


EXECUTED SQL STATEMENT
----------------------------------------

    **DETAILED QUERY**


Process Details
================================================================================


    Process ID:               process258294fbc28
    SPID:                     650
    Isolation Level:          read uncommitted (1)
    Logical Reads:            1904
    Wait Resource:            KEY: 6:72057996178358272 (2a9726d2d061)
    Wait Time (ms):           2278
    Transaction:              user_transaction
    Last Transaction Started: 2025-04-08T11:16:07.330
    Client:                   'dbserver_dll <ID@APPSERVER:11664>'
    Hostname:                 APPSERVER
    User:                     USERNAME


EXECUTED SQL STATEMENT
----------------------------------------

    **DETAILED QUERY**


Process Details
================================================================================


RESOURCE LIST
--------------------------------------------------------------------------------

    Resource:
        Type:               keylock
        Database:           6
        Object:             DATABASENAME.dbo.tcprmp300100
        Index:              Itcprmp300100_1a
        Lock Mode:          X
        HOBT ID:            72058005407662080
        Associated Object ID: 72058005407662080

    Owners:
        Process ID:         process258294fbc28, Mode: X

    Waiting Processes:
        Process ID:         process261b00cfc28, Mode: U, Request Type: wait

================================================================================

    Resource:
        Type:               keylock
        Database:           6
        Object:             DATABASENAME.dbo.tcprrp011100
        Index:              Itcprrp011100_1a
        Lock Mode:          X
        HOBT ID:            72057996178358272
        Associated Object ID: 72057996178358272

    Owners:
        Process ID:         process261b00cfc28, Mode: X

    Waiting Processes:
        Process ID:         process258294fbc28, Mode: U, Request Type: wait

================================================================================

Umsetzung

Es wurde gewünscht, die Ergebnisse in den Daily Report zu integrieren, den wir bereits mit PowerShell umgesetzt hatten. Jetzt ist es nicht geil, potenziell jeden Morgen 200 Textdateien an eine E-Mail zu hängen, deshalb gibt das PowerShell-Script eine Tabelle zurück, die zeigt, wie Blocks und Locks in Zeitraum X aufgetreten sind, und bei Bedarf kann man proaktiv die Ordnerstruktur checken.

Für den dramatischen Effekt und schnellen Überblick wird auch noch eine Excel-Datei generiert. In diesem Beispiel gab’s einen schönen Kollateralfund, dass die DWH-Jobs massive Probleme hatten 🙂

Und schon hatten wir ein paar Reports, die wir dem Vendor in die Hand drücken konnten, und dann ging’s sehr schnell.

Die Ordnerstruktur

_report/
├── text_reports/
│   └── YYYY/
│       └── MM/
│           └── DD/
│               ├── 20231120_123456_dbname_blocked.txt
│               ├── 20231120_123456_dbname_blocked.xml
│               └── 20231120_123456_dbname_deadlock.txt
└── excel_reports/
    └── BlockReport_20231120_123456.xlsx

Leider erlebe ich immer wieder, dass Anwendungsvendoren denken, ihre Kunden sind zu blöd und können die Anwendung nicht bedienen. Hört auf damit und glaubt euren Kunden manchmal auch ohne 101% Daten, die man nur sammeln kann, wenn man bereits Sachkenntnis hat.

Repository ansehen

Das Script hat verschiedene Parameter und Optionen, Details stehen in der README.MD. Falls du Fragen hast, lass sie in den Kommentaren oder kontaktier mich.

Anderes

Erik Darling hat auch eine Lösung entwickelt, um Extended Events lesbar zu machen, falls andere Ansätze gebraucht werden. (sp_HumanEvents)

Gabriel, der DBAvonNebenan

The post Dokumentation von Blocks und Deadlocks – Wenn der 3rd-Party Vendor Beweise fordert first appeared on DBA von Nebenan.

SELECT 
    blocking_session_id   AS blocking_session,
    session_id            AS blocked_session,
    wait_time / 1000.0    AS waiting_sec,
    wait_type             AS waittype,
    resource_description  AS ressource
FROM 
    sys.dm_os_waiting_tasks
WHERE 
    blocking_session_id IS NOT NULL
ORDER BY 
    wait_time DESC

I also have a custom development that I will present in a later blog post, which better meets my individual requirements.

The Problem

Now I can display AdHoc blocks, but with deadlocks it gets more interesting. For this, the System Health Session must be checked, which is also volatile.

-- Query System Health Session for Deadlocks

SELECT
    event_data.value('(event/@timestamp)[1]', 'datetime2') AS DeadlockDateTime,
    event_data.query('.')                                  AS DeadlockGraph
FROM
(
    SELECT 
        CAST(target_data AS XML) AS target_data
    FROM 
        sys.dm_xe_session_targets AS st
    JOIN 
        sys.dm_xe_sessions AS s ON s.address = st.event_session_address
    WHERE
             s.name = 'system_health'
        AND st.target_name = 'ring_buffer'
) AS data
CROSS APPLY
    target_data.nodes('//RingBufferTarget/event[@name="xml_deadlock_report"]') AS XEventData(event_data)
ORDER BY 
    DeadlockDateTime DESC;

I encountered this problem with a client who was struggling enormously with deadlocks in a 3rd party application, but the support was a bit… let’s say reluctant. 😉

We had to report everything transparently to them so they would start finding a solution. Of course, query result sets can be considered transparent if you understand them or want to understand them. Unfortunately, the XML of Health Sessions or Extended Events are not exactly famous for being readable. Yet the client simply wanted the problem to be fixed.

So together we developed a reporting solution.

The Idea

With Extended Events I have XML data, and with PowerShell I can parse XML however I want, including into a report of my choice.

The Goal

We wanted a way, apart from SQL Server result sets, to overlay application problems with anomalies in the SQL Server metrics to quickly bring about solutions.

In the week after the solution went live, there were many, many „aha“ moments. From incorrectly configured ERP parameters to poor transaction handling.

The Way

Persistent Data

The most important thing is to persistently store blocking session and deadlock events. This works perfectly with Extended Events. There are two areas for this:

-- SNIPPET!!

ADD EVENT sqlserver.blocked_process_report(
    ACTION(sqlserver.client_app_name,
           sqlserver.client_hostname,
           sqlserver.database_name)
),
ADD EVENT sqlserver.xml_deadlock_report(
    ACTION(sqlserver.client_app_name,
           sqlserver.client_hostname,
           sqlserver.database_name)
)

The whole thing is configured in its own Extended Event and the recordings are already running. Nearly! We still need to configure SQL Server to treat Blocked Process as Extended Events.

EXEC sp_configure 'show advanced options', 1;
GO
RECONFIGURE;
GO
EXEC sp_configure 'blocked process threshold', '5'; -- 5 Secconds
RECONFIGURE
GO

Read Data

100% PowerShell

After the events are logged, they need to be evaluated. What immediately came to my mind were the dbatools with Read-DbaXEFile. The problem is that the currently written file cannot be read with it. You can imagine that blocking and deadlock events don’t occur in such masses that dozens of file rotations are performed within 24 hours. If they do, you definitely have a different problem than just reporting it . So we took the detour via SQL Server, since the current file can also be read here.

PowerShell + TSql

I still find it very difficult to read XML with queries, but THANKS to Brent Ozar, known to all of us, for the basic query I could build upon. At least I now had a result set for orientation and a separate XML for each event in the log.

-- Snippet
select
    *
FROM sys.fn_xe_file_target_read_file
   ('C:\temp\XEventSessions\blocked_process*.xel',
    'C:\temp\XEventSessions\blocked_process*.xem',
     null, null)
CROSS APPLY 
    (SELECT CAST(event_data AS XML) AS event_data) as xevents

Finalization with PowerShell

Since I finally had my XML event, I could parse it with PowerShell, transform it, and finally package it into a nice text report.

Sql Server Deadlock Analysis | Event Time: 2025-04-08T11:16:07.447
================================================================================

SQL STATEMENTS INVOLVED
--------------------------------------------------------------------------------

    Process ID:   process261b00cfc28
    SPID:         643
    Database:     DATABASENAME
    Query:        **DETAILED QUERY**

----------------------------------------

    Process ID:   process258294fbc28
    SPID:         650
    Database:     DATABASENAME
    Query:        **DETAILED QUERY**

----------------------------------------

VICTIM LIST
--------------------------------------------------------------------------------

    Process ID:   process261b00cfc28
    SPID:         643
    Database:     DATABASENAME


PROCESS LIST
--------------------------------------------------------------------------------

    Process ID:               process261b00cfc28
    SPID:                     643
    Isolation Level:          read uncommitted (1)
    Logical Reads:            700
    Wait Resource:            KEY: 6:72058005407662080 (fb04e1bc7788)
    Wait Time (ms):           2247
    Transaction:              user_transaction
    Last Transaction Started: 2025-04-08T11:16:07.447
    Client:                   'dbserver_dll <ID@APPSERVER:34784>'
    Hostname:                 APPSERVER
    User:                     USERNAME


EXECUTED SQL STATEMENT
----------------------------------------

    **DETAILED QUERY**


Process Details
================================================================================


    Process ID:               process258294fbc28
    SPID:                     650
    Isolation Level:          read uncommitted (1)
    Logical Reads:            1904
    Wait Resource:            KEY: 6:72057996178358272 (2a9726d2d061)
    Wait Time (ms):           2278
    Transaction:              user_transaction
    Last Transaction Started: 2025-04-08T11:16:07.330
    Client:                   'dbserver_dll <ID@APPSERVER:11664>'
    Hostname:                 APPSERVER
    User:                     USERNAME


EXECUTED SQL STATEMENT
----------------------------------------

    **DETAILED QUERY**


Process Details
================================================================================


RESOURCE LIST
--------------------------------------------------------------------------------

    Resource:
        Type:               keylock
        Database:           6
        Object:             DATABASENAME.dbo.tcprmp300100
        Index:              Itcprmp300100_1a
        Lock Mode:          X
        HOBT ID:            72058005407662080
        Associated Object ID: 72058005407662080

    Owners:
        Process ID:         process258294fbc28, Mode: X

    Waiting Processes:
        Process ID:         process261b00cfc28, Mode: U, Request Type: wait

================================================================================

    Resource:
        Type:               keylock
        Database:           6
        Object:             DATABASENAME.dbo.tcprrp011100
        Index:              Itcprrp011100_1a
        Lock Mode:          X
        HOBT ID:            72057996178358272
        Associated Object ID: 72057996178358272

    Owners:
        Process ID:         process261b00cfc28, Mode: X

    Waiting Processes:
        Process ID:         process258294fbc28, Mode: U, Request Type: wait

================================================================================

Implementation

It was requested to add the results to the daily report, which we had already implemented with PowerShell. Now, it’s not great to potentially attach 200 text files to an email every morning, so the PowerShell script returns a table showing how blocks and locks occurred in time period X, and if needed, one can proactively check the folder structure.

For dramatic effect and a quick overview, an Excel file is also generated. In this example, there was a nice collateral finding that the DWH jobs had serious problems 🙂

And just like that, we had a few reports that we could hand over to the vendor, and then things moved very quickly.

Die Ordner Struktur

_report/
├── text_reports/
│   └── YYYY/
│       └── MM/
│           └── DD/
│               ├── 20231120_123456_dbname_blocked.txt
│               ├── 20231120_123456_dbname_blocked.xml
│               └── 20231120_123456_dbname_deadlock.txt
└── excel_reports/
    └── BlockReport_20231120_123456.xlsx

Unfortunately, I experience again and again that application vendors think their customers are stupid and cannot operate the application. Stop doing that and believe your customers sometimes without 101% data, which you can only collect if you already have knowledge of the subject matter.

See Repository

The script has various parameters and options, details are in the README.MD. If you have questions, leave them in the comments or contact me.

Other

Erik Darling has also developed a solution to make Extended Events readable, in case other approaches are needed. (sp_HumanEvents)

Gabriel, der DBAvonNebenan

The post Reporting Blocks and Deadlocks: When the 3rd-Party Vendor Demands Evidence first appeared on DBA von Nebenan.

So I wrote a small PowerShell script that searches through MD files in the current folder for links, downloads them to the attachments folder, and dynamically replaces the links in the MD with local links.

The post Offline Images with Obsidian Website Clipper first appeared on DBA von Nebenan.

Deshalb habe ich ein kleines PowerShell-Script geschrieben, das MD-Dateien im aktuellen Ordner nach Links durchsucht, sie in den Attachments-Ordner herunterlädt und die Links in den MD-Dateien dynamisch durch lokale Links ersetzt.

The post Offline Bilder mit Obsidian Website Clipper first appeared on DBA von Nebenan.