فرض کنید میخواهیم کامند git log را به همراه تعدادی از دستورات آن به یک PowerShell cmdlet تبدیل کنیم؛ برای اینکار ابتدا نیاز است ماژول عنوان شده را نصب کنیم:
$Configuration = @{
'$schema' = "https://aka.ms/PowerShell/Crescendo/Schemas/2021-11"
Commands = @()
}
$parameters = @{
Verb = "Get"
Noun = "GitLog"
OriginalName = "git"
}
$Configuration.Commands += New-CrescendoCommand @parameters
$Configuration | ConvertTo-Json -Depth 3 | Out-File ./git-ps.json
در اینجا تعیین کردهایم که کامندی که میخواهیم برایمان تولید شود، چه ویژگیهایی باید داشته باشد. به عنوان مثال Verb آن Get و Noun آن باید GitLog باشد (
براساس استانداری که مایکروسافت برای نامگذاری cmdletها پیشنهاد میدهد). در نهایت میتوانیم به صورت Get-GitLog از آن استفاده کنیم. همچنین legacy command اصلی که میخواهیم برای آن cmdlet ایجاد کنیم نیز توسط OriginalName تعیین شدهاست. لازم به ذکر است که در ویندوز باید مسیر کامل آن را وارد کنید. سپس با اجرای دستورات فوق، خروجی زیر برایمان تولید خواهد شد:
{
"Commands": [
{
"Verb": "Get",
"Noun": "GitLog",
"OriginalName": "git",
"OriginalCommandElements": null,
"Platform": [
"Windows",
"Linux",
"MacOS"
],
"Elevation": null,
"Aliases": null,
"DefaultParameterSetName": null,
"SupportsShouldProcess": false,
"ConfirmImpact": null,
"SupportsTransactions": false,
"NoInvocation": false,
"Description": null,
"Usage": null,
"Parameters": [],
"Examples": [],
"OriginalText": null,
"HelpLinks": null,
"OutputHandlers": null
}
],
"$schema": "https://aka.ms/PowerShell/Crescendo/Schemas/2021-11"
}
نکته: دقت داشته باشید که schema$ باید درون single quote نوشته شود؛ چون در غیراینصورت، key آن درون فایل تولید شده، خالی خواهد بود:
اکنون باید این فایل Configuration را به Crescendo معرفی کنیم تا cmdlet را برایمان تولید کند. اینکار را توسط Export-CrescendoModule انجام خواهیم داد:
Export-CrescendoModule -Configuration ./git-ps.json -ModuleName ./git-ps.psm1
با اجرای دستور فوق، فایلهای git.psm1 و همچنین git.psd1 تولید خواهند شد. نیاز به بررسی فایلهای جنریت شده نیست؛ چون تنها جایی که با آن باید در ارتباط باشیم، همان فایل JSON ابتدای بحث است که در ادامه آن را بررسی خواهیم کرد. اما قبل از آن اجازه دهید ماژول تولید شده را Import کنیم و دستور Get-GitLog را وارد کنیم:
PP /> Import-Module ./git-ps.psd1
PS /> Get-GitLog
usage: git [-v | --version] [-h | --help] [-C <path>] [-c <name>=<value>]
[--exec-path[=<path>]] [--html-path] [--man-path] [--info-path]
[-p | --paginate | -P | --no-pager] [--no-replace-objects] [--bare]
[--git-dir=<path>] [--work-tree=<path>] [--namespace=<name>]
[--super-prefix=<path>] [--config-env=<name>=<envvar>]
<command> [<args>]
These are common Git commands used in various situations:
start a working area (see also: git help tutorial)
clone Clone a repository into a new directory
init Create an empty Git repository or reinitialize an existing one
work on the current change (see also: git help everyday)
add Add file contents to the index
mv Move or rename a file, a directory, or a symlink
restore Restore working tree files
rm Remove files from the working tree and from the index
examine the history and state (see also: git help revisions)
bisect Use binary search to find the commit that introduced a bug
diff Show changes between commits, commit and working tree, etc
grep Print lines matching a pattern
log Show commit logs
show Show various types of objects
status Show the working tree status
grow, mark and tweak your common history
branch List, create, or delete branches
commit Record changes to the repository
merge Join two or more development histories together
rebase Reapply commits on top of another base tip
reset Reset current HEAD to the specified state
switch Switch branches
tag Create, list, delete or verify a tag object signed with GPG
collaborate (see also: git help workflows)
fetch Download objects and refs from another repository
pull Fetch from and integrate with another repository or a local branch
push Update remote refs along with associated objects
'git help -a' and 'git help -g' list available subcommands and some
concept guides. See 'git help <command>' or 'git help <concept>'
to read about a specific subcommand or concept.
See 'git help git' for an overview of the system.
همانطور که مشاهده میکنید، خروجی دستور git، نمایش داده شدهاست. دلیل آن نیز این است که در فایل configuration، هیچ آرگومانی را به عنوان ورودی آن تعیین نکردهایم. برای اضافه کردن آرگومانهای موردنظر باید پراپرتی OrginalCommandElements را مقدار دهی کنیم:
"OriginalCommandElements": ["log", "--oneline"],
بنابراین با فراخوانی دستور Get-GitLog، در اصل دستور git log —oneline فراخوانی خواهد شد:
PS /> Get-GitLog
e9590e8 init
اما تا اینجا نیز خروجی به صورت رشتهایی است. برای داشتن یک خروجی Object، باید پراپرتی OutputHandlers را از Configuration، تغییر دهیم:
"OutputHandlers": [
{
"ParameterSetName": "Default",
"Handler": "$args[0] | ForEach-Object { $hash, $message = $_.Split(' ', 2) ; [PSCustomObject]@{ Hash = $hash; Message = $message } }"
}
]
در اینجا توسط args$ به خروجی کامند اصلی دسترسی خواهیم داشت. این خروجی را سپس با کمک ForEach-Object، به یک شیء با پراپرتیهای Hash و Message تبدیل کردهایم. در اینجا فقط میخواستم روال تهیه یک آبجکت را از کامندهایی که خروجی JSON ندارند، نشان دهم؛ اما خوشبختانه توسط پرچم pretty در git log، امکان تهیهی خروجی JSON را نیز داریم:
git log --pretty=format:'{"commit": "%h", "author": "%an", "date": "%ad", "message": "%s"}'
در نتیجه عملاً نیازی به split کردن نیست و بجای آن میتوانیم به صورت مستقیم، خروجی را توسط ConvertFrom-Json پارز کنیم:
"OutputHandlers": [
{
"ParameterSetName": "Default",
"Handler": "$args[0] | ConvertFrom-Json"
}
]
همچنین درون فایل schema با کمک پراپرتی Parameters، امکان تعریف پارامتر را نیز برای کامند Get-GitLog خواهیم داشت. به عنوان مثال میتوانیم فلگ reverse را نیز به کامند اصلی از طریق PowerShell ارسال کنیم:
"Parameters": [
{
"Name": "reverse",
"OriginalName": "--reverse",
"ParameterType": "switch",
"Description": "Reverse the order of the commits in the output."
}
],
دقت داشته باشیم که با هربار تغییر فایل schema باید توسط دستور Export-CrescendoModule ماژول موردنظر را تولید کنید:
Export-CrescendoModule -Configuration ./git-ps.json -ModuleName ./git-ps.psm1
Import-Module ./git-ps.psd1
در نهایت cmdletمان به این صورت قابل استفاده خواهد بود: