Wie man PowerShell verwendet, um SQL-Server-Instanzen zu entdecken und dokumentieren

Möchten Sie lernen, wie man MSSQL-Server-Instanzen mit PowerShell abrufen kann? In der IT-Welt ist die Verwaltung und Wartung von SQL-Server-Instanzen eine wichtige Aufgabe für IT-Expert:innen und Managed Service Provider (MSPs). Wenn Sie wissen, wie Sie effizient Informationen über SQL Server-Instanzen sammeln, können Sie Ihre administrativen Aufgaben erheblich verbessern und Prozesse rationalisieren. Dieser Blogbeitrag befasst sich mit einem leistungsstarken PowerShell-Skript zum Abrufen einer Liste von MSSQL-Server-Instanzen und bietet detaillierte Einblicke und praktische Anwendungen.

Kontext

SQL-Server-Instanzen sind das Rückgrat vieler Geschäftsanwendungen und speichern bzw. verwalten große Datenmengen. IT-Expert:innen müssen diese Instanzen oft identifizieren und verwalten, um optimale Leistung und Sicherheit zu gewährleisten. Das mitgelieferte PowerShell-Skript ist ein unschätzbares Tool zum schnellen Abrufen von Informationen über SQL Server-Instanzen auf einem System. Diese Fähigkeit ist für Aufgaben wie Prüfungen, Fehlersuche und Systemüberwachung von entscheidender Bedeutung.

Das Skript zum Abrufen von MSSQL Server-Instanzen

#Requires -Version 5.1

<#
.SYNOPSIS
    Gets a list of MSSQL server instances and optionally save the results to a custom field.
.DESCRIPTION
    Gets a list of MSSQL server instances and optionally save the results to a custom field.
    The custom field can be either/both a multi-line or WYSIWYG custom field.

    SQL Server, SQL Server Developer and SQL Express are supported.

    SQL "Local" that are built into an application are not supported as they aren't an SQL Server instance.

    SQL service name that don't start with "MSSQL$" will not get detected.

    PS > Get-Service -Name "MSSQL`$*"
    Status   Name               DisplayName
    ------   ----               -----------
    Running  MSSQL$DB           SQL Server (DB)
    Running  MSSQL$DB01         SQL Server (DB01)
    Running  MSSQL$DB02         SQL Server (DB02)

.EXAMPLE
    (No Parameters)
    ## EXAMPLE OUTPUT WITHOUT PARAMS ##
     Status Name              Instance Path
     ------ ----              -------- ----
    Running SQL Server (DB01) DB01     C:\Program Files\Microsoft SQL Server\MSSQL16.DB01\MSSQL
    Running SQL Server (DB02) DB02     C:\Program Files\Microsoft SQL Server\MSSQL16.DB02\MSSQL

PARAMETER: -CustomFieldName "ReplaceMeWithAnyMultilineCustomField"
    Saves an text table to a multi-line Custom Field with a list of SQL instances.
.EXAMPLE
    -CustomFieldName "ReplaceMeWithAnyMultilineCustomField"
    ## EXAMPLE OUTPUT WITH CustomFieldName ##
     Status Name              Instance Path
     ------ ----              -------- ----
    Running SQL Server (DB01) DB01     C:\Program Files\Microsoft SQL Server\MSSQL16.DB01\MSSQL
    Running SQL Server (DB02) DB02     C:\Program Files\Microsoft SQL Server\MSSQL16.DB02\MSSQL

PARAMETER: -CustomFieldParam "ReplaceMeWithAnyWysiwygCustomField"
    Saves an html table to a Wysiwyg Custom Field with a list of SQL instances.
.EXAMPLE
    -WysiwygCustomFieldName "ReplaceMeWithAnyWysiwygCustomField"
    ## EXAMPLE OUTPUT WITH WysiwygCustomFieldName ##
     Status Name              Instance Path
     ------ ----              -------- ----
    Running SQL Server (DB01) DB01     C:\Program Files\Microsoft SQL Server\MSSQL16.DB01\MSSQL
    Running SQL Server (DB02) DB02     C:\Program Files\Microsoft SQL Server\MSSQL16.DB02\MSSQL
.OUTPUTS
    None
.NOTES
    Release Notes: Initial Release
