about_Updatable_Help

PowerShell의 도움말을 항상 최신으로 유지하는 방법을 설명하는 문서예요. 도움말 파일을 직접 내려받아 설치하는 방식이라, 인터넷이 없는 환경에서도 커맨드라인에서 최신 도움말을 읽을 수 있게 해 줘요.

출처: https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_updatable_help

본문

간단한 설명

PowerShell의 업데이트 가능한 도움말(Updatable Help) 시스템을 설명해요.

자세한 설명

PowerShell은 cmdlet과 개념에 대한 최신 도움말 항목에 접근하는 여러 가지 방법을 제공해요.

업데이트 가능한 도움말 시스템은 PowerShell 3.0에서 도입됐는데요, 로컬 컴퓨터에 항상 최신 도움말 항목을 갖춰 놓아 커맨드라인에서 바로 읽을 수 있게 하는 게 목적이에요. 도움말 파일을 쉽게 내려받고 설치할 수 있고, 더 새로운 도움말 파일이 나오면 그때마다 갱신할 수도 있어요.

여러 대의 컴퓨터를 관리하는 기업 환경이나 인터넷에 접속하지 못하는 컴퓨터를 위해서는, 도움말 파일을 파일 시스템 디렉터리나 파일 공유에 먼저 내려받은 뒤 그 파일 공유에서 도움말을 설치하는 방식도 지원해요.

PowerShell 4.0에서는 HelpInfoUri 속성이 Windows PowerShell 원격(remoting) 환경에서도 유지되는데요, 덕분에 Save-Help가 원격 컴퓨터에 설치된 모듈이면서 로컬 컴퓨터에는 없을 수 있는 모듈에 대해서도 동작해요. 인터넷에 접속되지 않은 컴퓨터에서 Export-Clixml을 실행해 PSModuleInfo 개체를 디스크나 이동식 미디어(예: USB 드라이브)에 저장하고, 인터넷에 연결된 컴퓨터에서 그 개체를 가져온 뒤 Save-Help를 실행하는 식으로요. 저장된 도움말은 다시 이동식 미디어로 원격·비연결 컴퓨터에 복사해 Update-Help로 설치할 수 있어요. 이렇게 Save-Help 기능이 개선되면서, 어떤 네트워크 접속도 없는 컴퓨터에도 도움말을 설치할 수 있게 됐어요. 새 Save-Help 활용 예시는 이 문서의 파일 공유에서 도움말 업데이트하기를 참고해요.

업데이트 가능한 도움말은 컴퓨터에 도움말 파일이 하나도 없을 때도, 최신 도움말 항목과 cmdlet의 기본 도움말을 온라인으로 접근할 수 있게 지원해요.

PowerShell은 기본적으로 도움말 파일이 딸려 오지 않아요. 업데이트 가능한 도움말 기능을 쓰면 PowerShell에 기본 포함된 모든 명령과 Windows 모듈의 도움말 파일을 설치할 수 있어요.

업데이트 가능한 도움말 cmdlet

Update-Help: 인터넷이나 파일 공유에서 최신 도움말 파일을 내려받아 로컬 컴퓨터에 설치해요.
Save-Help: 인터넷에서 최신 도움말 파일을 내려받아 파일 시스템 디렉터리나 파일 공유에 저장해요. 컴퓨터에 도움말을 설치하려면 Update-Help를 사용해요.
Get-Help: 커맨드라인에서 도움말 항목을 표시해요. 컴퓨터의 도움말 파일에서 도움말을 가져오고, 도움말 파일이 없는 cmdlet·함수는 자동 생성된 도움말을 표시해요. cmdlet·함수·스크립트·워크플로의 온라인 도움말 항목은 기본 인터넷 브라우저로 열어 줘요.

자동 생성 도움말: 도움말 파일이 없는 경우

컴퓨터에 cmdlet이나 함수, 워크플로의 도움말 파일이 없다면 Get-Help는 자동 생성된 도움말을 보여 주면서 도움말 파일을 내려받거나 온라인으로 읽으라고 안내해요.

자동 생성된 도움말에는 구문(syntax)과 별칭(aliases), 그리고 업데이트 가능한 도움말 cmdlet을 쓰는 방법과 온라인 도움말 항목에 접근하는 방법을 설명하는 참고(remarks)가 포함돼요.

예를 들어 아래 명령은 Get-Culture cmdlet의 기본 도움말을 가져와요. 출력은 컴퓨터에 도움말 파일이 없을 때 Get-Help가 보여 주는 화면이에요.

Get-Help Get-Culture

NAME
    Get-Culture

SYNTAX
    Get-Culture [<CommonParameters>]

ALIASES
    None

REMARKS
    To get the latest Help content including descriptions and examples
    type: Update-Help.

모듈용 도움말 파일

업데이트 가능한 도움말의 가장 작은 단위는 모듈 하나의 도움말이에요. 모듈 도움말에는 그 모듈의 모든 cmdlet·함수·워크플로·공급자·스크립트·개념에 대한 도움말이 담겨요. 컴퓨터에 설치된 모든 모듈의 도움말을 갱신할 수 있는데, 현재 세션에 가져오지 않은 모듈이라도 상관없어요.

도움말은 모듈 전체를 갱신할 수 있지만, 개별 cmdlet만 골라서 갱신할 수는 없어요.

특정 cmdlet이 어느 모듈에 들어 있는지 찾으려면 다음 형식의 명령을 써요.

(Get-Command <cmdlet-name>).ModuleName

예를 들어 Set-ExecutionPolicy cmdlet이 든 모듈을 찾으려면 이렇게 입력해요.

(Get-Command Set-ExecutionPolicy).ModuleName

특정 모듈의 도움말을 갱신하려면 이렇게 입력해요.

Update-Help -Module <ModuleName>

예를 들어 Set-ExecutionPolicy cmdlet이 포함된 모듈의 도움말을 갱신하려면 이렇게 입력해요.

Update-Help -Module Microsoft.PowerShell.Security

업데이트 가능한 도움말의 사용 권한

$PSHOME/Modules 디렉터리의 모듈 도움말을 갱신하려면 컴퓨터의 Administrators 그룹 구성원이어야 해요.

Administrators 그룹 구성원이 아니라면 이 모듈들의 도움말은 갱신할 수 없어요. 다만 인터넷에 접속할 수 있다면 온라인으로 도움말을 볼 수는 있어요.

$HOME/Documents/PowerShell/Modules 디렉터리나 $HOME 디렉터리의 다른 하위 디렉터리에 있는 모듈의 도움말 갱신에는 특별한 권한이 필요 없어요.

Update-Help와 Save-Help cmdlet에는 현재 사용자의 명시적 자격 증명을 제공하는 UseDefaultCredentials 매개 변수가 있어요. 이 매개 변수는 보안이 필요한 인터넷 위치에 접근할 때 쓰도록 설계된 거예요.

Update-Help와 Save-Help cmdlet에는 Credential 매개 변수도 있는데요, 이걸 쓰면 원격 컴퓨터에서 명령을 실행하면서 세 번째 컴퓨터의 파일 공유에 접근할 수 있어요. Credential 매개 변수는 Update-Help의 SourcePath·LiteralPath 매개 변수나 Save-Help의 DestinationPath·LiteralPath 매개 변수를 쓸 때만 유효해요.

도움말 파일 설치·업데이트하기

도움말 파일을 처음으로 내려받아 설치하거나 컴퓨터의 도움말 파일을 갱신하려면 Update-Help cmdlet을 사용해요.

Update-Help cmdlet이 힘든 작업을 모두 처리해 줘요. 처리하는 작업은 다음과 같아요.

업데이트 가능한 도움말을 지원하는 모듈을 판별해요.
각 모듈이 업데이트 가능한 도움말 파일을 저장하는 인터넷 위치를 찾아요.
컴퓨터의 각 모듈 도움말 파일을 각 모듈에서 사용 가능한 최신 도움말 파일과 비교해요.
인터넷에서 새 파일을 내려받아요.
도움말 파일 패키지의 래퍼를 풀어요.
파일이 올바른 도움말 파일인지 확인해요.
도움말 파일을 모듈 디렉터리의 언어별 하위 디렉터리에 설치해요.

