informacje_o_Komentarzach

Krótki opis

Opisuje sposób używania komentarzy programu PowerShell i zawiera listę specjalnych przypadków użycia.

Długi opis

Możesz napisać komentarze do adnotacji lub struktury kodu programu PowerShell, aby ułatwić czytelność. Po uruchomieniu kodu tekst komentarza jest ignorowany przez program PowerShell.

Komentarze zawierają ważny kontekst dla czytelników kodu. W następujących celach należy użyć komentarzy:

• Objaśnienie złożonego kodu w prostszych terminach
• Wyjaśnienie, dlaczego wybrano konkretne podejście
• Uwzględnianie przypadków krawędzi dokumentu
• Udostępnianie linków do materiałów referencyjnych pomocniczych

Niektóre komentarze mają specjalne znaczenie w programie PowerShell. Zobacz uwagi specjalne.

Style komentarzy programu PowerShell

Program PowerShell obsługuje dwa style komentarzy:

• komentarze jednowierszowe zaczynają się od znaku skrótu (#) i kończą się nowym wierszem. # można poprzedzić tekstem, który nie jest częścią komentarza, w tym odstępami. Komentarze jednowierszowe umieszczone w tym samym wierszu co kod źródłowy bez komentarza są nazywane komentarzami końcowymi.

• Komentarze blokowe zaczynają się od <# i kończą #>. Komentarz blokowy może obejmować dowolną liczbę wierszy i może być umieszczony przed nieskomentowanym kodem źródłowym, po nim lub w jego środku. Cały tekst w bloku jest traktowany jako część tego samego komentarza, w tym znaki odstępu.

  Ważny

  Komentarze jednowierszowe można uwzględnić w komentarzu blokowym. Nie można jednak zagnieżdżać komentarzy blokowych. Jeśli próbujesz umieszczać w sobie komentarze blokowe, komentarz blokowy zewnętrzny kończy się na pierwszym napotkanym #>.

Przykłady

Przykład 1. Komentarz jednowierszowy

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

Przykład 2. Blokuj komentarz

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

Przykład 3: komentarz końca wiersza

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

Przykład 4. Komentarz blokowy szeregowy

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

Przykład 5. Pełny przykład

<#
    .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
)

Komentarze specjalne

Program PowerShell zawiera kilka słów kluczowych komentarzy do obsługi określonych zastosowań.

Pomoc oparta na komentarzach

Możesz napisać pomoc odnoszącą się do komentarzy dla funkcji i skryptów, używając komentarzy jednowierszowych lub blokowych. Użytkownicy mogą użyć polecenia cmdlet Get-Help, aby wyświetlić pomoc opartą na komentarzach dla funkcji lub skryptu. Program PowerShell definiuje 15 słów kluczowych komentarzy, których można użyć do udostępniania informacji, takich jak opis i przykładowe użycie.

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

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

Aby uzyskać więcej informacji, zobacz:

• Pomoc_oparta_na_komentarzach
• Pisanie Comment-Based Tematy pomocy

#Requires

Instrukcja #Requires uniemożliwia uruchomienie skryptu, chyba że bieżąca sesja programu PowerShell spełnia określone wymagania wstępne. #Requires może pojawić się w dowolnym wierszu skryptu, ale jest przetwarzany w taki sam sposób, niezależnie od pozycji.

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

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

Aby uzyskać więcej informacji, zobacz about_Requires.

Blok podpisu

Skrypty mogą być podpisane, aby były zgodne z zasadami wykonywania programu PowerShell. Po podpisaniu blok podpisu zostanie dodany na końcu skryptu. Ten blok ma postać wielu komentarzy jednowierszowych, które są odczytywane przez program PowerShell przed wykonaniem skryptu.

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

Aby uzyskać więcej informacji, proszę zapoznać się z about_Signing.

Znaczniki regionów edytora kodu