By using this script, you indicate your acceptance of the following legal terms as well as our Terms of Use at https://www.ninjaone.com/terms-of-use.
    Ownership Rights: NinjaOne owns and will continue to own all right, title, and interest in and to the script (including the copyright). NinjaOne is giving you a limited license to use the script in accordance with these legal terms. 
    Use Limitation: You may only use the script for your legitimate personal or internal business purposes, and you may not share the script with another party. 
    Republication Prohibition: Under no circumstances are you permitted to re-publish the script in any script library or website belonging to or under the control of any other software provider. 
    Warranty Disclaimer: The script is provided “as is” and “as available”, without warranty of any kind. NinjaOne makes no promise or guarantee that the script will be free from defects or that it will meet your specific needs or expectations. 
    Assumption of Risk: Your use of the script is at your own risk. You acknowledge that there are certain inherent risks in using the script, and you understand and assume each of those risks. 
    Waiver and Release: You will not hold NinjaOne responsible for any adverse or unintended consequences resulting from your use of the script, and you waive any legal or equitable rights or remedies you may have against NinjaOne relating to your use of the script. 
    EULA: If you are a NinjaOne customer, your use of the script is subject to the End User License Agreement applicable to you (EULA).
#>

[CmdletBinding()]
param (
    [String]$CustomFieldName,
    [String]$WysiwygCustomFieldName
)