새 도움말 항목은 Get-Help cmdlet으로 확인할 수 있어요. PowerShell을 다시 시작할 필요는 없어요.

업데이트 가능한 도움말을 지원하는 컴퓨터의 모든 모듈에 대해 도움말을 설치하거나 갱신하려면 이렇게 입력해요.

Update-Help

특정 모듈의 도움말만 갱신하려면 Update-Help의 Module 매개 변수를 추가해요. 모듈 이름에는 와일드카드 문자가 허용돼요.

예를 들어 ServerManager 모듈의 도움말을 갱신하려면 이렇게 입력해요.

Update-Help -Module ServerManager

매개 변수 없이 실행하면 Update-Help는 세션의 모든 모듈과 설치된 모듈 중 업데이트 가능한 도움말을 지원하는 모든 모듈의 도움말을 갱신해요. 포함되려면 모듈이 PSModulePath 환경 변수 값에 나열된 디렉터리에 설치되어 있어야 해요. 이들은 Get-Module -ListAvailable 명령이 반환하는 모듈과도 같아요.

Module 매개 변수 값이 *(전체)이면 Update-Help는 업데이트 가능한 도움말을 지원하지 않는 모듈까지 포함해 설치된 모든 모듈의 도움말 갱신을 시도해요. 이 명령은 cmdlet이 지원하지 않는 모듈을 만나면서 오류를 많이 발생시키는 경우가 보통이에요.

파일 공유에서 도움말 업데이트하기

인터넷에 연결되지 않은 컴퓨터를 지원하거나, 기업 환경에서 도움말 갱신을 통제·간소화하려면 Save-Help cmdlet을 사용해요. Save-Help는 인터넷에서 도움말 파일을 내려받아 지정한 파일 시스템 디렉터리에 저장해요.

Save-Help는 지정한 디렉터리의 도움말 파일을 각 모듈에서 사용 가능한 최신 도움말 파일과 비교해요. 디렉터리에 도움말 파일이 없거나 모듈에 더 새로운 도움말 파일이 있다면 Save-Help가 인터넷에서 새 파일을 내려받아요. 다만 파일의 래퍼를 풀거나 설치하지는 않아요.

파일 시스템 디렉터리에 저장된 도움말 파일로 컴퓨터의 도움말을 설치하거나 갱신하려면 Update-Help cmdlet의 SourcePath 매개 변수를 사용해요. Update-Help는 최신 도움말 파일을 식별해 래퍼를 풀고 검증한 뒤 모듈 디렉터리의 언어별 하위 디렉터리에 설치해요.

예를 들어 설치된 모든 모듈의 도움말을 \\Server\Share 디렉터리에 저장하려면 이렇게 입력해요.

Save-Help -DestinationPath \\Server\Share

그다음 \\Server\Share 디렉터리에서 도움말을 갱신하려면 이렇게 입력해요.

Update-Help -SourcePath \\Server\Share

다음 예시들은 로컬 컴퓨터에 설치되지 않은 모듈의 도움말을 Save-Help로 저장하는 방법을 보여 줘요. 이 예시에서 관리자는 인터넷에 연결된 클라이언트 컴퓨터에서 DHCP 서버 역할이나 DhcpServer 모듈을 로컬 컴퓨터에 설치하지 않은 채, DhcpServer 모듈의 도움말을 저장해요.

방법 1: Invoke-Command로 원격 모듈의 PSModuleInfo 개체를 가져와 $m 변수에 저장한 뒤, 그 PSModuleInfo 개체를 모듈 이름으로 지정해 Save-Help를 실행해요.

$invokeCommandSplat = @{
    ComputerName = 'RemoteServer'
    ScriptBlock = { Get-Module -Name DhcpServer -ListAvailable }
}
$m = Invoke-Command @invokeCommandSplat
Save-Help -Module $m -DestinationPath C:\SavedHelp

방법 2: DHCP Server 모듈을 실행 중인 컴퓨터를 대상으로 하는 PSSession을 열어 모듈의 PSModuleInfo 개체를 가져와 $m 변수에 저장한 뒤, $m 변수에 저장된 개체를 대상으로 Save-Help를 실행해요.