Niektóre edytory kodu obsługują znaczniki regionów, które umożliwiają zwinięcie i rozwinięcie sekcji kodu. W przypadku programu PowerShell znaczniki regionów to komentarze, które zaczynają się od #region i kończą się #endregion. Znaczniki regionu muszą znajdować się na początku wiersza. Znaczniki regionów są obsługiwane w programie PowerShell ISE i w programie Visual Studio Code z rozszerzeniem programu PowerShell. Znaczniki regionów nie są częścią języka programu PowerShell. Program PowerShell interpretuje je jako zwykłe komentarze.

Aby uzyskać więcej informacji, zobacz sekcję Zwijanie w dokumentacji Podstawowe edytowanie w programie Visual Studio Code.

Komentarze w tokenach ciągów

# i <# #> nie mają specjalnego znaczenia w rozszerzalnym lub dosłownym ciągu. Program PowerShell interpretuje znaki dosłownie.

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.

Jednak niektóre funkcje programu PowerShell są przeznaczone do pracy z ciągami zawierającymi komentarze. Interpretacja komentarza zależy od określonej funkcji.

Komentarze wyrażeń regularnych

Wyrażenia regularne (regex) w programie PowerShell używają aparatu wyrażeń regularnych platformy .NET, który obsługuje dwa style komentarzy:

• Komentarz wbudowany ((?#))
• Komentarz końca wiersza (#)

Komentarze wyrażeń regularnych są obsługiwane przez wszystkie funkcje oparte na wyrażeniach regularnych w programie PowerShell. Na przykład:

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

Aby uzyskać więcej informacji, zobacz:

• o_Wyrażeniach_Regularnych
• różne konstrukcje w wyrażeniach regularnych

Komentarze JSON

Począwszy od programu PowerShell 6.0, polecenie cmdlet ConvertFrom-Json obsługuje następujące style komentarzy JSON:

• Komentarz jednowierszowy (//)
• Blokuj komentarz (/* */)

Na przykład:

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

Foo
---
Bar

Komentarze CSV

Import-Csv i ConvertFrom-Csv obsługują rozszerzony format dziennika W3C. Wiersze rozpoczynające się od znaku hash (#) są traktowane jako komentarze i ignorowane, chyba że komentarz zaczyna się od #Fields: i zawiera rozdzieloną listę nazw kolumn. W takim przypadku polecenie cmdlet używa tych nazw kolumn. Jest to standardowy format dla usług IIS systemu Windows i innych dzienników serwera sieci Web. Aby uzyskać więcej informacji, zobacz rozszerzony format pliku dziennika.

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

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

W programie Windows PowerShell 5.1 domyślnym zachowaniem Export-Csv-Csv i ConvertTo-Csv jest uwzględnienie informacji o typie w postaci komentarza #TYPE. Począwszy od programu PowerShell 6.0, ustawieniem domyślnym nie jest dołączenie komentarza, ale można go zastąpić parametrem IncludeTypeInformation.

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

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

Gdy komentarz #TYPE jest uwzględniony w danych CSV, Import-Csv i ConvertFrom-Csv używają tej informacji, aby ustawić właściwość pstypenames obiektów deserializowanych.

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

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

Test
CSV:Test

komentarze ConvertFrom-StringData

W danych tekstowych polecenie cmdlet ConvertFrom-StringData traktuje wiersze zaczynające się od znaku # jako komentarze. Aby uzyskać więcej informacji, zobacz:

• Przykład 3: konwertowanie tutaj-ciągu zawierającego komentarz

Notatki

• Nie można zagnieżdżać komentarzy blokowych. W poniższym przykładzie Baz nie jest częścią komentarza.

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

• <# #> nie ma specjalnego znaczenia w jednym wierszu komentarza. # nie ma specjalnego znaczenia w komentarzu bloku.

• Aby być traktowanym jako komentarz, znak komentarza nie może być częścią tokenu bez komentarza. W poniższym przykładzie #Bar i <#Bar#> są częścią tokenu Foo.... W związku z tym nie są traktowane jako komentarze.

  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 [...]