begin {
    function Test-IsElevated {
        $id = [System.Security.Principal.WindowsIdentity]::GetCurrent()
        $p = New-Object System.Security.Principal.WindowsPrincipal($id)
        $p.IsInRole([System.Security.Principal.WindowsBuiltInRole]::Administrator)
    }
    function Set-NinjaProperty {
        [CmdletBinding()]
        Param(
            [Parameter(Mandatory = $True)]
            [String]$Name,
            [Parameter()]
            [String]$Type,
            [Parameter(Mandatory = $True, ValueFromPipeline = $True)]
            $Value,
            [Parameter()]
            [String]$DocumentName
        )
    
        $Characters = $Value | Measure-Object -Character | Select-Object -ExpandProperty Characters
        if ($Characters -ge 10000) {
            throw [System.ArgumentOutOfRangeException]::New("Character limit exceeded, value is greater than 10,000 characters.")
        }
        
        # If we're requested to set the field value for a Ninja document we'll specify it here.
        $DocumentationParams = @{}
        if ($DocumentName) { $DocumentationParams["DocumentName"] = $DocumentName }
        
        # This is a list of valid fields that can be set. If no type is given, it will be assumed that the input doesn't need to be changed.
        $ValidFields = "Attachment", "Checkbox", "Date", "Date or Date Time", "Decimal", "Dropdown", "Email", "Integer", "IP Address", "MultiLine", "MultiSelect", "Phone", "Secure", "Text", "Time", "URL", "WYSIWYG"
        if ($Type -and $ValidFields -notcontains $Type) { Write-Warning "$Type is an invalid type! Please check here for valid types. https://ninjarmm.zendesk.com/hc/en-us/articles/16973443979789-Command-Line-Interface-CLI-Supported-Fields-and-Functionality" }
        
        # The field below requires additional information to be set
        $NeedsOptions = "Dropdown"
        if ($DocumentName) {
            if ($NeedsOptions -contains $Type) {
                # We'll redirect the error output to the success stream to make it easier to error out if nothing was found or something else went wrong.
                $NinjaPropertyOptions = Ninja-Property-Docs-Options -AttributeName $Name @DocumentationParams 2>&1
            }
        }
        else {
            if ($NeedsOptions -contains $Type) {
                $NinjaPropertyOptions = Ninja-Property-Options -Name $Name 2>&1
            }
        }
        
        # If an error is received it will have an exception property, the function will exit with that error information.
        if ($NinjaPropertyOptions.Exception) { throw $NinjaPropertyOptions }
        
        # The below type's require values not typically given in order to be set. The below code will convert whatever we're given into a format ninjarmm-cli supports.
        switch ($Type) {
            "Checkbox" {
                # While it's highly likely we were given a value like "True" or a boolean datatype it's better to be safe than sorry.
                $NinjaValue = [System.Convert]::ToBoolean($Value)
            }
            "Date or Date Time" {
                # Ninjarmm-cli expects the GUID of the option to be selected. Therefore, the given value will be matched with a GUID.
                $Date = (Get-Date $Value).ToUniversalTime()
                $TimeSpan = New-TimeSpan (Get-Date "1970-01-01 00:00:00") $Date
                $NinjaValue = $TimeSpan.TotalSeconds
            }
            "Dropdown" {
                # Ninjarmm-cli is expecting the guid of the option we're trying to select. So we'll match up the value we were given with a guid.
                $Options = $NinjaPropertyOptions -replace '=', ',' | ConvertFrom-Csv -Header "GUID", "Name"
                $Selection = $Options | Where-Object { $_.Name -eq $Value } | Select-Object -ExpandProperty GUID
        
                if (-not $Selection) {
                    throw [System.ArgumentOutOfRangeException]::New("Value is not present in dropdown")
                }
        
                $NinjaValue = $Selection
            }
            default {
                # All the other types shouldn't require additional work on the input.
                $NinjaValue = $Value
            }
        }
        
        # We'll need to set the field differently depending on if its a field in a Ninja Document or not.
        if ($DocumentName) {
            $CustomField = Ninja-Property-Docs-Set -AttributeName $Name -AttributeValue $NinjaValue @DocumentationParams 2>&1
        }
        else {
            $CustomField = Ninja-Property-Set -Name $Name -Value $NinjaValue 2>&1
        }
        
        if ($CustomField.Exception) {
            throw $CustomField
        }
    }
    if ($env:multilineCustomFieldName -and $env:multilineCustomFieldName -notlike "null") {
        $CustomFieldName = $env:multilineCustomFieldName
    }
    if ($env:WysiwygCustomFieldName -and $env:WysiwygCustomFieldName -notlike "null") {
        $WysiwygCustomFieldName = $env:WysiwygCustomFieldName
    }
}
process {
    if (-not (Test-IsElevated)) {
        Write-Error -Message "Access Denied. Please run with Administrator privileges."
        exit 1
    }

    try {
        $InstanceNames = $(Get-ItemProperty -Path "HKLM:\SOFTWARE\Microsoft\Microsoft SQL Server\" -ErrorAction Stop).InstalledInstances
        $SqlInstances = $InstanceNames | ForEach-Object {
            $SqlPath = $(Get-ItemProperty -Path "HKLM:\SOFTWARE\Microsoft\Microsoft SQL Server\$_\Setup" -ErrorAction Stop).SQLPath
            $SqlServices = Get-Service -Name "MSSQL`$$_" -ErrorAction Stop
            $SqlService = $SqlServices | Where-Object { $_.Name -notlike $SqlServices.DependentServices.Name -and $_.Name -notlike "SQLTelemetry*" }
            [PSCustomObject]@{
                Status   = $SqlService.Status
                Service  = $SqlService.DisplayName
                Instance = $_
                Path     = $SqlPath
            }
        }
    }
    catch {
        Write-Host "[Error] $($_.Message)"
        Write-Host "[Info] Likely no MSSQL instance found."
        exit 1
    }

    $SqlInstances | Out-String | Write-Host

    if ($CustomFieldName) {
        Write-Host "Attempting to set Custom Field '$CustomFieldName'."
        Set-NinjaProperty -Name $CustomFieldName -Value ($SqlInstances | Out-String)
        Write-Host "Successfully set Custom Field '$CustomFieldName'!"
    }

    if ($WysiwygCustomFieldName) {
        try {
            Write-Host "Attempting to set Custom Field '$WysiwygCustomFieldName'."
            $htmlReport = New-Object System.Collections.Generic.List[String]
            $htmlReport.Add("<h1>SQL Server Instances</h1>")
            $htmlTable = $SqlInstances | ConvertTo-Html -Fragment 
            $htmlTable = $htmlTable -replace "<tr><td>Running</td>", '<tr class="success"><td>Running</td>'
            $htmlTable = $htmlTable -replace "<tr><td>StartPending</td>", '<tr class="other"><td>StartPending</td>'
            $htmlTable = $htmlTable -replace "<tr><td>ContinuePending</td>", '<tr class="other"><td>ContinuePending</td>'
            $htmlTable = $htmlTable -replace "<tr><td>Paused</td>", '<tr class="other"><td>Paused</td>'
            $htmlTable = $htmlTable -replace "<tr><td>PausePending</td>", '<tr class="other"><td>PausePending</td>'
            $htmlTable = $htmlTable -replace "<tr><td>Stopped</td>", '<tr class="danger"><td>Stopped</td>'
            $htmlTable = $htmlTable -replace "<tr><td>StopPending</td>", '<tr class="danger"><td>StopPending</td>'
            $htmlTable | ForEach-Object { $htmlReport.Add($_) }
            Set-NinjaProperty -Name $WysiwygCustomFieldName -Value ($htmlReport | Out-String)
            Write-Host "Successfully set Custom Field '$WysiwygCustomFieldName'!"
        }
        catch {
            Write-Error $_
            Write-Host "[Error] $($_.Message)"
            exit 1
        }
    }
    exit 0
}
end {
    
    
    
}

 

Detailansicht

Das Skript prüft zunächst, ob es mit Administratorrechten ausgeführt wird, die für den Zugriff auf bestimmte Systemeigenschaften erforderlich sind. Sie definiert eine Funktion, Test-IsElevated, um dies zu überprüfen. Wenn das Skript nicht als Administrator ausgeführt wird, wird es mit einem Fehlermeldung beendet.

Anschließend wird versucht, die installierten SQL-Server-Instanzen aus der Windows-Registrierung abzurufen. Dies wird durch das Cmdlet ‘Get-ItemProperty’ erreicht, das auf den entsprechenden Registrierungspfad zugreift. Das Skript durchläuft dann jede Instanz und ruft Details wie den Instanznamen, den Dienststatus und den Installationspfad ab.

Die gesammelten Informationen werden in einem benutzerdefinierten Objekt strukturiert und angezeigt. Falls angegeben, können die Ergebnisse auch in benutzerdefinierten Feldern gespeichert werden, entweder als Plain-Text oder als HTML, unter Verwendung der Funktion Set-NinjaProperty. Diese Funktion verarbeitet verschiedene Datentypen und stellt sicher, dass die Werte den Zeichengrenzen und anderen Beschränkungen entsprechen.

Potenzielle Anwendungsfälle

Stellen Sie sich vor, ein IT-Experte verwaltet mehrere Server in einem Unternehmen. Mit diesem Skript kann er alle SQL-Server-Instanzen, die auf den einzelnen Servern laufen, schnell erfassen und dokumentieren. Diese Informationen sind für Software-Updates, die Durchführung von Sicherheitsaudits und die Kapazitätsplanung unerlässlich. Während eines Upgrade-Zyklus beispielsweise hilft die Kenntnis aller aktiven Instanzen bei der Planung und Minimierung von Ausfallzeiten.

Vergleiche

Dieses PowerShell-Skript bietet eine optimierte und automatisierte Methode zum Erfassen von SQL-Server-Instanzinformationen im Vergleich zu manuellen Methoden. Traditionell können Administrator:innen das SQL Server Management Studio (SSMS) verwenden oder die Dienste manuell über die Windows Services-Konsole überprüfen. Diese Methoden sind zwar wirksam, aber zeitaufwändig und anfällig für menschliches Versagen. Im Gegensatz dazu bietet das Skript einen konsistenten, wiederholbaren Prozess, der leicht in umfassendere IT-Management-Workflows integriert werden kann.

FAQs

F: Kann dieses Skript SQL-Server-Instanzen erkennen, die als Teil einer Anwendung installiert sind?

A: Nein, das Skript ist so konzipiert, dass es Standard-SQL-Server-Instanzen erkennt. Instanzen, die in Anwendungen eingebettet sind, werden nicht unterstützt.

F: Was passiert, wenn der Name eines benutzerdefinierten Feldes die Zeichengrenze überschreitet?

A: Das Skript enthält eine Prüfung, um sicherzustellen, dass die Werte nicht mehr als 10.000 Zeichen umfassen. Wird diese Grenze überschritten, tritt ein Fehler auf.

F: Kann dieses Skript auf jeder Version von PowerShell ausgeführt werden?

A: Das Skript erfordert PowerShell Version 5.1 oder höher.

Folgen

Durch die Ausführung dieses Skripts erhalten IT-Expert:innen einen detaillierten Einblick in die SQL-Server-Bereitstellung in ihrer Infrastruktur. Diese Informationen sind wichtig, um die Compliance zu gewährleisten, die Leistung zu optimieren und die Sicherheit zu erhöhen. Wenn Administrator:innen genau wissen, wo SQL-Server-Instanzen ausgeführt werden, können sie sensible Daten besser schützen und sicherstellen, dass die Systeme richtig konfiguriert und gewartet werden.

Empfehlungen

• Als Administrator ausführen: Stellen Sie sicher, dass das Skript mit den erforderlichen Berechtigungen für den Zugriff auf Systeminformationen ausgeführt wird.

• Regelmäßige Audits: Planen Sie die regelmäßige Ausführung des Skripts, um ein aktuelles Bestandsinventar der SQL-Server-Instanzen zu erhalten.

• Integration mit Überwachungs-Tools: Erwägen Sie, die Ausgabe des Skripts in Überwachungs- und Dokumentations-Tools zu integrieren, um die Systemverwaltung zu optimieren.

Abschließende Überlegungen

Das in diesem Beitrag besprochene PowerShell-Skript ist ein leistungsstarkes Tool für IT-Expert:innen, die mit der Verwaltung von SQL-Server-Instanzen betraut sind. Durch die Automatisierung des Erkennungsprozesses spart es Zeit und verringert das Fehlerrisiko, was es zu einer unverzichtbaren Ergänzung für jedes IT-Toolkit macht. Tools wie NinjaOne können diesen Prozess weiter verbessern, indem sie robuste Management- und Überwachungsfunktionen bereitstellen und so dafür sorgen, dass Ihre SQL-Server-Instanzen immer unter Kontrolle und sicher sind.