$s = New-PSSession -ComputerName RemoteServer
$m = Get-Module -PSSession $s -Name DhcpServer -ListAvailable
Save-Help -Module $m -DestinationPath C:\SavedHelp

방법 3: DHCP Server 모듈을 실행 중인 컴퓨터를 대상으로 하는 CIM 세션을 열어 모듈의 PSModuleInfo 개체를 가져와 $m 변수에 저장한 뒤, $m 변수에 저장된 개체를 대상으로 Save-Help를 실행해요.

$c = New-CimSession -ComputerName RemoteServer
$m = Get-Module -CimSession $c -Name DhcpServer -ListAvailable
Save-Help -Module $m -DestinationPath C:\SavedHelp

다음 예시에서는 네트워크 접속이 없는 컴퓨터에 DHCP Server 모듈의 도움말을 설치해요.

먼저 Export-Clixml로 PSModuleInfo 개체를 공유 폴더나 이동식 미디어에 내보내요.

$m = Get-Module -Name DhcpServer -ListAvailable
Export-Clixml -Path E:\UsbDrive\DhcpModule.xml -InputObject $m

다음으로 이동식 미디어를 인터넷에 접속된 컴퓨터로 옮겨 Import-Clixml로 PSModuleInfo 개체를 가져와요. 가져온 DhcpServer 모듈 PSModuleInfo 개체를 대상으로 Save-Help를 실행해 도움말을 저장해요.

$deserialized_m = Import-Clixml E:\UsbDrive\DhcpModule.xml
Save-Help -Module $deserialized_m -DestinationPath E:\UsbDrive\SavedHelp

마지막으로 이동식 미디어를 다시 네트워크 접속이 없는 컴퓨터로 옮긴 뒤 Update-Help로 도움말을 설치해요.

Update-Help -Module DhcpServer -SourcePath E:\UsbDrive\SavedHelp

매개 변수 없이 실행하면 Save-Help는 세션의 모든 모듈과 설치된 모듈 중 업데이트 가능한 도움말을 지원하는 모든 모듈의 도움말을 내려받아요. 포함되려면 모듈이 로컬 컴퓨터 또는 도움말을 저장하려는 원격 컴퓨터의 $Env:PSModulePath 환경 변수 값에 나열된 디렉터리에 설치되어 있어야 해요. 이들은 Get-Help -ListAvailable 명령을 실행해 반환되는 모듈과도 같아요.

다른 언어로 도움말 파일 업데이트하기

기본적으로 Update-Help와 Save-Help cmdlet은 로컬 컴퓨터의 Windows에 설정된 UI 문화(culture)와 언어로 도움말을 내려받아요. 지정한 모듈의 도움말 파일이 로컬 UI 문화로 제공되지 않으면 Update-Help와 Save-Help는 Windows 언어 폴백 규칙에 따라 가장 적합한 지원 언어를 찾아요.

다만 Update-Help와 Save-Help cmdlet의 UICulture 매개 변수를 쓰면 해당 언어로 제공되는 모든 UI 문화의 도움말 파일을 내려받고 설치할 수 있어요.

예를 들어 세션의 모든 모듈에 대한 최신 도움말 파일을 일본어(ja-JP)와 프랑스어(fr-FR)로 저장하려면 이렇게 입력해요.

Save-Help -Path \Server\Share -UICulture ja-JP, fr-FR

지정한 언어로 모듈의 도움말 파일이 제공되지 않으면 Update-Help와 Save-Help cmdlet은 각 모듈의 도움말이 제공되는 언어 목록을 담은 오류 메시지를 반환해요. 그러면 그중에서 요구 사항에 가장 맞는 대안을 고를 수 있어요.

참고

현재 업데이트 가능한 도움말 콘텐츠는 영어(en-US)로만 게시돼요.

온라인 도움말 사용하기

로컬 컴퓨터의 도움말 파일을 갱신할 수 없거나 갱신하고 싶지 않다면, 온라인으로 최신 도움말 파일을 얻을 수도 있어요.

어떤 cmdlet이나 함수의 온라인 도움말 항목을 열려면 Get-Help cmdlet의 Online 매개 변수를 사용해요.

