Udostępnij za pośrednictwem

about_Comments

  • Artykuł

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
  • Przypadki brzegowe dokumentu, na które należy zwrócić uwagę
  • Udostępnianie linków do materiałów referencyjnych pomocniczych

Niektóre komentarze mają specjalne znaczenie w programie PowerShell. Zobacz komentarze 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ą się na #>. Komentarz blokowy może obejmować dowolną liczbę wierszy i można go umieścić przed niekomentowanym kodem źródłowym, po nim lub w jego środku. Cały tekst w bloku jest traktowany jako część tego samego komentarza, w tym białe znaki.

    Ważny

    Możesz uwzględnić komentarze jednowierszowe w komentarzu blokowym. Nie można jednak zagnieżdżać komentarzy blokowych. Jeśli próbujesz zagnieżdżać komentarze blokowe, komentarz bloku zewnętrznego kończy się przy pierwszym napotkaniu #>.

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 bloku wbudowanego

'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 wspierania określonych zastosowań.

Pomoc oparta na komentarzach

Możesz tworzyć zawartość pomocy w oparciu o komentarze 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:

#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, zapoznaj się z 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, zobacz dotyczące_podpisywania.

shebang

W systemach przypominających system Unix shebang (#!) jest dyrektywą używaną na początku skryptu w celu wskazania, która powłoka powinna być używana do uruchamiania skryptu. Shebang nie jest częścią języka programu PowerShell. Program PowerShell interpretuje go jako zwykły komentarz. Shebang jest interpretowany przez system operacyjny.

W poniższym przykładzie shebang zapewnia, że program PowerShell uruchamia skrypt po wywołaniu skryptu z kontekstu innego niż program PowerShell.

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

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 linii. 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ę składania w dokumentacji Podstawowa edycja w programie Visual Studio Code.

Komentarz w tokenach łańcuchów znakó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ą silnika regex 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

Notatka

Komentarz końca wiersza wyrażenia regularnego wymaga konstrukcji (?x) lub opcji IgnorePatternWhitespace.

Aby uzyskać więcej informacji, zobacz:

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 (/* */)

Notatka

Polecenie cmdlet Invoke-RestMethod automatycznie deserializuje odebrane dane JSON. W programie PowerShell 6.0 komentarze są dozwolone w danych JSON.

Na przykład:

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

Foo
---
Bar

Ostrzeżenie

Począwszy od programu PowerShell 7.4, polecenie cmdlet Test-Json nie obsługuje już formatu JSON z komentarzami. Jeśli kod JSON zawiera komentarze, zostanie zwrócony błąd. W obsługiwanych wersjach wcześniejszych niż 7.4 Test-Json pomyślnie analizuje dane JSON z komentarzami. W programie PowerShell 7.5 Test-Json zawiera opcję ignorowania komentarzy JSON.

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 oddzieloną 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 i ConvertTo-Csv jest zawarcie 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ą tych informacji do ustawienia właściwości pstypenames obiektów deserializowanych.

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

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

Test
CSV:Test

ConvertFrom-StringData komentarze

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

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 blokowym.

  • Aby być traktowanym jako komentarz, znak komentarza nie może być częścią tokenu niebędącego komentarzem. 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 [...]