o_Komentářích

Krátký popis

Popisuje, jak používat komentáře PowerShellu a uvádí zvláštní případy použití.

Dlouhý popis

Můžete psát komentáře, abyste anotovali nebo strukturovali svůj kód PowerShellu, což vám pomůže s čitelností. Když kód spustíte, PowerShell ignoruje text komentáře.

Komentáře poskytují čtenářům kódu důležitý kontext. Komentáře byste měli použít pro následující účely:

• Vysvětlit složitý kód jednoduššími termíny
• Vysvětlit, proč byl zvolen konkrétní přístup
• Zdokumentovat hraniční případy, které je potřeba znát
• Uveďte odkazy na podpůrný referenční materiál.

Některé komentáře mají v PowerShellu zvláštní význam. Viz zvláštní komentáře.

Styly komentářů PowerShellu

PowerShell podporuje dva styly komentářů:

• jednořádkové komentáře začínají znakem hash (#) a končí novým řádkem. # může předcházet text, který není součástí komentáře, včetně prázdných znaků. Jednořádkové komentáře umístěné na stejném řádku jako nekommentovaný zdrojový kód se označují jako komentáře na konci řádku.

• Blokové komentáře začínají <# a končí #>. Blokový komentář může zahrnovat libovolný počet řádků a může být zahrnut před, za nebo uprostřed nekommentovaného zdrojového kódu. Veškerý text v bloku se považuje za součást stejného komentáře, včetně prázdných znaků.

  Důležitý

  Do bloku komentáře můžete zahrnout jednořádkové komentáře. Ale nemůžete vnořit blokové komentáře. Pokud se pokusíte vnořit blokové komentáře, vnější blokový komentář končí při prvním výskytu #>.

Příklady

Příklad 1: Jednořádkový komentář

# This is a single-line comment.
# This is also a single-line comment.

Příklad 2: Blokový komentář

<#
    This is a block comment.
    Text within the block is a part of the same comment.
Whitespace is unimportant in a block comment.
#>

Příklad 3: Konec řádku komentáře

$var = 4 # This is an end-of-line comment

Příklad 4: Vložený blokový komentář

'Foo'; <# This is an inline block comment #> 'Bar'

Příklad 5: Úplný příklad

<#
    .DESCRIPTION
    Demonstrates PowerShell's different comment styles.
#>
param (
    [string] $Param1, # End-of-line comment
    <# Inline block comment #> $Param2
)

$var = 1, <# Inline block comment #> 2, 2

# Single-line comment.
# Another single-line comment.
$var.Where(
    <# Arg1 note #> { $_ -eq 2 },
    <# Arg2 note #> 'First',
    <# Arg3 note #> 1
)

Speciální komentáře

PowerShell obsahuje několik klíčových slov komentářů pro podporu konkrétních použití.

Nápověda založená na komentářích

Obsah nápovědy založený na komentářích můžete psát pro funkce a skripty pomocí jednořádkového nebo blokovacího komentáře. Uživatelé můžou pomocí rutiny Get-Help zobrazit nápovědu založenou na komentářích pro funkci nebo skript. PowerShell definuje 15 klíčových slov komentářů, která se dají použít k poskytování informací, jako je popis a příklad použití.

<#
    .DESCRIPTION
    Comment-based help using a block comment.
#>
function Get-Function { }

# .DESCRIPTION
# Comment-based help using multiple single-line comments.
function Get-Function { }

Další informace najdete tady:

• about_Comment_Based_Help
• psaní Comment-Based témata nápovědy

#Requires

Příkaz #Requires zabrání spuštění skriptu, pokud aktuální relace PowerShellu nesplňuje zadané požadavky. #Requires se může objevit na libovolném řádku skriptu, ale zpracovává se stejným způsobem bez ohledu na pozici.

#Requires -Modules AzureRM.Netcore
#Requires -Version 6.0

param (
    [Parameter(Mandatory)]
    [string[]] $Path
)

Další informace najdete ve zdroji about_Requires.

Blok podpisu

Skripty je možné podepsat, aby dodržovaly zásady spouštění PowerShellu. Po podepsání se na konec skriptu přidá blok podpisu. Tento blok má formu několika jednořádkových komentářů, které před spuštěním skriptu načtou PowerShell.

# SIG # Begin signature block
# ...
# SIG # End signature block

Další informace viz about_signing.

Shebang

V systémech typu Unix je shebang (#!) direktiva použitá na začátku skriptu, která označuje, jaká shell by měla být použita ke spuštění skriptu. Shebang není součástí jazyka PowerShellu. PowerShell ho interpretuje jako běžný komentář. Shebang je interpretován operačním systémem.

V následujícím příkladu shebang zajišťuje, že PowerShell spustí skript při vyvolání skriptu z kontextu jiného prostředí než PowerShell.

#!/usr/bin/env pwsh
Write-Host 'Begin script'

Značky oblastí editoru kódu

Některé editory kódu podporují značky oblastí, které umožňují sbalit a rozbalit části kódu. V PowerShellu jsou komentáře, které označují oblasti, začínající #region a končící #endregion. Značky oblastí musí být na začátku řádku. Značky oblastí jsou podporované v integrovaném skriptovacím prostředí (ISE) PowerShellu a v editoru Visual Studio Code s rozšířením PowerShellu. Značky oblastí nejsou součástí jazyka PowerShellu. PowerShell je interpretuje jako běžné komentáře.

Další informace najdete v části Skládání a v části Základní úpravy v editoru Visual Studio Code dokumentace.

Komentáře v řetězcových tokenech

# a <# #> nemají zvláštní význam v rámci rozbalitelného nebo doslovného řetězce. PowerShell interpretuje znaky doslova.

PS> '# This is not interpreted as a comment.'
# This is not interpreted as a comment.

PS> "This is <# also not interpreted #> as a comment."
This is <# also not interpreted #> as a comment.

Některé funkce PowerShellu jsou ale navržené tak, aby fungovaly s řetězci, které obsahují komentáře. Interpretace komentáře závisí na konkrétní funkci.

Komentáře regulárních výrazů

Regulární výrazy (regex) v PowerShellu používají modul regulárních výrazů .NET, který podporuje dva styly komentářů:

• Vložený komentář ((?#))
• Komentář na konci řádku (#)

Komentáře regulárních výrazů jsou podporovány všemi funkcemi založenými na regulárních výrazech v PowerShellu. Například:

PS> 'book' -match '(?# This is an inline comment)oo'
True

PS> 'book' -match '(?x)oo# This is an end-of-line comment'
True

PS> $regex = 'oo # This is an end-of-line comment'
PS> 'book' -split $regex, 0, 'IgnorePatternWhitespace'
b
k

Poznámka

Koncový komentář regulárního výrazu vyžaduje buď konstrukci (?x), nebo volbu IgnorePatternWhitespace.

Další informace najdete tady:

• about_Regular_Expressions
• Různé konstrukce v regulárních výrazech

Komentáře JSON

Počínaje PowerShellem 6.0 podporuje rutina ConvertFrom-Json následující styly komentářů JSON:

• Jednořádkový komentář (//)
• Blokový komentář (/* */)

Poznámka

Rutina Invoke-RestMethod automaticky deserializuje přijatá data JSON. V PowerShellu 6.0 jsou komentáře povolené v datech JSON.

Například:

'{
    "Foo": "Bar" // This is a single-line comment
}' | ConvertFrom-Json

Foo
---
Bar

Varování

Počínaje PowerShellem 7.4 už rutina Test-Json nepodporuje JSON s komentáři. Pokud JSON obsahuje komentáře, vrátí se chyba. V podporovaných verzích starších než 7.4 Test-Json úspěšně parsuje JSON s komentáři. V PowerShellu 7.5 Test-Json obsahuje možnost ignorovat komentáře JSON.

Komentáře CSV

Import-Csv a ConvertFrom-Csv podporují formát rozšířeného protokolu W3C. Řádky začínající znakem hash (#) se považují za komentáře a ignorují se, pokud komentář nezačíná #Fields: a neobsahuje seznam názvů sloupců s oddělovači. V takovém případě rutina používá tyto názvy sloupců. Toto je standardní formát pro službu Windows Internet Information Services (IIS) a další záznamy webového serveru. Další informace naleznete v tématu Rozšířený formát souboru protokolu.

@'
# This is a CSV comment
Col1,Col2
Val1,Val2
'@ | ConvertFrom-Csv

Col1 Col2
---- ----
Val1 Val2

Ve Windows PowerShellu 5.1 je výchozím chováním Export-Csv a ConvertTo-Csv zahrnout informace o typu ve formě komentáře #TYPE. Počínaje PowerShellem 6.0 není výchozím nastavením zahrnout komentář, ale lze ho přepsat pomocí parametru IncludeTypeInformation.

[pscustomobject] @{ Foo = 'Bar' } | ConvertTo-Csv -IncludeTypeInformation

#TYPE System.Management.Automation.PSCustomObject
"Foo"
"Bar"

Pokud je v datech CSV zahrnut komentář #TYPE, Import-Csv a ConvertFrom-Csv tyto informace použijí k nastavení vlastnosti pstypenames u deserializovaných objektů.

class Test { $Foo = 'Bar' }
$test = [Test]::new()

$var = $test | ConvertTo-Csv -IncludeTypeInformation | ConvertFrom-Csv
$var.pstypenames

Test
CSV:Test

ConvertFrom-StringData komentáře

V řetězcových datech rutina ConvertFrom-StringData zpracovává řádky začínající # jako komentáře. Další informace najdete tady:

• Příklad 3: Převedení řetězce sem obsahujícího komentář

Poznámky

• Blokové komentáře nelze vnořit. V následujícím příkladu Baz není součástí komentáře.

  <#
  'Foo'
  <# 'Bar' #>
  'Baz'
  #>
  

• <# #> v jednom řádku komentáře nemá žádný zvláštní význam. # nemá v komentáři bloku žádný zvláštní význam.

• Aby se s ním zacházelo jako s komentářem, nesmí být znak komentáře součástí tokenu bez komentáře. V následujícím příkladu jsou #Bar a <#Bar#> součástí tokenu Foo.... Proto se s nimi nezachází jako s komentáři.

  PS> Foo#Bar
  Foo#Bar: The term 'Foo#Bar' is not recognized as a name [...]
  
  PS> Foo<#Bar#>
  Foo<#Bar#>: The term 'Foo<#Bar#>' is not recognized as a name [...]