예를 들어 다음 명령은 Get-Job cmdlet의 온라인 도움말 항목을 기본 인터넷 브라우저로 열어 줘요.

Get-Help Get-Job -Online

스크립트의 온라인 도움말을 보려면 Online 매개 변수와 스크립트의 전체 경로를 함께 사용해요.

Online 매개 변수는 About 항목에서는 동작하지 않아요. PowerShell 언어를 포함한 about 항목을 보려면 PowerShell About Topics를 참고해요.

인터넷 다운로드 줄이기·막기

인터넷 다운로드를 줄이고 인터넷에 연결되지 않은 사용자에게 업데이트 가능한 도움말을 제공하려면 Save-Help cmdlet을 사용해요. 인터넷에서 도움말을 내려받아 네트워크 공유에 저장해요. 그런 다음 모든 컴퓨터에서 Update-Help 명령을 실행하는 그룹 정책 설정이나 예약 작업(scheduled job)을 만들어요. Update-Help cmdlet의 SourcePath 매개 변수 값을 그 네트워크 공유로 설정해 두면 되죠.

인터넷에 접속한 사용자가 인터넷에서 업데이트 가능한 도움말을 내려받지 못하게 하려면 Set the default source path for Update-Help 그룹 정책 설정을 사용해요.

이 그룹 정책 설정은 영향받는 모든 컴퓨터의 모든 Update-Help 명령에, 지정한 파일 시스템 위치를 값으로 하는 SourcePath 매개 변수를 암시적으로 추가해요. 사용자는 SourcePath 매개 변수를 명시적으로 써서 다른 파일 시스템 위치를 지정할 수는 있지만, SourcePath 매개 변수를 제외하고 인터넷에서 도움말을 내려받을 수는 없어요.

참고

Set the default source path for Update-Help 그룹 정책 설정은 컴퓨터 구성(Computer Configuration)과 사용자 구성(User Configuration) 아래에 모두 나타나요. 하지만 실제로 적용되는 것은 컴퓨터 구성 아래의 정책 설정뿐이에요. 사용자 구성 아래의 정책 설정은 무시돼요.

자세한 내용은 about_Group_Policy_Settings를 참고해요.

비표준 모듈의 도움말 업데이트하기

Get-Module cmdlet의 ListAvailable 매개 변수가 반환하지 않는 모듈의 도움말을 갱신하거나 저장하려면, Update-Help나 Save-Help 명령을 실행하기 전에 그 모듈을 현재 세션으로 가져와요. 원격 컴퓨터에서는 Save-Help 명령을 실행하기 전에, 원격 컴퓨터에 연결된 현재 세션 또는 Invoke-Command 스크립트 블록으로 모듈을 가져와요.

모듈이 현재 세션에 있으면 매개 변수 없이 Update-Help나 Save-Help cmdlet을 실행하거나, Module 매개 변수로 모듈 이름을 지정해요.

Update-Help와 Save-Help cmdlet의 Module 매개 변수는 모듈 이름만 받아요. 모듈 파일의 경로는 받지 않아요.

이 기법은 Get-Module cmdlet의 ListAvailable 매개 변수가 반환하지 않는 보통의 모듈——예를 들어 $Env:PSModulePath 환경 변수에 나열되지 않은 위치에 설치된 모듈이나, 모듈 디렉터리에 디렉터리 이름과 같은 기본 이름을 가진 파일이 하나도 없어 제대로 형성되지 않은(not well-formed) 모듈——의 도움말을 갱신하거나 저장할 때 써요.

업데이트 가능한 도움말 지원하기

모듈을 직접 만든다면, 모듈에 온라인 도움말과 업데이트 가능한 도움말을 지원하도록 구성할 수 있어요. 자세한 내용은 Supporting Updatable Help와 Supporting Online Help를 참고해요.

업데이트 가능한 도움말은 PowerShell 스냅인(snap-in)이나 설명 기반 도움말(comment-based help)에서는 사용할 수 없어요.

참고 사항

Update-Help와 Save-Help cmdlet은 Windows 사전 설치 환경(Windows PE)에서는 지원되지 않아요.

about_Updatable_Help