Private/Wissen/B_Basic/B21_Hilfe-System.ps1
|
<#
# Hilfe Hilfe zur PowerShell und Cmdlets abrufen. Cmdlets finden und verstehen. - **Hashtags** Help about Parameter Find cmdlet - **Version** 2020.12.22 #> #region 1. PowerShell-Hilfe zu Modulen installieren bzw. aktualisieren # ! Hilfe zu allen Modulen installieren (Admin-Rechte werden benötigt): Update-Help -Module '*' -UICulture 'en-US' -Force # * Die Quelle ist das Internet bzw. der im Module (.PSD1) hinterlegte Path (HelpInfoURI). Einige Module haben keinen Path hinterlegt was mit einer Error quittiert wird. # ! Hilfe auf Nicht-Internet-Fähigen Computern installieren: # TIPP - Es ist wichtig für ALLE PowerShell-Computer die Hilfe zu installieren, um relevante Informationen auch dort nachschlagen zu können. # TODO 1. SCHRITT - Auf einem internet-fähigen die Hilfe installieren. # TODO 2. SCHRITT - Von diesem die Hilfe-Daten kopieren (evtl. benötigte Module installieren oder Test-System einrichten): Save-Help -DestinationPath 'C:\Temp\PSHelpFiles' -Module '*' -UICulture 'en-US' # TODO 3. SCHRITT - Von einer lokalten Ort die Hilfe auf dem Ziel-PC installieren: Update-Help -Module '*' -UICulture 'en-US' -Force -SourcePath 'C:\Temp\PSHelpFiles' # ? Quiz / Übungen zu PowerShell-Hilfe installieren # ? 1. Welche Voraussetzungen müssen zum Installieren der PowerShell-Hilfe erfüllt sein? # ? 2. Welche Hilfe bzw. zu Was wird Hilfe installiert? # ? 3. Was speichert Save-Help? #endregion #region 2. Hilfe um und zur PowerShell verwenden (about-Seiten) # Dies so genanten about_-Seiten beschreiben die Mechaniken der PowerShell und erklären Themen wie: if, Remoting, Pipelining, Variablen, etc. # ! Eine Übersicht / Inhaltsverzeichnis aller about_-Seiten anzeigen: Get-Help -Name 'about_*' | Out-GridView -OutputMode 'Multiple' # ! Den Inhalt konkreter about_-Seiten abrufen: Get-Help -Name 'about_Arithmetic_Operators' -ShowWindow Get-Help -Name 'about_wildcards' -ShowWindow Get-Help -Name 'about_if' -ShowWindow # TIPP - HANDOUT: ('POWERSHELL-HILFE :: ABOUT-SEITEN¹' + [System.Environment]::NewLine + '=================================' + (Get-Help -Name 'about_*' | Select-Object -Property 'Name' -Unique | Sort-Object -Property 'Name' | Format-Wide -Column 2 | Out-String -Width 80) + [System.Environment]::NewLine + "¹) Beispiel-Aufruf: Get-Help -Name 'about_Operators' -ShowWindow") -split '\r\n' -replace "\s+$", [string]::Empty | Out-Printer # TIPP ... Seiten wiederholt lesen, es findet sich darin immer tiefere Informationen. # ? In allen about-Seiten nach einem Keyword suchen: Get-Help -Name 'filesystem' -Category 'HelpFile' Get-Help -Name 'Call operator' -Category 'HelpFile' # ? Quiz / Übungen zu About-Seiten # ? 1. Eine About-Seite ruf Sie auf, wenn Sie Hilfe zu was benötigen? # ? 2. Wie bekommen Sie eine komfortable Übersicht aller About-Seiten? # ? 3. Welche About-Seite enthält Informationen über die grundsätzliche Bedienung von Cmdlets? # ? 4. Welche About-Seite enthält Informationen über HashTables? # ? 5. Welche About-Seite enthält Informationen über das Ausführen von Aufgaben im Hintergrund (Jobs)? # ? 6. Welche About-Seite enthält eine Übersicht aller Operatoren in der PowerShell? # ? 7. Welche About-Seite enthält Informationen über die Syntax von Pfad-Angaben? Get-Help -Name about_*syntax* #endregion #region 3. BEFEHLSKONZEPT Command-Let (Cmdlet) # ! Ein Cmdlet aufrufen: Get-Process Microsoft.PowerShell.Management\Get-Process # z.B. Lesbarkeit erhöhen oder Doppeldeutigkeiten auflösen # |-----------------------------| => Module-Name # ! Cmdlet => Command-Let besteht aus Verb(Verb, Tätigkeit), einem Bindestrich '-' und Substantiv (Noun, Nomen, Tätigkeitsbereich) => Verb-Noun => Verb-Substantiv => Tätigkeit-Tätigkeitsbereich, z.B.: Get-Service Stop-Process # ? Welche Verben/Tätigkeit gibt es: Get-Verb | Sort-Object -Property 'Verb' | Format-Wide -AutoSize # TIPP Evtl. als Spickzettel für den Monitor ausdrucken. # ? Welche Cmdlets stoppen etwas? Get-Command -Verb 'Stop' # ? Welche Cmdlets beschäftigen sich mit dem Tätigkeitsbereich Service: Get-Command -Noun 'Service' # ! Cmdlets sind keine EXE-Dateien, sie sind *.dll oder in *.ps1 definiert. Cmdlets sind in Module zusammengefasst. Neu Cmdlets können durch die Installation eines Moduls hinzugefügt werden: Get-Command -Module 'BitLocker', 'Hyper-V' # ! Ein Cmdlet wird nur über dessen Parameter gesteuert, dabei unterscheidet man Parameter die ein Argument erwarten...: Get-ChildItem -Path 'C:\Windows' -Filter '*.exe' # ! ... und SwitchParameter die durch das Setzen das Verhalten des Cmdlets ändern: Get-ChildItem -Recurse -File # ! Das Benennen eines Parameters kann vollständig erfolgen. Es kann aber auch soweit verkürzt werden das die rechtlichen Buchstaben weggelassen werden können soweit der Rest eindeutig einem Parameter zugeordnet werden kann: Get-ChildItem -LiteralPath 'C:\Windows' Get-ChildItem -LiteralPat 'C:\Windows' Get-ChildItem -LiteralPa 'C:\Windows' Get-ChildItem -LiteralP 'C:\Windows' Get-ChildItem -Literal 'C:\Windows' Get-ChildItem -Litera 'C:\Windows' Get-ChildItem -Liter 'C:\Windows' Get-ChildItem -Lite 'C:\Windows' Get-ChildItem -Lit 'C:\Windows' Get-ChildItem -Li 'C:\Windows' Get-ChildItem -L 'C:\Windows' Get-ChildItem 'C:\Windows' # ! Ein Parameter kann auch über dessen Alias angesprochen werden: Get-ChildItem -PSPath 'C:\Users' -s -ea SilentlyContinue -af -ah -as # TODO Konsole Get-ChildItem -PSPath 'C:\Users' -Recurse -ErrorAction SilentlyContinue -File -Hidden -System # TODO In Skripten # ! Welche Parameter-Aliase ein Cmdlet unterstützt ist in der Cmdlet-Hilfe NICHT immer ersichtlich, aber wie folgt schon: Get-Command -Name 'Get-ChildItem' | Select-Object -ExpandProperty 'Parameters' | Select-Object -ExpandProperty 'Values' | Select-Object -Property 'Name', 'Aliases' # ! Ein Cmdlet kann auch dynamische Parameter besitzen die nur dann zur Verfügung stehen wenn div. Konstellationen eingetreten sind: Get-ChildItem -Path 'Cert:\CurrentUser\My' -CodeSigningCert # Den Switch-Parameter '-CodeSigningCert' gibt es nur im PowerShell-Drive 'Cert:' Get-ChildItem -Path 'C:\Temp' -Directory # Den Switch-Parameter '-Directory' gibt es nur im PowerShell-Provider 'FileSystem' # TODO Quiz: # ? 1. Woran erkennt man einen Cmdlet-Parameter? # ? 2. Welche Schreibweise für den Recurse-Parameter vom Command-Let Get-ChildItem sind korrekt: -Re -Rec -Recur -s? #endregion #region 4. Ein benötigtes Cmdlet finden # ! Siehe .\AKPT\Private\Wissen\B_Basic\B22_Cmdlet-finden.md # ! bzw. https://attilakrick.com/powershell/cmdlet-finden/ #endregion #region 5. Hilfe zu einem Cmdlet aufrufen, lesen und anwenden # ? Kurz-Information bzgl. Syntax anzeigen: Get-Command -Name 'Get-Process' -Syntax Get-Command -Name 'Enter-PSSession' -Syntax Get-Command -Name 'Where-Object' -Syntax # ? Ausführliche Informationen bzgl. der Parameter-Metadaten: Get-Command -Name 'Get-Process' -ShowCommandInfo | Select-Object -ExpandProperty 'ParameterSets' | Format-Table -Wrap # ? 'Get-Process' => Was mach das Cmdlet und wie wird es benutzt: Get-Help -Name 'Get-Process' -ShowWindow Get-Help -Name 'Get-Process' -Online # TIPP - CTRL + F1 öffnet die Online-Hilfe eines selektiertem Cmdlets (VSCode) # ? Wie wird am Beispiel von Get-Process der Syntax-Block gelesen: <# 1. Get-Process [[-Name] <String[]>] [-ComputerName <String[]>] [-Module ] [-FileVersionInfo ] [<Allgemeine Parameter>] 2. Get-Process [[-Name] <String[]>] -IncludeUserName [<Allgemeine Parameter>] 3. Get-Process -Id <Int32[]> [-ComputerName <String[]>] [-Module ] [-FileVersionInfo ] [<Allgemeine Parameter>] 4. Get-Process -Id <Int32[]> -IncludeUserName [<Allgemeine Parameter>] 5. Get-Process -InputObject <Process[]> [-ComputerName <String[]>] [-Module ] [-FileVersionInfo ] [<Allgemeine Parameter>] 6. Get-Process -InputObject <Process[]> -IncludeUserName [<Allgemeine Parameter>] #> # ! SECHS Get-Process Syntax-Zeilen, d.h. 6 verschiedene ParameterSet sind möglich. Parameter aus unterschiedlichen Sets dürfen NICHT gemischt werden: Get-Process # 1. Set wird benutzt Get-Process -Name 'notepad' -FileVersionInfo # 1. Set wird benutzt Get-Process -Name 'notepad' -IncludeUserName # 5. Set wird benutzt Get-Process -Name 'Idle' -Id 0 # ! ERROR Get-Process -Id 0 # 3. Set wird benutzt # ! [-ParaName <...>], d.h. der Parameter mit Argument ist optional: Get-Process Get-Process -Name 'notepad' # ! [[-ParaName] <...>], d.h. der Parameter mit Argument ist optional und der Parametername selbst ist optional: Get-Process -Name 'notepad' Get-Process 'notepad' # ! -Id <Int32[]>, d.h. dieser Parameter ist pflicht: Get-Process -Id 0 # ! -ParaName <...> -ParaName <...[]>, d.h. das Parameter-Argument muss vom <...>-Typ sein: Get-Process -Name 'notepad', 'explorer' # String[] => String-Array # ! [-ParaName], d.h. der Parameter ist ein Switch-Parameter (setzen = AN; sonst = AUS): Get-Process -IncludeUserName $istAn = $false Get-Process -IncludeUserName:$istAn # ! [<CommonParameters>], d.h. div. Parameter die i.d.R. an alle Cmdlets angehängt werden können (s. `Get-Help about_CommonParameters -ShowWindow`): Get-Process -FileVersionInfo -ErrorAction 'SilentlyContinue' Get-Process -FileVersionInfo -ErrorAction 'Stop' Get-Process | Stop-Process -WhatIf # TIPP - `Format-Volume -DriveLetter 'D' -WhatIf` # Das geht nicht, WAI!? # ! Parameter-Detail-Beschreibung: # ? Erforderlich => Optional | Pflicht-Parameter # ? Position => Argument-Position, wenn der Parameter-Name weg gelassen wird # ? Standardwert => Wert der benutzt wird, wenn der Parameter nicht bedient wird # ? Pipelineeingaben akzeptieren => Die Art wie Pipeline-Objekte an das Cmdlet gebunden wird # ? Platzhalterzeichen akzeptieren => Ob Wildcards wie z.B. "*" akzeptiert und als solche behandelt werden # * Erforderlich? true ODER: false # * Position? named ODER: 0, 1, 2, 3, 4, 5, usw. # * Standardwert none ODER: localhost # * Pipelineeingaben akzeptieren? false ODER: true (ByValue), true (ByPropertyName), true (ByPropertyName, ByValue) # * Platzhalterzeichen akzeptieren? false ODER: true # TIPP Get-Help intensiv nutzen! # ? Quiz / Übungen zum Cmdlet-Hilfe: # ? 1. Wann können mehrere Argumente an einen Parameter übergeben werden? # ? 2. Wie können mehrere Argumente an einen Parameter übergeben werden? # ? 3. Wo werden im Detail die Common-Parameter beschrieben? # ? 4. Warum wird das 1. ParameterSet bei folgendem Aufruf `Get-Process -Name 'notepad' -FileVersionInfo` benutzt? # ? 5. Finden Sie heraus ob bereits eine Instanz vom Windows Taschenrechner ([WIN]+[R], calc+[ENTER]) ausgeführt wird. # ? 6. Berechnen Sie mit dem Cmdlet New-TimeSpan wieviele Tage es noch bis Neujahr sind. # ? 7. Erzeugen Sie mit dem Cmdlet Get-EventLog eine Übersicht der 10 neusten Fehler aus der Windows-Ereignisanzeige "System". # ? 8. Was bewirkt die folgende Kommando-Zeile? `gci 'C:\Windows\Logs' -Rec -File -errora 'SilentlyContinue'` Und geht das noch kürzer? #endregion #region Eigene Hilfe-Inhalte erstellen Get-Help -Name "about_Script_Internationalization" -ShowWindow # Beschreibt die Funktionen zur Internationalisierung von Skripten, die es Skripten erleichtern, Nachrichten und Anweisungen für Benutzer in ihrer Benutzeroberflächensprache anzuzeigen. Get-Help -Name "about_Data_Sections" -ShowWindow # Erläutert Datenabschnitte, in denen Textzeichenfolgen und andere schreibgeschützte Daten von der Skriptlogik isoliert werden. # HILFE-ARTEN # Cmdlet => The Help topics that describe Cmdlets in a module are XML files that use the command help schema # Provider => The Help topics that describe providers in a module are XML files that use the provider help schema. # Function => The Help topics that describe functions in a module can be XML files that use the command help schema or comment-based Help topics within the function, or the script or script module # Script => The Help topics that describe scripts in a module can be XML files that use the command help schema or comment-based Help topics in the script or script module. # Conceptual ("About") => You can use a conceptual ("about") Help topic to describe the module and its members and to explain how the members can be used together to perform tasks. Conceptual Help topics are text files with Unicode (UTF-8) encoding. The file name must use the about_<name>.help.txt format, such as about_MyModule.help.txt. By default, Windows PowerShell includes over 100 of these conceptual About Help topics, and they are formatted like the following example. # <ModulePath> # \<MyModuleName> # \en-US # \about_SampleModule.help.txt # \SampleModule.dll-help.xml # \fr-FR # \about_SampleModule.help.txt # \SampleModule.dll-help.xml # Supporting Updatable Help Start-Process "https://msdn.microsoft.com/de-de/library/hh852754(v=vs.85).aspx" # Supporting Online Help Start-Process "https://msdn.microsoft.com/de-de/library/hh852737(v=vs.85).aspx" # PowerShell Cmdlet Help Editor Start-Process "https://pscmdlethelpeditor.codeplex.com" # Create XML-based help using PlatyPS # https://docs.microsoft.com/en-us/powershell/scripting/dev-cross-plat/create-help-using-platyps?view=powershell-7.1 #endregion # TODO QUIZ - https://attilakrick.com/schlagwort/powershell-hilfe/ |