이 문서에서는 PowerShell-Docs 콘텐츠와 관련된 스타일 지침을 제공합니다. 개요에 설명된 정보를 기반으로 합니다.
명령 구문 요소 서식 지정
다음 규칙을 사용하여 문장에서 요소를 사용할 때 PowerShell 언어의 요소에 서식을 지정합니다.
적절한 Pascal 케이스에서 항상 cmdlet 및 매개 변수의 전체 이름을 사용합니다.
별칭을 구체적으로 보여 주는 경우에만 별칭을 사용합니다.
PowerShell 키워드 및 연산자는 모두 소문자여야 합니다.
다음 항목은 굵은 텍스트를 사용하여 서식을 지정해야 합니다.
타입 이름
클래스 이름
속성 이름
매개 변수 이름
- 기본적으로 하이픈 접두사 없이 매개 변수를 사용합니다.
- 구문을 설명하는 경우 하이픈과 함께 매개 변수 이름을 사용합니다. 매개 변수를 백틱으로 래핑합니다.
다음은 그 예입니다.
The parameter's name is **Name**, but it's typed as `-Name` when used on the command line as a parameter.
다음 항목은 백틱
`을 사용하여 형식을 지정해야 합니다.속성 및 매개 변수 값
대괄호로 묶인 스타일을 사용하는 이름을 입력합니다. 예를 들면 다음과 같습니다.
[System.Io.FileInfo]이름으로 캐릭터를 부릅니다. 예: 별표 문자(
*)를 와일드카드로 사용합니다.언어 키워드 및 연산자
Cmdlet, 함수 및 스크립트 이름
명령 및 매개 변수 별칭
메서드 이름 - 예를 들어 메서드는
ToString()개체의 문자열 표현을 반환합니다.변수
고유 명령
파일 및 디렉터리 경로
인라인 명령 구문 예제 - 코드 샘플은 Markdown을 참조하세요.
이 예제에서는 몇 가지 백틱 예제를 보여 줍니다.
The following code uses `Get-ChildItem` to list the contents of `C:\Windows` and assigns the output to the `$files` variable. ```powershell $files = Get-ChildItem C:\Windows ```이 예제에서는 명령 구문 인라인을 보여줍니다.
To start the spooler service on a remote computer named DC01, you type: `sc.exe \\DC01 start spooler`.파일 확장명을 포함하면 PowerShell의 명령 우선 순위에 따라 올바른 명령이 실행됩니다.
코드 샘플을 위한 Markdown
Markdown은 두 가지 코드 스타일을 지원합니다.
-
코드 범위(인라인) - 단일 백틱(
`) 문자로 표시됩니다. 독립 실행형 블록이 아닌 단락 내에서 사용됩니다. -
코드 블록 - 삼중 백틱(
```) 문자열로 둘러싸인 여러 줄 블록입니다. 코드 블록에는 백틱 다음에 언어 레이블이 있을 수도 있습니다. 언어 레이블을 사용하면 코드 블록의 내용을 강조 표시하는 구문을 사용할 수 있습니다.
모든 코드 블록은 코드 펜스에 포함되어야 합니다. 코드 블록에 들여쓰기를 사용하지 마세요. Markdown은 이 패턴을 허용하지만 문제가 될 수 있으며 피해야 합니다.
코드 블록은 삼중 백틱(```) 코드 펜스로 둘러싸인 하나 이상의 코드 줄입니다.
코드 펜스 표식은 코드 샘플 전후에 각각의 줄에 있어야 합니다. 여는 표식에는 선택적 언어 레이블이 있을 수 있습니다. 언어 레이블을 사용하면 렌더링된 웹 페이지에서 구문을 강조 표시할 수 있습니다.
지원되는 언어 태그의 전체 목록은 중앙 집중식 기여자 가이드의 Fenced 코드 블록을 참조하세요.
또한 게시는 코드 블록의 내용을 클립보드에 복사할 수 있는 복사 단추를 추가합니다. 이렇게 하면 코드를 스크립트에 붙여넣어 코드 샘플을 테스트할 수 있습니다. 그러나 모든 예제가 기록된 대로 실행되도록 의도된 것은 아닙니다. 일부 코드 블록은 PowerShell 개념의 기본 그림입니다.
설명서에 사용되는 세 가지 유형의 코드 블록이 있습니다.
- 구문 블록
- 예시
- 실행 가능한 예제
구문 코드 블록
구문 코드 블록은 명령의 구문 구조를 설명하는 데 사용됩니다. 코드 펜스에서 언어 태그를 사용하지 마세요. 이 예제는 Get-Command cmdlet의 가능한 모든 매개 변수를 보여 줍니다.
```
Get-Command [-Verb <String[]>] [-Noun <String[]>] [-Module <String[]>]
[-FullyQualifiedModule <ModuleSpecification[]>] [-TotalCount <Int32>] [-Syntax]
[-ShowCommandInfo] [[-ArgumentList] <Object[]>] [-All] [-ListImported]
[-ParameterName <String[]>] [-ParameterType <PSTypeName[]>] [<CommonParameters>]
```
이 예제는 for 문을 일반적인 용어로 설명합니다.
```
for (<init>; <condition>; <repeat>)
{<statement list>}
```
예시
설명 예제는 PowerShell 개념을 설명하는 데 사용됩니다. 가능하면 예제에서 PowerShell 프롬프트를 사용하지 않아야 합니다. 그러나 설명 예제는 실행을 위해 복사하여 붙여넣을 수 없습니다. 이해하기 쉬운 간단한 예제에 가장 일반적으로 사용됩니다. PowerShell 프롬프트 및 예제 출력을 포함할 수 있습니다.
다음은 PowerShell 비교 연산자를 보여 주는 간단한 예제입니다. 이 경우, 독자가 이 예제를 복사해서 실행하는 것을 의도하지 않습니다. 이 예제에서는 간단한 프롬프트 문자열로 사용합니다 PS> .
```powershell
PS> 2 -eq 2
True
PS> 2 -eq 3
False
PS> 1,2,3 -eq 2
2
PS> "abc" -eq "abc"
True
PS> "abc" -eq "abc", "def"
False
PS> "abc", "def" -eq "abc"
abc
```
실행 가능한 예제
복잡한 예제 또는 복사 및 실행하려는 예제는 다음 블록 스타일 태그를 사용해야 합니다.
```powershell
<Your PowerShell code goes here>
```
구문 강조 표시를 방지하려면 PowerShell 명령으로 표시되는 출력을 출력 코드 블록으로 묶어야 합니다. 다음은 그 예입니다.
```powershell
Get-Command -Module Microsoft.PowerShell.Security
```
```Output
CommandType Name Version Source
----------- ---- ------- ------
Cmdlet ConvertFrom-SecureString 3.0.0.0 Microsoft.PowerShell.Security
Cmdlet ConvertTo-SecureString 3.0.0.0 Microsoft.PowerShell.Security
Cmdlet Get-Acl 3.0.0.0 Microsoft.PowerShell.Security
Cmdlet Get-AuthenticodeSignature 3.0.0.0 Microsoft.PowerShell.Security
Cmdlet Get-CmsMessage 3.0.0.0 Microsoft.PowerShell.Security
Cmdlet Get-Credential 3.0.0.0 Microsoft.PowerShell.Security
Cmdlet Get-ExecutionPolicy 3.0.0.0 Microsoft.PowerShell.Security
Cmdlet Get-PfxCertificate 3.0.0.0 Microsoft.PowerShell.Security
Cmdlet New-FileCatalog 3.0.0.0 Microsoft.PowerShell.Security
Cmdlet Protect-CmsMessage 3.0.0.0 Microsoft.PowerShell.Security
Cmdlet Set-Acl 3.0.0.0 Microsoft.PowerShell.Security
Cmdlet Set-AuthenticodeSignature 3.0.0.0 Microsoft.PowerShell.Security
Cmdlet Set-ExecutionPolicy 3.0.0.0 Microsoft.PowerShell.Security
Cmdlet Test-FileCatalog 3.0.0.0 Microsoft.PowerShell.Security
Cmdlet Unprotect-CmsMessage 3.0.0.0 Microsoft.PowerShell.Security
```
코드 레이블은 Output 구문 강조 표시 시스템에서 지원하는 공식 언어 가 아닙니다.
그러나 이 레이블은 게시 시스템에서 웹 페이지의 코드 상자 프레임에 출력 레이블을 추가하기 때문에 유용합니다.
출력 코드 상자에는 구문 강조 표시가 없습니다.
코딩 스타일 규칙
코드 샘플에서 줄 연속 방지
PowerShell 코드 예제에서는 줄 연속 문자(`)를 사용하지 마세요. 백틱 문자는 보기 어렵고 줄 끝에 추가 공백이 있는 경우 문제가 발생할 수 있습니다.
- PowerShell 스플래팅을 사용하여 여러 매개 변수가 있는 cmdlet의 줄 길이를 줄입니다.
- PowerShell의 자연스러운 줄 바꿈 기회를 활용하세요. 예를 들면 파이프 문자(
|) 뒤, 여는 중괄호({), 괄호((), 대괄호([) 뒤입니다.
예제에서 PowerShell 프롬프트를 사용하지 않습니다.
프롬프트 문자열의 사용은 권장되지 않으며 명령줄 사용을 설명하기 위한 시나리오로 제한해야 합니다. 이러한 예제의 대부분은 프롬프트 문자열PS>이어야 합니다. 이 프롬프트는 OS 관련 지표와 독립적입니다.
프롬프트를 변경하는 명령을 설명하는 예제 또는 표시되는 경로가 시나리오에 중요한 경우 프롬프트가 필요합니다. 다음 예제에서는 레지스트리 공급자를 사용할 때 프롬프트가 어떻게 변경되는지 보여 줍니다.
PS C:\> cd HKCU:\System\
PS HKCU:\System\> dir
Hive: HKEY_CURRENT_USER\System
Name Property
---- --------
CurrentControlSet
GameConfigStore GameDVR_Enabled : 1
GameDVR_FSEBehaviorMode : 2
Win32_AutoGameModeDefaultProfile : {2, 0, 1, 0...}
Win32_GameModeRelatedProcesses : {1, 0, 1, 0...}
GameDVR_HonorUserFSEBehaviorMode : 0
GameDVR_DXGIHonorFSEWindowsCompatible : 0
예제에서 별칭을 사용하지 마세요.
별칭을 구체적으로 문서화하지 않는 한 모든 cmdlet 및 매개 변수의 전체 이름을 사용합니다. Cmdlet 및 매개 변수 이름은 적절한 파스칼 대소문자 표기법을 사용해야 합니다.
예제에서 매개 변수 사용
위치 매개 변수를 사용하지 않습니다. 혼동의 가능성을 줄이려면 매개 변수가 위치인 경우에도 예제에 매개 변수 이름을 포함해야 합니다.
cmdlet 참조 문서의 서식 지정
Cmdlet 참조 아티클에는 특정 구조가 있습니다.
PlatyPS 는 이 구조를 정의합니다. PlatyPS는 Markdown에서 PowerShell 모듈에 대한 cmdlet 도움말을 생성합니다. Markdown 파일을 편집한 후 PlatyPS는 cmdlet에서 사용하는 Get-Help MAML 도움말 파일을 만들 수 있습니다.
PlatyPS에는 cmdlet 참조에 대한 특정 구조가 예상되는 스키마가 있습니다. PlatyPS 스키마 문서에서 는 이 구조를 설명합니다. 스키마 위반으로 인해 기여를 수락하기 전에 수정해야 하는 빌드 오류가 발생합니다.
- ATX 헤더 구조를 제거하지 마세요. PlatyPS는 특정 순서로 특정 헤더 집합을 예상합니다.
- H2 INPUTS 및 OUTPUTS 헤더에는 H3 형식이 있어야 합니다. cmdlet이 입력을 수행하거나 값을 반환하지 않는 경우 H3 값을
None사용합니다. - 모든 단락에서 인라인 코드 범위를 사용할 수 있습니다.
- 펜스 코드 블록은 EXAMPLES 섹션에서만 허용됩니다.
PlatyPS 스키마에서 예제는 H2 헤더입니다. 각 예제는 H3 헤더입니다. 예제 내에서 스키마는 코드 블록을 단락으로 구분할 수 없습니다. 스키마는 다음 구조만 허용합니다.
### Example X - Title sentence
0 or more paragraphs
1 or more code blocks
0 or more paragraphs.
각 예제에 번호를 매기고 간단한 제목을 추가합니다.
다음은 그 예입니다.
### Example 1: Get cmdlets, functions, and aliases
This command gets the PowerShell cmdlets, functions, and aliases that are installed on the
computer.
```powershell
Get-Command
```
### Example 2: Get commands in the current session
```powershell
Get-Command -ListImported
```
About_ 파일 서식 지정
About_* 파일은 Markdown으로 작성되었지만 일반 텍스트 파일로 제공됩니다.
Pandoc을 사용하여 Markdown을 일반 텍스트로 변환합니다.
About_* 파일은 PowerShell의 모든 버전과 게시 도구에서 최상의 호환성을 위해 형식이 지정됩니다.
기본 서식 지정 지침:
단락 줄을 80자로 제한
코드 블록을 76자로 제한
블록 따옴표 및 경고를 78자로 제한
이러한 특수 메타 문자를
\$사용하는 경우 및<:헤더 내에서 이러한 문자는 선행
\문자를 사용하여 이스케이프되거나 백틱(`)을 사용하여 코드 범위로 묶어야 합니다.단락 내에서 이러한 문자는 코드 범위에 넣어야 합니다. 다음은 그 예입니다.
### The purpose of the \$foo variable The `$foo` variable is used to store ...
Markdown 테이블
- 아티클의 경우
About_*테이블은 76자 이내여야 합니다.- 콘텐츠가 76자 제한에 맞지 않는 경우 글머리 기호 목록을 대신 사용합니다.
- 각 줄에서 여는 문자 및 닫는
|문자 사용
- 아티클의 경우
다음 단계
GitHub에서 Microsoft와 공동 작업
이 콘텐츠의 원본은 GitHub에서 찾을 수 있으며, 여기서 문제와 끌어오기 요청을 만들고 검토할 수도 있습니다. 자세한 내용은 참여자 가이드를 참조하세요.
PowerShell