Powershell комментарии: PowerShell — Commenting | powershell Tutorial
Подключение к Azure AD с помощью PowerShell
В этой статье мы рассмотрим, как установить PowerShell модуль для подключения к Azure AD, подключится к своему тенанту и получить различную информацию из Azure. Сейчас Microsoft разрешает использовать два PowerShell модуля для подключения к Azure:
- MS Online (MSOnline) – старый модуль для работы с Azure/Office 365 из PowerShell, который появился около 6 лет назад и сейчас не развивается Microsoft;
- Azure Active Directory PowerShell for Graph (AzureAD) – современный PowerShell модуль для работы с инфраструктурой Azure. Модуль активно развивается, в него добавляется новый функционал (в нем доступны почти все аналоги командлетов MSOnline за небольшим исключением)
Теперь можно установить модуль Azure PowerShell из PowerShell Gallery. Запустите консоль PowerShell с правами администратора и выполните команду:
Install-Module -Name AzureAD
Появится сообщение:
Untrusted repository. You are installing the modules from an untrusted repository. If you trust this repository, change its InstallationPolicy value by running the Set-PSRepository cmdlet.
Нажмите Y -> Enter
Вы можете добавить галерею PowerShell в доверенные хосты с помощью команды:
Set-PSRepository -Name PSGallery -InstallationPolicy Trusted
После окончания установки, можно проверить версию модуля AzureAD:
Get-Module AzureAD –ListAvailable
В нашем случае это 2.0.2.130
В этой версии модуля AzureAD доступно 222 командлета, которые содержат в названии *-AzureAD*. Список доступных команды можно вывести так:
Get-Command –Module AzureAD
Если у вас установлена более старая версия модуля AzureAD, ее можно обновить:
Update-Module -Name AzureAD
Если нужно установить определенную версию модуля, выполните:
Update-Module -Name AzureAD -RequiredVersion 2.0.2.120
Теперь можно подключиться в Azure с помощью вашего аккаунта:
Connect-AzureAD
Командлет запросит ввести учетные данные, которые вы хотите использовать для доступа к каталогу AzureAD. В этом примере для доступа к моему тенанту я использую учетную запись [email protected].
Если у вас включен Azure MFA, подтвердите в вход в аккаунт на устройстве.
Также можно запросить имя и пароль для подключения и сохранить их в переменную:
$AzureADcreds = Get-Credential
И затем использовать их для подключения:
Connect-AzureAD -Credential $AzureADcreds
Командлет возвращает подтверждение, показывающее, что сеанс был успешно подключен к каталогу. В строке будет указано окружение AzureCloud, TenantID и TenantDomain.
Для подключения к некоторым специализированным облакам AzureOffice 365 нужно указывать параметр -AzureEnvironmentName.
Connect-AzureAD -AzureEnvironmentName AzureChinaCloud
Connect-AzureAD -AzureEnvironmentName AzureGermanyCloud
Connect-AzureAD -AzureEnvironmentName AzureUSGovernment
По умолчанию модуль подключается к облаку Worldwide.
Информацию о текущем тенанте Azure можно вывести так:
Get-AzureADTenantDetail
Теперь вы можете использовать командлеты модуля AzureAD для получения различной информации из домена. Найдем пользователей, чьи имена начинаются с Dmit:
get-azureaduser -SearchString Dmit
Или список облачных групп в AzureAD:
Get-AzureADGroup
Чтобы получить список доступных лицензий, которые доступны в вашей подписке Office 365 используется командлет:
Get-AzureADSubscribedSku | select SkuPartNumber, ConsumedUnits
Можно определить, какая лицензия назначена определенному аккаунту:
Get-AzureADUser -SearchString [email protected] | Select -ExpandProperty AssignedLicenses
Затем по полученному SkuID можно узнать имя лицензии:
Get-AzureADSubscribedSku | Where {$_.SkuId -eq "6123434-b223-4332-babcd-1e9231231235"}
Чтобы в сессии PowerShell отключится от Azure, выполните:
Disconnect-AzureAD
xml — PowerShell XmlReader в XmlWriter, встроенные комментарии переходят на новую строку
Учитывая XML-файл
<root>
<!-- Block comment -->
<node />
<!-- Block comment -->
<node /> <!-- Inline comment -->
</root>
И этот код
function Write-XmlToConsole ($xml) {
$stringWriter = [System. Io.StringWriter]::new()
$xmlWriter = [System.Xml.XmlTextWriter]::new($stringWriter)
$xmlWriter.Formatting = "indented"
$xmlWriter.Indentation = 4
$xml.WriteTo($xmlWriter)
$xmlWriter.Flush()
$stringWriter.Flush()
Write-Host $stringWriter.ToString()
Write-Host
Write-Host
}
$fileStream = [System.Io.fileStream]::New("$psScriptRoot\File.xml", [System.Io.FileMode]::Open, [System.Io.FileAccess]::Read, [System.Io.FileShare]::ReadWrite)
$xmlReaderSettings = [Xml.XmlReaderSettings]::new()
$xmlReaderSettings.CloseInput = $true
#$xmlReaderSettings.IgnoreComments = $true
$xmlReaderSettings.IgnoreProcessingInstructions = $true
$xmlReaderSettings.IgnoreWhitespace = $true
$xmlreader = [System.Xml.Xmlreader]::Create($fileStream, $xmlReaderSettings)
$importFile = [System.Xml.XmlDocument]::new()
$importFile.Load($xmlreader)
$importFile.Save("$psScriptRoot\New.xml")
Write-XmlToConsole $importFile
Я ожидаю, что и новый файл, и вывод консоли будут соответствовать оригиналу. Однако в обоих случаях встроенный комментарий переносится на новую строку. Мне не хватает настройки в XmlReader или XmlWriter? Или это просто невозможно?
Кроме того, причина, по которой я обеспокоен, заключается в том, что я в конечном итоге хочу иметь возможность проверять XML способом, который не поддается XSD, а именно, что часть загруженного XML будет использоваться для текущего рабочего процесса, а часть — нет, поэтому Я хочу проверить и потерпеть неудачу, если неудачная проверка повлияет на рабочий процесс, но если это не повлияет на рабочий процесс, я хочу продолжить, регистрируя ошибку проверки, чтобы пользователь мог решить ее, прежде чем она повлияет на рабочий процесс. И в этом журнале я хочу указать номер строки, для чего требуется, чтобы комментарии обрабатывались правильно, чтобы номер строки совпадал. Но второй вопрос: как извлечь номер строки, например, последнего <node />
?
РЕДАКТИРОВАТЬ: еще больше усложняет ситуацию, если я сделаю один из двух комментариев блока двухстрочным комментарием, например
<!-- Block comment
Line 2 -->
Я получаю сообщение об ошибке «Недопустимый символ» во второй строке <node />
, которая следует сразу за комментарием, но XML проверяется нормально при копировании / вставке в единственный валидатор XML.
EDIT2: не уверен, что это имеет значение, но исходный файл XML был создан с помощью NotePad ++.
EDIT3: если у меня нет настоящего комментария блока, результат выглядит как
<root>
<!-- Block comment -->
<node />
<!-- Block comment -->
<node />
<!-- Inline comment -->
</root>
Если я изменю второй комментарий блока на настоящий блок, как этот
<root>
<!-- Block comment -->
<node />
<!-- Block comment
Second Line -->
<node />
<!-- Inline comment -->
</root>
Я получаю эту ошибку
Exception calling "Load" with "1" argument(s): "'.', hexadecimal value 0x00, is an invalid character. Line 7, position 8."
At \\Mac\iCloud Drive\Px Tools 4.#\# Dev 4.0\##Spikes\XML Comments handling\XMLcomments.ps1:27 char:1
0
Gordon
24 Ноя 2020 в 12:15
Dell Storage Center Command Set 7.
1 for Windows PowerShell Release Notes
Выполняется загрузка, подождите
Данные для раздела недоступны
Оценить этот контент
Функционально
Просто понять
Отправьте нам свое мнение (Опционально)
0/3000 characters
Комментарии не должны содержать следующие специальные символы: ()\
Комментарии не должны содержать следующие специальные символы: ()\
Благодарим вас за отзыв.
Поставьте оценку (1–5 звезд).
Поставьте оценку (1–5 звезд).
Поставьте оценку (1–5 звезд).
Выберите ответ на вопрос, была ли статья полезной.
Комментарии не должны содержать следующие специальные символы: <>()\
Включайте в сценарии PowerShell справочную информацию | Windows IT Pro/RE
Один из самых эффективных инструментов, которые помогают пользователям изучать механизмы оболочки PowerShell, — ее справочная система, и в первую очередь — команда Get-Help. Для изучающих среду PowerShell это одна из трех ключевых команд (остальные две — команды Get-Command и Get-Member). Если вам когда-либо доводилось работать с технологией PowerShell, вы, скорее всего, использовали команду Get-Help (или один из ее псевдонимов — help и man).
Справочная система загружается автоматически в ходе установки оболочки PowerShell, но если вы работаете с третьей или более новой версией этого продукта, не забудьте выполнить команду Update-Help при первом запуске PowerShell и регулярно запускать ее в дальнейшем. Дело в том, что Microsoft постоянно добавляет в справочную систему новые темы и исправляет ошибки в существующих темах, обнаруженные сотрудниками компании, а также другими пользователями. Предоставляя возможность выполнять команду Update-Help на вашей системе, Microsoft позволяет вам экономить значительную часть дискового пространства: ведь на вашу машину загружаются средства поддержки лишь того языка, который вы определили для своей системы, а не для всех языков, которые, возможно, указала система.
Сценарий PowerShell Get-Help
Однако помощь, получаемая вами от PowerShell, — это еще не все. Взяв за основу справочную функцию на базе комментариев, реализованную разработчиками во второй версии PowerShell, вы можете предоставить такую же помощь будущим пользователям написанных вами функций и сценариев. В этой версии добавлена возможность включения в сценарии многострочных комментариев. В качестве разделителей этих комментариев применяются пары символов ». Используются они следующим образом:
# Любой однострочный комментарий
Сюда может быть включено любое число комментариев.
#>Как применять справочную информацию
И как же использовать справочные данные в соответствии с вашим замыслом? В сущности все довольно просто. Достаточно определить в комментарии несколько ключевых слов и поместить комментарий в начало вашего сценария или в начало функции, и тогда каждый, кто будет пользоваться этим сценарием или функцией, сможет получить помощь точно таким же образом, каким вы получали нужные сведения с помощью команды Get-Help.
Ключевые слова, которые вы будете использовать, называются тегами. Я применяю такие базовые теги:. SYNOPSIS,. DESCRIPTION и. EXAMPLE. Тег. SYNOPSIS позволяет дать краткое определение задачи, выполняемой сценарием или функцией. Тег. DESCRIPTION дает возможность представить более детальные сведения, а тег. EXAMPLE позволяет привести примеры применения вашего сценария или функции с тем, чтобы пользователь понял, как следует должным образом их вызывать. Ниже помещается раздел комментариев из сценария, который я использую для того, чтобы присвоить владельцам всех баз данных имя 'sa'.
Вы также можете применять такие теги, как. PARAMETER для описания параметров, используемых в вашем коде,. INPUTS для описания типов объектов, которые могут быть переданы в ваш код по конвейеру, или. OUTPUTS для описания объектов, передаваемых на конвейер,. NOTES для передачи дополнительной информации,. LINK для передачи ссылок на дополнительные источники и т.д.
Сценарий PowerShell get-Help Set-Database
Включая подобного рода справочные данные в сценарии или функции, вы облегчите для тех, кто будет запускать их в дальнейшем, понимание того, какую задачу выполняет ваш код и как его следует использовать. Я обнаружил, что и мне самому эти данные помогают вспомнить, как пользоваться сценариями, которые я написал некоторое время назад.
Включайте в сценарии PowerShell справочную информацию
Поделитесь материалом с коллегами и друзьями
Как добавить комментарий к объекту GPO
Добрый день! Уважаемые читатели и гости IT блога Pyatilistnik.org. В прошлый раз мы с вами рассмотрели вопрос по отключению тестового режима Windows 10. Сегодня мы поговорим про очень полезную вещь, которая позволит вашей инфраструктуре Active Directory, быть более описанной и задокументированной. В данной заметке пойдет речь, о добавлении комментариев к объектам групповой политики. Будьте профессионалами, не ленитесь делать такие простые вещи.
Нужны комментарии или нет
Лично я всегда придерживался концепции, что если сервис, оборудование или софт позволяет оставить какой-либо комментарий, то нужно не лениться и всегда это делать, по ряду причин:
- Во первых через какое-то время вы сами можете забыть, что настраивали и за что, это отвечает. В такой ситуации наличие описания, или комментария сильно упростит понимание, что это и для чего, сэкономит вам некоторое время.
- Во вторых групповые политики не всегда в составе своего имени несут смысл своего назначения, так как в название не запихнешь всего и вот наличие подробного описание в виде комментариев, очень сильно вам поможет с поиском нужной политики или параметров. Я много раз встречал в различных организациях наличие большого количества групповых политик, применяемых к объектам AD, и в большинстве случаев, когда нужно понять из-за какой политики применяется та или иная настройка, администраторы тратили уйму времени, чтобы это отыскать. Элементарные комментарии сильно бы упростили им их задачу.
- В третьих, когда у вас порядок, то вам проще передавать дела на время отпуска или в связи со сменой работы, согласитесь, что когда приходишь на новое место и входишь в курс дел, так где все службы и настройки задокументированы, проще вникнуть в режим работы инфраструктуры, не желе так, где был безалаберный администратор, который считал, все это своей тайном и чтобы его не удалили, специально не посвящал в детали никого. Это лишь показывает его неуверенность и не профессионализм, за такое отношение они часто попадают в конфликтные ситуации.
Методы позволяющие задать комментарий в GPO
Существует два способа, которые позволят вам оставить комментарии в видео описаний к вашим объектам групповой политики:
- Использование оснастки «Управление групповой политикой (GPMC)»
- Командлеты PowerShell
Давайте проставим комментарий через графический интерфейс GPMC. Выберите нужную вам политику и щелкните по ней правым кликом, из контекстного меню выберите пункт «Изменить».
Далее вы кликаете по корню и из меню выбираете пункт «Свойства».
В открывшемся окне свойств, перейдите на вкладку «Комментарий» и в примечании введите нужное вам описание. Сохраняем изменения и закрываем окно.
Перейдите теперь на вкладку «Сведения» и проверьте, что у вас появилось описание в комментариях.
Теперь попробуем выполнить то же самое, но с использованием PowerShell. Откройте PowerShell от имени администратора. первым делом мы посмотрим все политики и есть ли у них описание, для этого:
get-gpo -All | FT DisplayName,Description,ID
В итоге я виду, имя объекта GPO, описание (Description) и ID (GUID).
Теперь зная GUID поменяем текст комментария.
(Get-GPO -Guid ’49df37c4-d9af-48d0-85aa-96e91b6cc13a’).Description=’Новое описание политики’
Смотрим все групповые политики и видим, что описание у GPO изменилось.
Или можно изменить по имени политики.
(Get-GPO -Name ‘Управление UIPI’).Description=’Еще раз изменил комментарий’
Как видите, все очень просто, быстро и полезно. Надеюсь, что вы теперь найдете желание и время, чтобы привести в порядок ваше описание политик GPO. С вами был Иван Семин, автор и создатель IT портала Pyatilistnik.org.
Руководство по Windows PowerShell для начинающих
В этой статье про PowerShell для начинающих мы посмотрим, как писать скрипты, которые помогают оптимизировать управление Windows-окружением.
PowerShell — это объектно-ориентированный программный движок и скриптовый язык с интерфейсом командной строки, предоставляющий широкие возможности для конфигурирования операционных систем семейства MS Windows. Он предлагает как чисто консольный интерфейс, так и полноценную среду разработки PowerShell ISE (Integrated Scripting Environment, встроенное скриптовое окружение) для скриптов.
Для запуска интерфейса командной строки введите powershell
в меню «Выполнить» (WinKey + R). PowerShell ISE запускается с помощью команды «PowerShell ISE» в том же меню. ISE более предпочтительно, так как предоставляет более широкие возможности разработчику благодаря подсветке синтаксиса, функции автозаполнения кода и другим особенностям, присущим многим «большим» IDE.
Среда разработки Windows PowerShell ISE
Написание и запуск скриптов
Скрипты сохраняются в виде файлов с расширением .ps1
. Несмотря на то, что PowerShell уже давно является нативной частью ОС Windows, вы не сможете запустить его скрипты простым двойным щелчком. Для этого надо кликнуть правой кнопкой по скрипту и выбрать «Запустить в PowerShell».
Также существуют системные политики, ограничивающие выполнение скриптов. Можно проверить текущие параметры политики, введя команду Get-ExecutionPolicy
. Результатом будет одно из следующих значений:
- Restricted — выполнение скриптов запрещено. Стандартная конфигурация;
- AllSigned — можно запускать скрипты, подписанные доверенным разработчиком; перед запуском скрипта PowerShell запросит у вас подтверждение;
- RemoteSigned — можно запускать собственные скрипты или те, что подписаны доверенным разработчиком;
- Unrestricted — можно запускать любые скрипты.
Для начала работы необходимо изменить настройку политики запуска на RemoteSigned, используя команду Set-ExecutionPolicy
:
После выполнения команды можно будет запускать свои скрипты
Командлеты
Командлеты — это команды с предопределённой функцией, подобные условным операторам в языках программирования. У них есть несколько ключевых особенностей:
- существуют системные, пользовательские и опциональные командлеты;
- результатом выполнения командлета будет объект или массив объектов;
- командлеты могут обрабатывать данные и передавать их другим командлетам с помощью конвейеров;
- командлеты нечувствительны к регистру, так что нет никакой разницы между
Get-ADUser
,get-aduser
иgEt-AdUsEr
; - в качестве разделителя используется символ
;
.
Каждый командлет содержит в себе глагол и существительное, разделяемые дефисом. Например:
- Get-Process — отобразить текущие процессы, запущенные на компьютере;
- Get-Service — отобразить список служб и их статус;
- Get-Content — отобразить содержимое указанного файла, например
Get-Content C:\Windows\System32\drivers\etc\hosts
.
При необходимости список всех доступных командлетов можно вывести с помощью Get-Help-Category. Запомните эту команду — она крайне важна для тех, кто изучает PowerShell с нуля, так как помогает быстрее начать ориентироваться в его возможностях.
Результат выполнения команды Get-Help-Category
Также можно создавать свои командлеты, но эта тема выходит за рамки нашего руководства по PowerShell для начинающих.
Параметры
У каждого командлета есть несколько параметров, определяющих его работу. PowerShell ISE автоматически предлагает все доступные параметры с отображением их типа. Например, Get-Service-NameW*
выводит список служб, у которых имя начинается с W
. Если вы забыли, какие параметры у введённого командлета, воспользуйтесь Get-Member
.
Например, Get-Process | Get-Member
:
Список параметров командлета Get-Process
Если вы не нашли того, что нужно, или не уверены в том, как правильно задаются параметры, можно даже запросить примеры с помощью параметра -Examples
. Встроенное руководство по PowerShell покажет, для чего используются разные параметры:
Примеры использования командлета
Некоторые командлеты также могут вызываться с помощью алиасов. Например, вместо Get-Help
можно просто написать Help
— эта команда также вызовет встроенное руководство по PowerShell.
При написании больших скриптов или коллективной разработке можно пользоваться комментариями. Каждый комментарий начинается с символа #
, а блок комментариев ограничивается комбинациями символов <#
и #>
в начале и в конце соответственно.
Конвейер
PowerShell позволяет осуществлять обмен данными между командлетами с помощью конвейера. Например:
GetService | SortObject -property Status
— сортировка запущенных служб по статусу;“Hello World!” | Out-File C:\ps\test.txt
— запись текста в файл.
Можно использовать несколько конвейеров. Например, следующий скрипт выводит список имён всех служб за исключением остановленных:
Get-Service | WHERE {$_.status -eq “Running”} | SELECT displayname
Заключение
Это руководство для тех, кто изучает PowerShell с нуля, поэтому здесь раскрыты только базовые понятия и приёмы. После его прочтения у вас должно появиться представление о том, что собой представляет этот инструмент. Также мы рассмотрели варианты изменения политики выполнения скриптов, что такое командлет, как они обмениваются данными с помощью конвейера и как получить свойства нужного объекта. Помните, что в случае затруднений можно воспользоваться командлетом Get-Help — это одна из самых важных команд для начинающих изучать PowerShell.
Если пользуетесь не только Windows, но и Linux, посмотрите статью про команды терминала Linux для начинающих. В ней рассказывается про работу с процессами и файлами, навигацию, каналы, xargs, awk и grep.
Перевод статьи «Windows PowerShell Scripting Tutorial for Beginners»
Как запустить PowerShell как оснастку в Ubuntu
PowerShell — это оболочка командной строки, разработанная специально для системных администраторов, чтобы упростить и автоматизировать управление сервером. Это очень мощный и эффективный инструмент, который экономит много времени за счет автоматизации широкого спектра локальных и удаленных задач управления. Microsoft запустила PowerShell Core как оснастку для пользователей Linux. Теперь вы можете попробовать PowerShell в Linux.
В этой статье мы увидим, как установить PowerShell в Ubuntu в качестве оснастки. Мы будем использовать Ubuntu 18.04 LTS для описания процедуры, упомянутой в этой статье.
Установка snapd в Ubuntu
Для запуска PowerShell в качестве оснастки в Ubuntu нам сначала потребуется установить Snap. Snap поставляется предварительно установленным в Ubuntu 18.04 LTS и 19.04 LTS. Однако, если вы используете более старую версию или случайно удалили ее из своей системы, вы можете установить ее с помощью терминала Ubuntu.
Чтобы включить snapd , выполните в терминале следующую команду:
$ sudo apt install snapd
Установка Powershell на Ubuntu
Затем для установки PowerShell с помощью оснастки выполните следующую команду в Терминале:
$ snap install powershell --classic
Введите пароль для текущей учетной записи пользователя, затем нажмите на Authenticate .
Установка займет не более минуты.
После установки PowerShell запустите его из Dash-меню Ubuntu. В качестве альтернативы просто введите pwsh в Терминале. Это вызовет командную строку PowerShell.
$ pwsh
Microsoft также выпустила предварительную версию бета-версии PowerShell. Он доступен в виде отдельной оснастки.
Чтобы установить предварительный просмотр PowerShell, введите в терминале следующую команду:
snap install powershell-preview –classic
Снова введите пароль для учетной записи пользователя, а затем нажмите Authenticate .
Чтобы запустить предварительный просмотр PowerShell, просто введите pwsh-preview в Terminal. Откроется командная строка предварительного просмотра PowerShell.
$ pwsh-preview
Чтобы просмотреть установленную версию PowerShell, выполните в терминале следующую команду:
$ PSVersionTable
Итак, это был краткий обзор о том, как запустить PowerShell как оснастку в Linux. Теперь вы можете использовать PowerShell точно так же, как в Windows.
комментариев Powershell — PowerShell — SS64.com
комментариев Powershell — PowerShell — SS64.com
В PowerShell однострочные комментарии начинаются с символа решетки, все справа от # будет проигнорировано.
# комментарий
В PowerShell 2.0 и выше могут использоваться многострочные блочные комментарии:
<# комментарий
contines
#>
Многострочные комментарии обычно используются для добавления описательной справки в начале сценария, но также работают для встраивания текста комментария в команду.
Справка на основе комментариев была также добавлена в PS 2.0, что позволяет добавлять некоторые стандартизированные теги к комментариям сценария, которые позволяют сценарию взаимодействовать с Get-Help.
См. Этот шаблонный скрипт или полный список ключевых слов в справке about_Comment_Based_Help.
Примеры
Copy-Item demo. msi C: \ install \ demo.msi # скопируйте установщик
<# Этот скрипт будет говорить с вами на французском языковая функция на основе: www.example.com/powershell.html Последнее обновление: 1666-09-02 #> Get-Content -Path <# файл конфигурации #> C: \ install \ app64.ini
Используя встроенные комментарии, вы можете задокументировать аргументы командлета:
PS C: \> Get-ChildItem <# перечислить элементы #> ` -Path $ env: windir <# системной папки Windows #> ` -Filter * .dll <# которые являются DLL #> ` -Recurse <# и поиск во всех подпапках #>
Справка на основе комментариев
К функциям и скриптам можно добавлять разделы справки на основе комментариев.Это делается с помощью специальных ключевых слов для комментариев справки, которые начинаются с точки. Ниже приведены их примеры. Вы можете добавить столько или меньше из них в свой сценарий, сколько необходимо, чтобы обеспечить соответствующий уровень подробной справки.
DemoParam1 Параметр DemoParam1 используется для определения значения blah, а также blah. .PARAMETER DemoParam2 Параметр DemoParam2 используется для определения значения blah, а также blah. .ПРИМЕР Пример ниже делает бла PS C: \> Пример .ПРИМЕР Другой пример .ЗАМЕТКИ Автор: Название Последнее редактирование: гггг-мм-дд Версия 1.0 - начальный выпуск blah Версия 1.1 - обновление для бла #>
Чтобы отобразить этот текст справки, используйте Get-Help
например
get-help ./script.ps1
get-help myfunction (это будет работать только после загрузки функции / получения точки)Где добавить справку на основе комментариев:
Справка на основе комментариев для сценария должна отображаться в начале сценария (ее также можно разместить в конце файла сценария, но только если сценарий не подписан.)
Справка на основе комментариев для функции может появляться в одном из трех мест:
- В начале тела функции.
- В конце тела функции.
- Перед ключевым словом Function. Между последней строкой справки по функциям и ключевым словом Function не может быть более одной пустой строки.
Большинство людей помещают все комментарии в начало скрипта / функции.
Справка по умолчанию
Если вы вызываете get-help для сценария, у которого нет справки на основе комментариев, но есть параметры, определенные с помощью оператора PARAM (), то get-help вернет эти сведения о параметрах.
Также можно получить немного более подробный набор текста справки по умолчанию, включив только <# .SYNOPSIS #> в верхней части скрипта.
Дополнительные сведения см. В справке about_Comment_Based_Help.
Копировать и вставить
Поскольку PowerShell поддерживает автозавершение табуляции, вам нужно быть осторожным при копировании и вставке символов пробела + TAB (особенно непосредственно перед разделителем комментария #). Эта строка:} <пробел> <вкладка> #
при копировании / вставке в командную строку PowerShell происходит следующее:PS C: \ batch> Демонстрация функции () {
>>}.\ aaardvaark.cmd # comment
>>
Термин ‘. \ Aaardvaark.cmd #’ не распознается как имя командлета, функции, файла сценария …Что происходит, так это то, что пробел расширяется, чтобы соответствовать первому файлу в текущем каталоге, в этом случае aaardvaark.cmd. Если бы последовательность была <пробел> <вкладка> <пробел>, а первым файлом был сценарий PowerShell или исполняемый файл, то он действительно был бы запущен.
Если пробел состоит только из символов
(или только из символов ), этого никогда не произойдет.
# Теперь стой там, где работаешь, теперь лицом к западу
Подумайте о месте, где вы живете. Интересно, почему вы этого не делали раньше # — REM ‘Stand’
Связанные командлеты PowerShell:
Escape-символы — двойные \\, чтобы избежать их
Авторские права © 1999-2021 SS64. com
Некоторые права защищены. Синтаксис
— как вы комментируете код в PowerShell?
Я немного опоздал на эту вечеринку, но кажется, что на самом деле никто не написал все варианты использования.Итак …
В настоящее время поддерживаются только версии PowerShell (, осень 2020 г. и более поздняя версия ):
- Windows PowerShell 5.1.x
- PowerShell 7.0.x.
Вы не хотите или не должны работать с разными версиями PowerShell.
Обе версии ( или любая другая версия, которую вы могли встретить с WPS 3.0-5.0, PS Core 6.x.x на некоторых устаревших станциях ) имеют одинаковые функции комментариев.
Однострочные комментарии
# Получить все процессы службы Windows <- однострочный комментарий, он начинается с '#'
Get-Process -Name * host *
Get-Process -Name * host * ## Вы можете поставить сколько угодно ###, это не имеет значения
Get-Process -Name * host * # | Stop-Service # Все от первого # до конца строки рассматривается как комментарий
Stop-Service -DisplayName Windows * Update # -WhatIf # Вы можете использовать его, чтобы закомментировать переключатели командлетов
Многострочные комментарии
<#
Все символы между '<#' и '#>'
рассматривается как комментарий. Типичный вариант использования - справка, см. Ниже.
# Вы также можете иметь однострочный комментарий внутри блока многострочного комментария.
# Или два ... :)
#>
<#
.СИНОПСИС
Краткое описание функции или скрипта.
Это ключевое слово можно использовать только один раз в каждой теме.
.ОПИСАНИЕ
Подробное описание функции или скрипта.
Это ключевое слово можно использовать только один раз в каждой теме.
.ЗАМЕТКИ
Некоторые дополнительные примечания. Это ключевое слово можно использовать только один раз в каждой теме.
Это ключевое слово можно использовать только один раз в каждой теме..ССЫЛКА НА САЙТ
Ссылка, используемая при использовании Get-Help с переключателем -OnLine.
Это ключевое слово можно использовать только один раз в каждой теме.
.ПРИМЕР
Пример 1
Вы можете использовать это ключевое слово сколько угодно.
.ПРИМЕР
Пример 2
Вы можете использовать это ключевое слово сколько угодно.
#>
Вложенные многострочные комментарии
<#
Нет, это запрещено в PowerShell.
<# Это нарушит ваш первый многострочный блок комментария ... #>
... и это вызовет синтаксическую ошибку.#>
В коде вложены многострочные комментарии
<#
Открытие / закрытие многострочного комментария
также можно использовать для комментирования вложенного кода
или как объяснение многосвязных операций ..
#>
Get-Service | <# Шаг объяснения #>
Where-Object {$ _. Status -eq [ServiceProcess.ServiceControllerStatus] :: Stopped} |
<# Format-Table -Property DisplayName, Status -AutoSize | #>
Out-File -FilePath Services.txt -Encoding Unicode
Сценарий крайнего случая
# Какой-нибудь хорошо написанный скрипт
выход
Писать что-то после выхода можно, но не рекомендуется.Это не комментарий.
Эти слова сбивают с толку PSScriptAnalyzer, особенно в Visual Studio Code.
Вы можете активно прервать сеанс в VS Code.
макросов - PowerShell - автоматизация заголовка комментария
Если вы хотите узнать параметры определенной функции, вы можете сделать что-то вроде этого:
# определить функцию
function Add-Extension {
param ([строка] $ Имя, [строка] $ Расширение)
}
# получить информацию о команде для определенной функции
$ cmdInfo = Get-Command Добавить-расширение
# компилировать метаданные команды из информации о команде
$ cmdMetadata = [System. Management.Automation.CommandMetadata] :: new ($ cmdInfo)
Теперь вы можете получить доступ к метаданным отдельных параметров через $ cmdMetadata.Parameters
и сгенерировать содержимое справки на основе комментариев:
foreach ($ param в $ cmdMetadata.Parameters.GetEnumerator ()) {
".PARAMETER {0}" -f $ param.Key
"[Вставить описание параметра для {0}]" -f $ param.Key
""
}
Есть одна вещь, которая может вас заинтересовать в том, что метаданные параметра не будут содержать - выражение значения по умолчанию - для этого вам нужно вместо этого проанализировать необработанный исходный код:
# разобрать файл скрипта, содержащий функцию
$ scriptPath = Resolve-Path.\ scriptWithFunctionDefinition.ps1
$ AST = [System.Management.Automation.Language.Parser] :: ParseFile ($ scriptPath, [ref] $ null, [ref] $ null)
# обнаруживаем все определения функций на корневом уровне
$ functionDefs = $ AST. FindAll ({$ args [0] -is [System.Management.Automation.Language.FunctionDefinitionAst]}, $ false)
Метод Parser.ParseFile ()
вернет абстрактное синтаксическое дерево - или сокращенно AST - элементы, которые мы можем проверить.
Метод FindAll ()
будет обходить AST и выводить любое поддерево, удовлетворяющее условию - в данном случае мы ищем любой [FunctionDefinitionAst]
, который, как следует из названия, описывает определение функции.
Теперь мы можем перебирать параметры, как раньше:
foreach ($ functionDefinition в $ functionDefs) {
# Поскольку мы по-прежнему эффективно работаем с кодом,
# нам нужно обрабатывать синтаксисы `function f () {}` и `function f {param ()}`
$ parameters = $ functionDefinition.Parameters
if ($ functionDefinition.Body.ParamBlock) {
$ parameters = $ functionDefinition.Body.ParamBlock
}
# Теперь мы можем просмотреть фактические параметры
foreach (параметр $ в параметрах $) {
". ПАРАМЕТР {0} "-f $ параметр.Name.VariablePath
# ... и извлеките выражение значения по умолчанию
if ($ parameter.DefaultValue) {
"Значение по умолчанию: {0}" -f $ parameter.DefaultValue
}
}
}
Регулярное выражение
- PowerShell удаляет все комментарии из скрипта
Я ищу способ удалить все комментарии из файла. Есть разные способы делать комментарии, но меня интересуют только простые комментарии формы #
. Причина в том, что я использую только <# #>
для действующего .\ s * #
вроде работает.
b) с некоторым кодом в начале строки, а затем командой в конце строки.
Я хочу избежать зачистки линий, например, Write-Host "#####"
, но я думаю, что это описано в коде, который у меня есть.
Мне удалось удалить комментарии в конце строки с помощью разделения, так как я не мог понять, как это сделать с помощью регулярного выражения, знает ли кто-нибудь способ добиться этого с помощью регулярного выражения?
Разделение не было идеальным, поскольку <#
в строке будет удалено -split
, но я исправил это, разделив на "#"
. Это не идеально, но может быть достаточно хорошим - может быть, может существовать более надежный способ с регулярным выражением?
Когда я делаю следующее для моего скрипта длиной 7000 строк, он работает (!) И удаляет огромное количество комментариев, НО размер выходного файла почти удваивается (!?) с 400 КБ до примерно 700 КБ. Кто-нибудь понимает, почему это происходит и как этого избежать (это как-то связано с спецификацией, Unicode или чем-то в этом роде? Out-File, кажется, действительно увеличивает размер файла!)
$ x = Get-Content ".\ s * # "} # Удалить все строки, начинающиеся с; включая пробелы перед
$ x = $ x | % {($ _ -split "#") [0]} # Удалить комментарии в конце строки
$ x = ($ x -replace $ regex) .Trim () # Удалять пробелы только в начале и в конце строки
$ x | Out-File $ out
# $ x | более
Синтаксис справки на основе комментариев - PowerShell
- 2 минуты на чтение
В этой статье
В этом разделе описывается синтаксис справки на основе комментариев.
Синтаксическая диаграмма
Синтаксис справки на основе комментариев следующий:
#. <Ключевое слово справки>
# <содержание справки>
-или же -
<#
. <ключевое слово помощи>
<содержание справки>
#>
Описание синтаксиса
Справка на основе комментариев представляет собой серию комментариев. Вы можете ввести символ комментария ( #
) перед
каждую строку комментариев, или вы можете использовать символы <#
и #>
для создания блока комментариев.Все
строки в блоке комментариев интерпретируются как комментарии.
Каждый раздел справки на основе комментариев определяется ключевым словом, и каждому ключевому слову предшествует точка.
(,
). Ключевые слова могут появляться в любом порядке. Имена ключевых слов не чувствительны к регистру.
Блок комментариев должен содержать по крайней мере одно ключевое слово справки. Некоторые ключевые слова, такие как ПРИМЕР ,
может появляться много раз в одном и том же блоке комментариев. Содержание справки для каждого ключевого слова начинается с
строка после ключевого слова и может охватывать несколько строк.
Все строки в разделе справки, основанном на комментариях, должны быть смежными. Если раздел справки на основе комментариев
следует за комментарием, который не является частью раздела справки, между
последняя строка комментария, не относящаяся к справке, и начало справки на основе комментариев.
Например, следующий раздел справки на основе комментариев содержит ключевое слово .Description и его
значение, которое является описанием функции или сценария.
<#
.Описание
Функция Get-Function отображает имя и синтаксис всех функций в сеансе.#>
комментариев и многое другое в PowerShell
Как и любой другой язык программирования, PowerShell поддерживает комментарии. Фактически, он будет поддерживать два стиля комментариев. Однако, как вы увидите позже в этой статье, PowerShell может использовать комментарии несколькими интересными и неожиданными способами, которые могут оказаться весьма эффективными.
Использование комментариев
Самый распространенный стиль комментария, который вы увидите, - это строка, перед которой стоит символ #. (Я предоставляю вам решать, хотите ли вы называть это хэштегом, символом фунта или даже старым добрым октоторпом!)
В качестве примера у вас может быть блок комментария в начале вашей программы с подробной информацией о нем:
# Это пример однострочного комментария # # Автор: Greg D.Мур [email protected] # Дата: 2019-11-12 # Версия: 1.0 # |
Подобные комментарии могут размещаться в любом месте вашего кода. Однако альтернативный способ сделать это - это то, что я бы назвал стилем языка C или иногда называемым блочным комментарием:
<# Это пример комментария блока Автор: Greg D.Мур [email protected] Дата: 2019-11-12 Версия: 1.0 #> |
Этот стиль позволяет вам легко добавлять строки комментариев, не ставя перед каждым символом #. Вы можете использовать любой стиль или даже оба. Однако просто помните о полезности таких блоков комментариев, когда вы вернетесь для отладки собственного кода через год. Однако комментарии не обязательно должны быть в начале строки. Фактически, лично я использую только блоки комментариев, подобные приведенным выше, в начале скрипта или прямо перед особенно сложным блоком кода.Я с гораздо большей вероятностью буду комментировать в конце строки, например:
$ Callback_Test_Form.Show () | Out-Null #absorbs сообщение об отмене в конце. Это происходит по причинам, выходящим за рамки данной статьи |
Я включил этот комментарий в недавний сценарий, потому что | Out-Null
не был чем-то, что я ожидал, что он понадобится, и я знаю, что через год, если бы у меня не было комментария там, я бы удивился, почему он у меня там был.Или, что еще хуже, я бы удалил его и потом удивился, почему я получаю сообщение об отмене, которое все время появляется.
Обратите внимание, что когда вы начинаете комментарий с символа #, все до конца строки рассматривается как комментарий. Это может быть полезно, например, когда вы тестируете и можете закомментировать конец команды.
get-help write-host # Ой, я не хочу идти - онлайн |
Это позволит вам позже удалить комментарий и получить – онлайн-версию справки
, но что, если вы хотите, чтобы комментарий был посередине? Опять же, PowerShell дает вам такую возможность.
get-help write-host <# Мне нужна самая последняя версия, поэтому я пойду #> -online |
Обратите внимание, что, используя комментарий блочного стиля, вы получаете возможность иметь комментарий в середине вашей команды и при этом выполнять или интерпретировать элементы справа от него. Наконец, вы можете спросить: «А что, если я захочу распечатать # или сделать что-то подобное?» Если вы попробуете
хост записи Нажмите # на телефоне |
Вы обнаружите, что он не записывает то, что вы хотите.Вы просто получаете:
Вот здесь и пригодится могильный акцент `.
хост записи Нажмите `# на телефоне |
Будет напечатано желаемое сообщение.
Вы также можете заключить эту строку в кавычки:
write-host 'Нажмите # на телефоне' |
Это сработает, но я хотел бы привести пример того, как избежать квалификатора #.
Если вы, как и я, часто используете PowerShell ISE для написания сценариев, есть еще один полезный трюк, которым я хочу поделиться, но я могу только описать и дать несколько снимков экрана, а не предоставить сценарий для него. Это сочетание клавиш, не предназначенное для комментариев, но полезно, если у вас есть фрагмент кода, который вы хотите закомментировать, например, для тестирования. Поместите курсор в начало строки и, удерживая Shift-Alt , используйте клавиши со стрелками, чтобы переместить его вверх или вниз. Вы заметите, что появляется тонкая линия (синяя на моем экране).После того, как вы отметите строки, которые хотите прокомментировать, просто введите #, и он появится в начале каждой строки.
Это пример кода для комментария:
Если щелкнуть справа от текста в строке 40 и несколько раз нажать Shift-Alt и стрелку вверх, вы увидите синюю строку:
После нажатия # <пробел> вы увидите символы, добавленные к коду:
В качестве примечания, вы можете использовать этот трюк в любом месте строки (так что, если вы хотите поместить кучу комментариев в конце ряда строк, вы можете использовать этот трюк, чтобы легко вставить # для вас) и, очевидно, не относится к комментированию, но это одно из наиболее очевидных применений.используется для привязки начала строки и, конечно, # (там есть пробел) в основном вставляет # и пробел в конце выделенных строк. Обратите внимание: если вы не выделите блок кода, это будет действовать для всего вашего скрипта.
и более
Однако, если бы это было все, что могли делать комментарии в PowerShell, это была бы очень короткая и скучная статья (и мой редактор качала бы головой, говоря: «Грег, мне нужно более 850 слов!»). Как и многие вещи в PowerShell. , создатели добавили функции, которые делают его более мощным, чем вы могли ожидать.
Недавно я готовился к презентации, которую проводил в группе пользователей SQL Server в Hampton Roads. Во время этой презентации я запускаю сценарий в PowerShell, который запускает и останавливает SQL Server. Для этого мне нужно запустить его от имени администратора. Конечно, я совершенно забыл об этом во время тренировки, и когда я запустил его от своего имени, в итоге было выдано несколько уродливых ошибок. Это не было шоу-стопером, но не тем, что вы хотели во время демонстрации. Это заставило меня задуматься о том, как сделать так, чтобы этого не произошло во время разговора.
Первой моей мыслью было найти какой-нибудь командлет, который бы проверял, под каким именем я вошел в систему, а затем отменял бы работу, если я был неправильным пользователем. Частично проблема с этим подходом, конечно же, заключается в том, что когда вы запускаете программу (например, PowerShell ISE) от имени администратора, вы показываете себя как зарегистрированный пользователь. Это будет сложнее, чем я думал.
И снова PowerShell меня удивил. Решение этой проблемы тривиально. Чтобы увидеть, как решить проблему, откройте PowerShell ISE от имени себя (т.е. НЕ выбирайте Запуск от имени администратора и убедитесь, что у вашего пользователя нет прав локального администратора) и введите следующий код:
стоп-служба «время окна» запуск службы «время окна» |
Сохраните это в файл с именем перезапуск службы таймера example.ps1 , а затем попробуйте запустить его. Если вы не являетесь локальным администратором на своем компьютере, вы должны получить экран с ошибкой, подобный приведенному ниже.
Если вы запустите это с помощью параметра «Запуск от имени администратора», он должен работать без ошибок. В этом примере сбой довольно мягкий, но, возможно, вы пишете сценарий, и сбой не был бы таким безобидным. Чтобы решить эту проблему, просто поместите следующий комментарий вверху скрипта выше и сохраните его повторно.
#Requires -RunAsAdministrator |
Теперь вы получите другую ошибку:
Это все еще немного некрасиво, но намного лучше, чем запускать сценарий и, возможно, что-то сломать.Обратите внимание, если вы просто скопируете и вставите сценарий в новое окно, но не сохраните его, PowerShell попытается запустить все это целиком. Обычно #requires игнорируется, если это не фактический сохраненный файл. Это решило мою первоначальную проблему, но заставило меня изучить другие функции, о которых я не знал. Для #requires приведен полный список:
.
#Requires -Version N [.n] #Requires -PSEdition [Core | Рабочий стол] #Requires –PSSnapin PSSnapin-Name [-Version N [.n]] #Requires -Modules {Module-Name | Hashtable} #Requires –ShellId ShellId #Requires –RunAsAdministrator |
Как видите, они дают вам много возможностей контролировать, как и когда запускается ваш скрипт. #Requires –Version
полезен, если вашему сценарию требуются функции, которые доступны только в более поздней версии PowerShell. Обратите внимание, что это минимальное количество. Версия PowerShell, которую вы используете, должна соответствовать этой или быть выше.Вы не можете использовать это, чтобы требовать предыдущую версию PowerShell. Например, полезный командлет, который я использовал в недавнем скрипте, - это compress-archive
. К счастью, этот сценарий был специфичен для проблемы, которую я пытался решить, но если бы я пытался написать более общий сценарий, я мог бы поставить #requires –Version 5.0
в конце моего сценария. Для демонстрации сохранения следующего сценария как требуется версия example.ps1.
#requires - Версия 5.0 Get-Process | Исходящий файл -FilePath. \ Process.txt Сжать-архив -Path. \ Process.txt -DestinationPath. \ Process.zip -Force |
Если вы запустите это в существующем экземпляре PowerShell ISE, он должен работать без проблем, но если вы попытаетесь запустить более старую версию, такую как PowerShell 2.0, сценарий выдаст ошибку в строке #requires
и никогда не выполнит остальная часть сценария. Это желаемый результат.
Для тестирования вы также можете ввести что-то вроде –Version 99.99
, и вы увидите сообщения об ошибках, аналогичные приведенным ниже примерам, но я хотел показать, как это будет работать в реальном мире в существующих системах, а также продемонстрировать возможность командной строки вернуться к предыдущей версии PowerShell.
Чтобы проверить это, вам нужно будет использовать версию PowerShell для командной строки и запустить ее следующим образом:
C: \> Powershell - версия 2.0 |
Затем запустите файл, который вы сохранили выше, требует версии example.ps1.
Вы должны увидеть ошибку, например:
Хотя я бы рекомендовал поместить комментарий #Requires в самое начало файла, по правде говоря, вы можете поместить его где угодно, и он будет действовать таким же образом. Если вы воссоздаете вышеуказанный файл, но переместите комментарий вниз после Get-Process и сохраните как , потребуется пример версии Версия 2.ps1 .
Get-Process | Исходный файл -FilePath.\ Process.txt #requires -Version 5.0 Compress-Archive -Path. \ Process.txt -DestinationPath. \ Process.zip -Force |
Попробуйте запустить его в версии 2.0, как указано выше, и вы получите аналогичную ошибку, и весь скрипт не запустится.
Это означает, что у вас не может быть части сценария, которая может запускаться под более старой версией (или запускаться от имени администратора), а затем части, которая требует определенной версии или запускаться от имени администратора.Если вы хотите сделать что-то подобное в коде, вам нужно стать умнее. Сохраните следующий сценарий как Требуется версия example Версия 3.ps1.
Get-Process | Out-File -FilePath. \ Process.txt if ($ PSVersionTable.PSVersion. Major -ge 5) { Compress-Archive -Path. \ Process.txt -DestinationPath. \ Process.zip -Force } else { Write-Host "Мне очень жаль, Дэйв, я не могу этого сделать." } |
Если вы запустите его в версии 5 или выше, он создаст файл Process.txt и заархивирует его. Если вы запустите его в более ранней версии, такой как –Version 2.0
выше, сценарий все равно сможет создать файл Process.txt , поскольку Get-Process
- это командлет, доступный в версии 2.0. Поскольку Compress-Archive не работает, сценарий пропустит этот шаг и выдаст сообщение об ошибке. Вам решать, хотите ли вы писать сценарии, которые могут определять версию PowerShell и вести себя по-разному в зависимости от версии, но во многих случаях, если вы просто хотите прервать выполнение сценария, комментарий #Requires
- безусловно, самый простой способ. обращения с вещами.
Два последних предупреждения об использовании комментария #Requires
. Он должен начинаться в начале строки; перед ним не должно быть пробелов или табуляции. Кроме того, вы не можете попытаться перехитрить его и поместить в блок try / catch, чтобы более изящно с ним справиться. Сохраните следующий сценарий, чтобы проиллюстрировать оба предостережения: Требуется пример версии Версия 4.ps1.
#requires - Версия 5.0 try { write-host "Мы на версии 5.0!" #requires -Version 5.0 } catch { write-host "Эй, у нас не версия 5!" } |
Обратите внимание, что сценарий #requires
в строке 6 был прерван, а не сценарий в строке 1, и команда try / catch не дала результата. #Requires
являются глобальными и влияют на весь сценарий, независимо от того, где они находятся, при условии, что они начинаются в строке.И да, в скрипте может быть более одного #Requires
. Вам может потребоваться определенная версия PowerShell, наличие определенных модулей и RunAsAdministrator
.
Два последних замечания по комментарию #Requires - RunAsAdministrator
. Он был представлен в PowerShell версии 4.0 и не работает в системах, отличных от Windows (да, помните, PowerShell теперь кроссплатформенный!). Сохраните следующий сценарий как Requires Administrator.ps1 . Для проверки вам потребуется экземпляр Linux, но если вы это сделаете, PowerShell можно установить в Linux с помощью описанных здесь методов.После установки скопируйте или сохраните приведенный выше сценарий в свой экземпляр Linux. Для запуска скрипта введите:
Pwsh "./ Требуется Administrator.ps1" |
Вы должны увидеть
Наконец, вам может быть интересно, можно ли использовать комментарии блочного стиля с #Requires. Судя по моему ограниченному тестированию, это не работает. Вам нужно поместить каждый Requires в отдельную строку с предшествующим #.Этот скрипт работает:
#Requires -RunAsAdministrator #Requires -Version 5.0 |
Этот скрипт не работает:
<#Requires -RunAsAdministrator Требуется -Version 5.0 #> |
Заключение
Как видите, комментарии PowerShell полезны не только из-за своей очевидной роли, позволяющей вам комментировать код, но также полезны для управления выполнением вашего кода.Вы можете выбирать между однострочными комментариями или блочными комментариями, и вы можете помещать их перед блоками кода или встроенными в код. Обратите внимание, что все эти скрипты доступны на Github.
Документация и комментарии
- Практика и стиль PowerShell
Комментарии, противоречащие коду, хуже, чем отсутствие комментариев. Всегда уделяйте первоочередное внимание обновлению комментариев при изменении кода!
Комментарии должны быть на английском языке и должны быть полными предложениями.Если комментарий короткий, точку в конце можно не ставить.
Помните, что комментарии должны служить для ваших рассуждений и принятия решений, а не пытаться объяснить, что делает команда. За исключением регулярных выражений, хорошо написанный PowerShell может быть довольно понятным.
# Не писать:
# Увеличить маржу на 2
$ Margin = $ Margin + 2
# Возможно написать:
# Поле рендеринга закрывает пару пикселей.
$ Маржа = $ Маржа + 2
Не переусердствуйте с комментариями. Если ваш код не является особенно непонятным, не ставьте перед каждой строкой комментарий - это разбивает код и затрудняет чтение. Вместо этого напишите комментарий из одного блока.
Комментарии блока обычно применяются к некоторому или всему коду, который следует за ними, и имеют отступ на том же уровне, что и этот код. Каждая строка должна начинаться с символа # и одного пробела.
Если блок очень длинный (как в случае с текстом документации), рекомендуется использовать <#... #>
синтаксис блочного комментария, но вы должны поместить символы комментария в их собственные строки и сделать отступ для комментария:
# Требование пробела делает вещи удобочитаемыми и предотвращает путаницу.
# Написание комментариев по одному в строке делает их более заметными в консоли.
<#
.SYNOPSIS
Действительно длинные блоки комментариев утомительно оставлять комментарии в однострочном режиме.
.DESCRIPTION
В частности, когда комментарий необходимо часто редактировать,
как с помощью и документацией для функции или сценария.
#>
Комментарии к той же строке, что и утверждение, могут отвлекать, но когда в них не говорится об очевидном, и особенно когда у вас есть несколько коротких строк кода, требующих пояснения, они могут быть полезны.
Они должны быть отделены от оператора кода как минимум двумя пробелами, и в идеале они должны совпадать с любыми другими встроенными комментариями в том же блоке кода.
$ Options = @ {
Margin = 2 # Поле рендеринга закрывает пару пикселей.
Padding = 2 # Нам нужен пробел между рамкой и текстом.
FontSize = 24 # Оставьте больше 16, чтобы его можно было читать в презентациях.
}
Справка на основе комментариев должна быть написана простым языком.
Вы не пишете диссертацию на курс технического письма в колледже - вы пишете что-то, в котором описывается, как работает функция. Избегайте излишне громоздких слов и делайте объяснения краткими. Вы не пытаетесь никого впечатлить, и единственные люди, которые когда-либо это прочтут, просто пытаются понять, как использовать эту функцию.
Если вы пишете на том, что для вас является иностранным языком, более простые слова и более простые структуры предложений будут лучше и с большей вероятностью будут иметь смысл для носителя языка.
Будьте полными, но краткими.
Чтобы гарантировать, что документация соответствует функции, комментарии документации должны быть помещены ВНУТРИ функции, а не выше. Чтобы было сложнее забыть обновить их при изменении функции, вы должны держать их вверху функции, а не внизу.
Конечно, это не значит, что размещать их в другом месте неправильно - но это легче сделать и сложнее забыть обновить.
Если вы хотите предоставить подробные объяснения того, как работает ваш инструмент, используйте для этого раздел Notes
.
Каждая команда функции сценария должна иметь хотя бы краткое описание ее функции. Это Synopsis
.
Каждый параметр должен быть задокументирован. Чтобы упростить синхронизацию комментариев с изменениями параметров, предпочтительным местом для комментариев документации по параметрам является внутри блока param
, непосредственно над каждым параметром.Примеры можно найти в фрагментах ISE:
param (
# Param1 help description
[Parameter (Mandatory = $ true,
ValueFromPipelineByPropertyName = $ true,
Position = 0)]
$ Param1
# Описание справки Param2
[int]
$ Param2
)
Также можно записать операторы .PARAMETER
с остальными комментариями документации, но опыт показывает, что они с большей вероятностью быть в актуальном состоянии, если вы поместите их ближе к документированному коду.
В вашей справке всегда должен быть пример для каждого основного варианта использования. «Пример использования» - это просто пример того, что вы вводите в Powershell для запуска скрипта - вы даже можете вырезать и вставить его из командной строки, пока тестируете свою функцию.
функция Test-Help {
<#
.SYNOPSIS
Пример функции для отображения того, как должна быть написана справка.
.EXAMPLE
Get-Help -Name Test-Help
Здесь отображается справка для функции примера.
#>
[CmdletBinding ()]
param (
# Этот параметр ничего не делает.
# Псевдонимы: MP
[Параметр (Обязательный = $ true)]
[Псевдоним ("MP ")]
[String] $ MandatoryParameter
)
<# здесь код ... #>
}
Вы всегда должны писать справку на основе комментариев в своих скриптах и функциях.
Справка на основе комментариев имеет следующий формат:
function Get-Example {
<#
.ОБЗОР
Краткое описание функции или сценария.
. ОПИСАНИЕ
Более подробное описание.
.PARAMETER FirstParameter
Описание каждого из параметров.
Примечание:
Чтобы упростить синхронизацию комментариев с изменениями параметров,
предпочтительное место для комментариев документации по параметрам находится не здесь,
, а в блоке параметров, непосредственно над каждым параметром.
.PARAMETER SecondParameter
Описание каждого из параметров.
.INPUTS
Описание объектов, которые могут быть переданы скрипту по конвейеру.
.OUTPUTS
Описание объектов, которые выводит скрипт.
.EXAMPLE
Пример запуска сценария.
.LINK
Ссылки на дополнительную документацию.
.NOTES
Подробная информация о том, что делает сценарий, если это необходимо.
#>
Справка на основе комментариев отображается, когда пользователь вводит help Get-Example
или Get-Example -?
и т. Д.
Ваша помощь должна быть полезной. То есть, если вы написали инструмент под названием Get-LOBAppUser
, не пишите справку, которая просто говорит: «Получает пользователей LOB-приложений».