about_Module_Manifests — 모듈 매니페스트, 모듈의 신상정보 카드
about_Module_Manifests — 모듈 매니페스트, 모듈의 신상정보 카드
모듈을 만들다 보면 "이 모듈은 어떤 버전까지 호환되고, 어디까지 공개할지" 같은 걸 미리 정해두고 싶어져요. 그런 정보를 모아둔 게 바로 모듈 매니페스트예요. 매니페스트는 단순한 설정 파일이지만, 모듈을 더 잘게 조작하고 배포할 때 사실상 필수라고 보면 돼요. 이번엔 모듈 매니페스트가 뭘 하는지, 어떤 항목들이 있는지 하나씩 살펴볼게요.
본문
모듈 매니페스트는 해시 테이블을 담고 있는 PowerShell 데이터 파일(.psd1)이에요. 그 해시 테이블의 키-값 쌍이 모듈의 내용과 속성을 설명하고, 전제 조건을 정의하며, 구성 요소가 어떻게 처리될지를 제어해요.
매니페스트는 모듈을 불러오는 데 필수는 아니에요. 하지만 모듈을 PowerShell Gallery에 게시하려면 반드시 필요해요. 또 매니페스트를 쓰면 모듈의 구현과 "모듈이 어떻게 불러지는지"를 분리할 수 있어요. 매니페스트를 통해 요구 사항, 호환성, 불러오는 순서 같은 것들을 정의할 수 있는 거죠.
매니페스트의 어떤 설정 항목도 지정하지 않은 채 New-ModuleManifest를 실행하면, 아주 간단한 최소 매니페스트 파일이 만들어져요. 아래 코드 조각이 바로 그 기본 출력이에요. 길이 때문에 주석과 공백은 생략했어요.
@{
# RootModule = ''
ModuleVersion = '1.0'
# CompatiblePSEditions = @()
GUID = 'e7184b71-2527-469f-a50e-166b612dfb3b'
Author = 'username'
CompanyName = 'Unknown'
Copyright = '(c) 2022 username. All rights reserved.'
# Description = ''
# PowerShellVersion = ''
# PowerShellHostName = ''
# PowerShellHostVersion = ''
# DotNetFrameworkVersion = ''
# CLRVersion = ''
# ProcessorArchitecture = ''
# RequiredModules = @()
# RequiredAssemblies = @()
# ScriptsToProcess = @()
# TypesToProcess = @()
# FormatsToProcess = @()
# NestedModules = @()
FunctionsToExport = @()
CmdletsToExport = @()
VariablesToExport = '*'
AliasesToExport = @()
# DscResourcesToExport = @()
# ModuleList = @()
# FileList = @()
PrivateData = @{
PSData = @{
# Tags = @()
# LicenseUri = ''
# ProjectUri = ''
# IconUri = ''
# ReleaseNotes = ''
# ExternalModuleDependencies = @()
} # End of PSData hashtable
} # End of PrivateData hashtable
# HelpInfoURI = ''
# DefaultCommandPrefix = ''
}
모듈을 게시하기 전에 Test-ModuleManifest로 매니페스트를 검증할 수 있어요. 매니페스트가 잘못됐거나, 현재 세션이 매니페스트에 설정된 요구 사항을 충족하지 못해 모듈을 불러올 수 없으면 Test-ModuleManifest는 오류를 반환해요.
매니페스트 안에서 스크립트 코드 쓰기
매니페스트 파일에서 항목에 할당하는 값은 PowerShell이 평가하는 표현식일 수 있어요. 그래서 변수를 바탕으로 경로를 만들거나 조건에 따라 값을 정할 수 있어요.
Import-Module로 모듈을 불러오면 매니페스트가 Restricted 언어 모드에서 평가돼요. Restricted 모드는 사용할 수 있는 명령과 변수를 제한해요.
사용 가능한 명령
Import-LocalizedDataConvertFrom-StringDataWrite-HostOut-HostJoin-Path
사용 가능한 변수
$PSScriptRoot$PSEdition$EnabledExperimentalFeatures- 환경 변수들, 예를 들어
$Env:TEMP
더 자세한 내용은 about_Language_Modes 문서를 참고하세요.
매니페스트 설정 항목들
아래부터는 모듈 매니페스트에서 쓸 수 있는 모든 설정 항목을 어떻게 쓰는지와 함께 자세히 다룰게요. 각 항목은 먼저 한 줄 요약을 보여주고, 그다음 표로 항목을 정리해요. 표는 다음 내용을 담아요.
- Input type: 매니페스트에서 이 항목에 지정할 수 있는 객체 유형
- Required: 이 값이
Yes면 불러오기와 PowerShell Gallery 게시에 모두 필요한 필수 항목이에요.No면 어느 쪽에도 필요 없어요.PowerShell Gallery면 PowerShell Gallery에 게시할 때만 필요해요. - Value if unset: 명시적으로 설정하지 않고 불러왔을 때 이 항목이 갖는 값
- Accepts wildcards: 이 항목이 와일드카드 값을 받을 수 있는지 여부
RootModule
이 항목은 모듈의 주 파일, 그러니까 루트 파일을 지정해요. 모듈이 불러와지면 루트 모듈 파일이 내보내는 멤버들이 호출자의 세션 상태로 불러와져요.
| Value | |
|---|---|
| Input Type | System.String |
| Required | No |
| Value if unset | $null |
| Accepts wildcards | No |
값은 다음 중 하나의 경로여야 해요.
- 스크립트(
.ps1) — Constrained Language 모드에서는 지원되지 않아요 - 스크립트 모듈(
.psm1) - 모듈 매니페스트(
.psd1) - 어셈블리(
.dll) - cmdlet 정의 XML 파일(
.cdxml) - Windows PowerShell 5.1 워크플로(
.xaml) — Windows PowerShell 5.1에서만 지원돼요
경로는 모듈 매니페스트 기준의 상대 경로여야 해요.
RootModule 키에 루트 파일이 지정되지 않은 매니페스트가 있다면, 그 매니페스트 자체가 모듈의 주 파일이 되고 모듈은 매니페스트 모듈(ModuleType = Manifest)이 돼요. RootModule이 정의되면 모듈의 유형은 사용된 파일 확장자로 결정돼요.
.ps1또는.psm1파일이면 모듈 유형은 Script.psd1파일이면 모듈 유형은 Manifest.dll파일이면 모듈 유형은 Binary.cdxml파일이면 모듈 유형은 CIM.xaml파일이면 모듈 유형은 Workflow
기본적으로 RootModule의 모든 모듈 멤버가 내보내져요.
팁
모듈 유형에 따라 불러오는 속도가 달라요. Binary, Script, CIM 모듈 유형 사이에서요. 더 자세한 내용은 PowerShell module authoring considerations 문서를 참고하세요.
예를 들어, 아래 모듈은 ModuleType이 Manifest예요. 이 모듈이 내보낼 수 있는 모듈 멤버는 NestedModules 설정에서 지정한 모듈에 정의된 것들뿐이에요.
@{
RootModule = ''
}
참고
이 항목은 매니페스트에서 ModuleToProcess라는 이름으로도 지정할 수 있어요. 그 이름도 유효하지만, RootModule을 쓰는 게 권장 관행이에요.
ModuleVersion
이 항목은 모듈의 버전을 지정해요. 시스템에 모듈 버전이 여러 개 있으면, Import-Module을 실행했을 때 기본적으로 가장 최신 버전이 불러와져요.
| Value | |
|---|---|
| Input Type | System.String |
| Required | Yes |
| Value if unset | None |
| Accepts wildcards | No |
이 항목의 값은 Import-Module을 실행했을 때 System.Version으로 변환될 수 있어야 해요.
예를 들어, 아래 매니페스트는 모듈 버전을 '1.2.3'으로 선언해요.
@{
ModuleVersion = '1.2.3'
}
모듈을 불러오고 Version 속성을 확인해 보면, 그 값이 문자열이 아니라 System.Version 객체라는 걸 알 수 있어요.
$ExampleModule = Import-Module example.psd1
$ExampleModule.Version
$ExampleModule.Version.GetType().Name
Major Minor Build Revision
----- ----- ----- --------
1 2 3 -1
Version
CompatiblePSEditions
이 항목은 모듈과 호환되는 PSEdition을 지정해요.
| Value | |
|---|---|
| Input Type | System.String[] |
| Accepted Values | Desktop, Core |
| Required | No |
| Value if unset | $null |
| Accepts wildcards | No |
이 항목의 값이 $null이면 세션의 PSEdition과 관계없이 모듈을 불러올 수 있어요. 허용되는 값 중 하나 이상으로 설정할 수 있어요.
PSEdition에 대한 자세한 내용은 아래를 참고하세요.
이 항목이 정의되면, 모듈은 $PSEdition 자동 변수의 값이 이 항목에 포함된 세션에서만 불러올 수 있어요.
참고
$PSEdition 자동 변수는 5.1 버전에서 도입됐기 때문에, 더 오래된 Windows PowerShell 버전은 CompatiblePSEditions 항목을 사용하는 모듈을 불러올 수 없어요.
예를 들어, 아래 매니페스트는 어떤 세션이든 불러올 수 있어요.
@{
# CompatiblePSEditions = @()
}
아래처럼 설정을 지정하면, $PSEdition 자동 변수의 값이 Core인 세션에서만 이 모듈을 불러올 수 있어요.
@{
CompatiblePSEditions = @('Core')
}
GUID
이 항목은 모듈의 고유 식별자를 지정해요. GUID는 같은 이름을 가진 모듈들을 구별하는 데 쓰여요.
| Value | |
|---|---|
| Input Type | System.String |
| Required | No |
| Value if unset | 00000000-0000-0000-0000-000000000000 |
| Accepts wildcards | No |
이 항목의 값은 Import-Module을 실행했을 때 System.Guid로 변환될 수 있어야 해요.
주의
필수 항목은 아니지만, 매니페스트에 GUID를 지정하지 않는 건 아무 이점도 없고 모듈 이름 충돌을 일으킬 수 있어요.
매니페스트에 쓸 새 GUID를 만들 수 있어요.
New-Guid | Select-Object -ExpandProperty Guid
8456b025-2fa5-4034-ae47-e6305f3917ca
@{
GUID = '8456b025-2fa5-4034-ae47-e6305f3917ca'
}
머신에 같은 이름의 모듈이 또 있어도, 모듈의 정규화된 이름을 지정해 원하는 모듈을 불러올 수 있어요.
Import-Module -FullyQualifiedName @{
ModuleName = 'Example'
GUID = '8456b025-2fa5-4034-ae47-e6305f3917ca'
ModuleVersion = '1.0.0'
}
Author
이 항목은 모듈 작성자를 식별해요.
| Value | |
|---|---|
| Input Type | System.String |
| Required | PowerShell Gallery |
| Value if unset | $null |
| Accepts wildcards | No |
아래 매니페스트는 모듈의 작성자가 Contoso Developer Experience Team이라고 선언해요.
@{
Author = 'Contoso Developer Experience Team'
}
CompanyName
이 항목은 모듈을 만든 회사나 공급업체를 식별해요.
| Value | |
|---|---|
| Input Type | System.String |
| Required | No |
| Value if unset | $null |
| Accepts wildcards | No |
아래 매니페스트는 모듈이 Contoso, Ltd.에서 만들었다고 선언해요.
@{
CompanyName = 'Contoso, Ltd.'
}
Copyright
이 항목은 모듈에 대한 저작권 문구를 지정해요.
| Value | |
|---|---|
| Input Type | System.String |
| Required | No |
| Value if unset | $null |
| Accepts wildcards | No |
아래 매니페스트는 2022년 기준으로 모든 권리를 Contoso, Ltd.에 보유한다는 저작권 문구를 선언해요.
@{
Copyright = '(c) 2022 Contoso, Ltd. All rights reserved.'
}
Description
이 항목은 모듈을 높은 수준에서 설명해요.
| Value | |
|---|---|
| Input Type | System.String |
| Required | PowerShell Gallery |
| Value if unset | $null |
| Accepts wildcards | No |
아래 매니페스트는 짧은 설명을 담고 있어요. here-string을 쓰면 더 길거나 여러 줄로 된 설명을 쓸 수도 있어요.
@{
Description = 'Example commands to show a valid module manifest'
}
PowerShellVersion
이 항목은 모듈이 요구하는 최소 PowerShell 버전을 지정해요.
| Value | |
|---|---|
| Input Type | System.String |
| Required | No |
| Value if unset | $null |
| Accepts wildcards | No |
이 항목의 값은 Import-Module을 실행했을 때 System.Version으로 변환될 수 있어야 해요.
이 항목을 설정하지 않으면 PowerShell은 현재 버전을 기준으로 모듈 불러오기를 제한하지 않아요.
예를 들어, 아래 매니페스트는 모든 버전의 PowerShell과 Windows PowerShell과 호환된다고 선언해요.
@{
# PowerShellVersion = ''
}
PowerShellVersion을 7.2로 설정하면 PowerShell 7.2 이상에서만 모듈을 불러올 수 있어요.
@{
PowerShellVersion = '7.2'
}
PowerShellHostName
이 항목은 모듈이 요구하는 PowerShell 호스트 프로그램의 이름을 지정해요. 예를 들어 Windows PowerShell ISE Host나 ConsoleHost 같은 거예요.
| Value | |
|---|---|
| Input Type | System.String |
| Required | No |
| Value if unset | $null |
| Accepts wildcards | No |
세션의 호스트 이름은 $Host.Name 문으로 확인할 수 있어요. 예를 들어 원격 세션의 호스트는 ConsoleHost가 아니라 ServerRemoteHost라는 걸 볼 수 있어요.
$Host.Name
Enter-PSSession -ComputerName localhost
$Host.Name
ConsoleHost
[localhost]: PS C:\Users\username\Documents> $Host.Name
ServerRemoteHost
아래 모듈은 어떤 호스트에서든 불러올 수 있어요.
@{
# PowerShellHostName = ''
}
PowerShellHostName을 ServerRemoteHost로 설정하면 원격 PowerShell 세션에서만 모듈을 불러올 수 있어요.
@{
PowerShellHostName = 'ServerRemoteHost'
}
PowerShellHostVersion
이 항목은 모듈이 요구하는 PowerShell 호스트 프로그램의 최소 버전을 지정해요.
| Value | |
|---|---|
| Input Type | System.String |
| Required | No |
| Value if unset | $null |
| Accepts wildcards | No |
이 항목의 값은 Import-Module을 실행했을 때 System.Version으로 변환될 수 있어야 해요.
주의
이 항목은 PowerShellHostName 항목 없이도 쓸 수 있지만, 예상치 못한 동작이 생길 가능성이 높아져요. PowerShellHostName 항목과 함께 쓸 때만 이 항목을 쓰세요.
예를 들어, 아래 매니페스트의 모듈은 호스트 버전과 관계없이 ConsoleHost에서 실행되는 어떤 PowerShell 세션이든 불러올 수 있어요.
@{
PowerShellHostName = 'ConsoleHost'
# PowerShellHostVersion = ''
}
PowerShellHostVersion을 5.1로 설정하면, 콘솔 호스트 버전이 5.1 이상인 ConsoleHost에서 실행되는 어떤 PowerShell 세션이든 모듈을 불러올 수 있어요.
@{
PowerShellHostName = 'ConsoleHost'
PowerShellHostVersion = '5.1'
}
DotNetFrameworkVersion
이 항목은 모듈이 요구하는 Microsoft .NET Framework의 최소 버전을 지정해요.
| Value | |
|---|---|
| Input Type | System.String |
| Required | No |
| Value if unset | $null |
| Accepts wildcards | No |
참고
이 항목은 PowerShell Desktop 버전(예: Windows PowerShell 5.1)에서만 유효하고, 4.5보다 낮은 .NET Framework 버전에만 적용돼요. 더 새로운 버전의 PowerShell이나 .NET Framework에는 이 요구 사항이 아무 효과가 없어요.
이 항목의 값은 Import-Module을 실행했을 때 System.Version으로 변환될 수 있어야 해요.
예를 들어, 아래 매니페스트는 Microsoft .NET Framework 버전과 관계없이 어떤 PowerShell이나 Windows PowerShell 세션이든 모듈을 불러올 수 있다고 선언해요.
@{
# DotNetFrameworkVersion = ''
}
DotNetFrameworkVersion을 4.0으로 설정하면, 최신으로 사용 가능한 Microsoft .NET Framework 버전이 최소 4.0인 Windows PowerShell 세션 어디서든 이 모듈을 불러올 수 있어요. 어떤 PowerShell 세션에서도 불러올 수 있고요.
@{
DotNetFrameworkVersion = '4.0'
}
CLRVersion
이 항목은 모듈이 요구하는 Microsoft .NET Framework의 CLR(Common Language Runtime) 최소 버전을 지정해요.
| Value | |
|---|---|
| Input Type | System.String |
| Required | No |
| Value if unset | $null |
| Accepts wildcards | No |
참고
이 항목은 PowerShell Desktop 버전(예: Windows PowerShell 5.1)에서만 유효하고, 4.5보다 낮은 .NET Framework 버전에만 적용돼요. 더 새로운 버전의 PowerShell이나 .NET Framework에는 이 요구 사항이 아무 효과가 없어요.
이 항목의 값은 Import-Module을 실행했을 때 System.Version으로 변환될 수 있어야 해요.
예를 들어, 아래 매니페스트는 Microsoft .NET Framework의 CLR 버전과 관계없이 어떤 PowerShell이나 Windows PowerShell 세션이든 모듈을 불러올 수 있다고 선언해요.
@{
# CLRVersion = ''
}
CLRVersion을 4.0으로 설정하면, 최신으로 사용 가능한 CLR 버전이 최소 4.0인 Windows PowerShell 세션 어디서든 이 모듈을 불러올 수 있어요. 어떤 PowerShell 세션에서도 불러올 수 있고요.
@{
CLRVersion = '4.0'
}
ProcessorArchitecture
이 항목은 모듈이 요구하는 프로세서 아키텍처를 지정해요.
| Value | |
|---|---|
| Input Type | System.String |
| Accepted Values | None, MSIL, X86, IA64, Amd64, Arm |
| Required | No |
| Value if unset | None |
| Accepts wildcards | No |
이 항목의 값은 Import-Module을 실행했을 때 System.Reflection.ProcessorArchitecture로 변환될 수 있어야 해요.
예를 들어, 아래 매니페스트는 시스템의 프로세서 아키텍처와 관계없이 어떤 세션이든 모듈을 불러올 수 있다고 선언해요.
@{
# ProcessorArchitecture = ''
}
ProcessorArchitecture를 Amd64로 설정하면 아키텍처가 일치하는 머신에서 실행되는 세션에서만 이 모듈을 불러올 수 있어요.
@{
ProcessorArchitecture = 'Amd64'
}
RequiredModules
이 항목은 전역 세션 상태에 반드시 있어야 하는 모듈을 지정해요. 필수 모듈이 전역 세션 상태에 없으면 PowerShell이 그 모듈을 불러와요. 필수 모듈을 쓸 수 없으면 Import-Module 명령이 실패해요.
| Value | |
|---|---|
| Input Type | System.String[], System.Collections.Hashtable[] |
| Required | No |
| Value if unset | $null |
| Accepts wildcards | No |
이 항목의 항목은 모듈 이름, 전체 모듈 사양, 또는 모듈 파일 경로일 수 있어요.
값이 경로면 경로는 정규화된 경로나 상대 경로일 수 있어요.
값이 이름이나 모듈 사양이면 PowerShell은 PSModulePath에서 지정한 모듈을 찾아요.
모듈 사양은 다음 키를 가진 해시 테이블이에요.
ModuleName— 필수. 모듈 이름을 지정해요.GUID— 선택. 모듈의 GUID를 지정해요.- 아래 세 키 중 하나 이상을 지정하는 것도 필수예요.
RequiredVersion키는ModuleVersion이나MaximumVersion키와 함께 쓸 수 없어요.ModuleVersion과MaximumVersion키를 함께 지정하면 모듈의 허용 버전 범위를 정의할 수 있어요. ModuleVersion — 모듈의 허용 가능한 최소 버전을 지정해요. RequiredVersion — 모듈의 정확하고 필수인 버전을 지정해요. MaximumVersion — 모듈의 허용 가능한 최대 버전을 지정해요.
참고
RequiredVersion은 Windows PowerShell 5.0에서 추가됐어요. MaximumVersion은 Windows PowerShell 5.1에서 추가됐어요.
예를 들어, 아래 매니페스트는 기능에 다른 모듈이 필요 없다고 선언해요.
@{
# RequiredModules = @()
}
아래 매니페스트는 PSReadLine 모듈이 필요하다고 선언해요. 이 매니페스트에 Import-Module을 실행하면 PowerShell이 세션에서 사용할 수 있는 최신 버전의 PSReadLine을 불러와요. 사용할 수 있는 버전이 없으면 불러오기는 오류를 반환해요.
@{
RequiredModules = @(
'PSReadLine'
)
}
팁
PowerShell 2.0에서는 Import-Module이 필수 모듈을 자동으로 불러오지 않아요. 필수 모듈이 전역 세션 상태에 있는지만 확인해요.
아래 매니페스트는 자체 모듈 폴더에 벤더링된 버전의 PSReadLine 모듈이 필요하다고 선언해요. 이 매니페스트에 Import-Module을 실행하면 PowerShell이 지정된 경로에서 벤더링된 PSReadLine을 불러와요.
@{
RequiredModules = @(
'Vendored\PSReadLine\PSReadLine.psd1'
)
}
아래 매니페스트는 PSReadLine 모듈의 2.0.0 버전을 구체적으로 요구한다고 선언해요. 이 매니페스트에 Import-Module을 실행하면 사용할 수 있다면 PSReadLine 2.0.0 버전을 불러와요. 사용할 수 없으면 Import-Module이 오류를 반환해요.
@{
RequiredModules = @(
@{
ModuleName = 'PSReadLine'
RequiredVersion = '2.0.0'
}
)
}
아래 매니페스트는 PSReadLine 모듈이 2.0.0 버전 이상으로 불러와져야 한다고 선언해요.
@{
RequiredModules = @(
@{
ModuleName = 'PSReadLine'
ModuleVersion = '2.0.0'
}
)
}
아래 매니페스트는 PSReadLine 모듈이 2.0.0 버전 이하로 불러와져야 한다고 선언해요.
@{
RequiredModules = @(
@{
ModuleName = 'PSReadLine'
MaximumVersion = '2.0.0'
}
)
}
아래 매니페스트는 PSDesiredStateConfiguration 모듈이 2.0.0 이상, 2.99.99 이하의 버전으로 불러와져야 한다고 선언해요.
@{
RequiredModules = @(
@{
ModuleName = 'PSDesiredStateConfiguration'
ModuleVersion = '2.0.0'
MaximumVersion = '2.99.99'
}
)
}
RequiredAssemblies
이 항목은 모듈이 요구하는 어셈블리(.dll) 파일을 지정해요. PowerShell은 형식이나 서식을 업데이트하고, 중첩 모듈을 불러오고, RootModule 키 값에 지정된 모듈 파일을 불러오기 전에 지정된 어셈블리를 먼저 불러와요.
| Value | |
|---|---|
| Input Type | System.String[] |
| Required | No |
| Value if unset | $null |
| Accepts wildcards | No |
이 항목의 항목은 어셈블리의 파일 이름이나 경로일 수 있어요. NestedModules 항목에서 이진 모듈로도 나열되어 있어도 필수 어셈블리를 모두 나열하세요.
아래 매니페스트는 example.dll 어셈블리를 요구해요. 이 매니페스트에 지정된 서식이나 형식 파일을 불러오기 전에, 모듈 매니페스트와 같은 디렉터리의 Assemblies 폴더에서 example.dll을 불러와요.
@{
RequiredAssemblies = @(
'Assemblies\Example.dll'
)
}
ScriptsToProcess
이 항목은 모듈이 불러와질 때 호출자의 세션 상태에서 실행되는 스크립트(.ps1) 파일을 지정해요. 이 스크립트들은 로그인 스크립트처럼 환경을 준비하는 데 쓸 수 있어요.
| Value | |
|---|---|
| Input Type | System.String[] |
| Required | No |
| Value if unset | $null |
| Accepts wildcards | No |
모듈의 세션 상태에서 실행되는 스크립트를 지정하려면 NestedModules 키를 사용하세요.
아래 매니페스트를 불러오면 PowerShell이 현재 세션에서 Initialize.ps1을 실행해요.
@{
ScriptsToProcess = @(
'Scripts\Initialize.ps1'
)
}
예를 들어, Initialize.ps1이 정보 메시지를 쓰고 $ExampleState 변수를 설정한다고 해볼게요.
if ([string]::IsNullOrEmpty($ExampleState)) {
Write-Information "Example not initialized."
Write-Information "Initializing now..."
$ExampleState = 'Initialized'
} else {
Write-Information "Example already initialized."
}
모듈을 불러오면 스크립트가 실행되고, 그 메시지들을 쓰고 세션에 $ExampleState를 설정해요.
$InformationPreference = 'Continue'
"Example State is: $ExampleState"
Import-Module .\example7x.psd1
"Example State is: $ExampleState"
Import-Module .\example7x.psd1 -Force
Example State is:
Example not initialized.
Initializing now...
Example State is: Initialized
Example already initialized.
참고
ScriptsToProcess 키는 모듈이 Constrained Language 모드에서 실행될 때 지원되지 않아요. 그 모드에서 모듈을 불러오면 나열된 스크립트가 실행될 수 없어요.
TypesToProcess
이 항목은 모듈이 불러와질 때 실행되는 형식 파일(.ps1xml)을 지정해요.
| Value | |
|---|---|
| Input Type | System.String[] |
| Required | No |
| Value if unset | $null |
| Accepts wildcards | No |
모듈을 불러오면 PowerShell이 지정된 파일과 함께 Update-TypeData cmdlet을 실행해요. 형식 파일은 범위가 지정되지 않기 때문에 세션의 모든 세션 상태에 영향을 줘요.
형식 파일에 대한 자세한 내용은 about_Types.ps1xml 문서를 참고하세요.
예를 들어, 아래 매니페스트를 불러오면 모듈 매니페스트와 같은 디렉터리의 Types 폴더에 있는 Example.ps1xml 파일에 지정된 형식을 PowerShell이 불러와요.
@{
TypesToProcess = @(
'Types\Example.ps1xml'
)
}
FormatsToProcess
이 항목은 모듈이 불러와질 때 실행되는 서식 파일(.ps1xml)을 지정해요.
| Value | |
|---|---|
| Input Type | System.String[] |
| Required | No |
| Value if unset | $null |
| Accepts wildcards | No |
모듈을 불러오면 PowerShell이 지정된 파일과 함께 Update-FormatData cmdlet을 실행해요. 서식 파일은 범위가 지정되지 않기 때문에 세션의 모든 세션 상태에 영향을 줘요.
형식 파일에 대한 자세한 내용은 about_Format.ps1xml 문서를 참고하세요.
예를 들어, 아래 모듈을 불러오면 모듈 매니페스트와 같은 디렉터리의 Formats 폴더에 있는 Example.ps1xml 파일에 지정된 서식을 PowerShell이 불러와요.
@{
FormatsToProcess = @(
'Formats\Example.ps1xml'
)
}
NestedModules
이 항목은 모듈의 세션 상태로 불러와지는 스크립트 모듈(.psm1)과 이진 모듈(.dll)을 지정해요. 스크립트 파일(.ps1)도 지정할 수 있어요. 이 항목의 파일들은 나열된 순서대로 실행돼요.
| Value | |
|---|---|
| Input Type | System.String[], System.Collections.Hashtable[] |
| Required | No |
| Value if unset | $null |
| Accepts wildcards | No |
이 항목의 항목은 모듈 이름, 전체 모듈 사양, 또는 모듈이나 스크립트 파일 경로일 수 있어요. 값이 경로면 경로는 정규화된 경로나 상대 경로일 수 있어요.
참고
.ps1 파일로 지정된 모듈은 모듈이 Constrained Language 모드에서 실행될 때 지원되지 않아요. 그 모드에서 모듈을 불러오면 나열된 파일들이 실행될 수 없어요.
값이 모듈 이름이나 사양이면 PowerShell은 PSModulePath에서 지정한 모듈을 찾아요.
모듈 사양은 다음 키를 가진 해시 테이블이에요.
ModuleName— 필수. 모듈 이름을 지정해요.GUID— 선택. 모듈의 GUID를 지정해요.- 아래 세 키 중 하나 이상을 지정하는 것도 필수예요.
RequiredVersion키는ModuleVersion이나MaximumVersion키와 함께 쓸 수 없어요.ModuleVersion과MaximumVersion키를 함께 지정하면 모듈의 허용 버전 범위를 정의할 수 있어요. ModuleVersion — 모듈의 허용 가능한 최소 버전을 지정해요. RequiredVersion — 모듈의 정확하고 필수인 버전을 지정해요(Windows PowerShell 5.0에서 추가). MaximumVersion — 모듈의 허용 가능한 최대 버전을 지정해요(Windows PowerShell 5.1에서 추가).
중첩 모듈에서 내보내야 하는 항목은 중첩 모듈이 Export-ModuleMember cmdlet으로 내보내거나, 내보내기 속성 중 하나에 나열되어야 해요.
- FunctionsToExport
- CmdletsToExport
- VariablesToExport
- AliasesToExport
모듈 세션 상태의 중첩 모듈은 루트 모듈에서 사용할 수 있지만, 호출자의 세션 상태에서 Get-Module 명령으로는 반환되지 않아요.
이 항목에 나열된 스크립트(.ps1)는 호출자의 세션 상태가 아니라 모듈의 세션 상태에서 실행돼요. 호출자의 세션 상태에서 스크립트를 실행하려면 스크립트 파일 이름을 ScriptsToProcess 항목에 나열하세요.
예를 들어, 아래 매니페스트를 불러오면 Helpers.psm1 모듈이 루트 모듈의 세션 상태로 불러와져요. 중첩 모듈에 선언된 cmdlet들은 특별히 제한하지 않는 한 내보내져요.
@{
NestedModules = @(
'Helpers\Helpers.psm1'
)
}
FunctionsToExport
이 항목은 모듈이 내보내는 함수를 지정해요. 이 항목을 사용해 모듈이 내보내는 함수를 제한할 수 있어요. 이 항목은 내보낸 함수 목록에서 함수를 제거할 수는 있지만, 목록에 함수를 추가할 수는 없어요.
| Value | |
|---|---|
| Input Type | System.String[] |
| Required | No |
| Value if unset | $null |
| Accepts wildcards | Yes |
이 항목의 항목은 와일드카드로 지정할 수 있어요. 내보낸 함수 목록에서 일치하는 모든 함수가 내보내져요.
팁
성능과 검색 가능성을 위해, 이 항목에는 와일드카드를 쓰지 말고 모듈이 내보내길 원하는 함수를 항상 명시적으로 나열하는 게 좋아요.
예를 들어, 항목이 주석 처리된 모듈을 불러오면 루트 모듈과 모든 중첩 모듈의 모든 함수가 내보내져요.
@{
# FunctionsToExport = @()
}
아래 매니페스트는 항목을 전혀 지정하지 않은 것과 기능적으로 동일해요.
@{
FunctionsToExport = '*'
}
FunctionsToExport를 빈 배열로 설정하면, 모듈을 불러와도 루트 모듈이나 중첩 모듈이 내보내는 함수가 하나도 사용 가능하지 않아요.
@{
FunctionsToExport = @()
}
참고
New-ModuleManifest 명령으로 모듈 매니페스트를 만들 때 FunctionsToExport 매개 변수를 지정하지 않으면, 만들어진 매니페스트는 이 항목을 빈 배열로 지정해요. 매니페스트를 직접 편집하지 않는 한 모듈의 어떤 함수도 내보내지지 않아요.
FunctionsToExport를 Get-Example 함수만 포함하도록 설정하면, 루트 모듈이나 중첩 모듈이 다른 함수를 내보냈어도 모듈을 불러오면 Get-Example 함수만 사용할 수 있어요.
@{
FunctionsToExport = @(
'Get-Example'
)
}
FunctionsToExport를 와일드카드 문자열로 설정하면, 루트 모듈이나 중첩 모듈이 다른 함수를 모듈 멤버로 내보냈어도 이름이 Example로 끝나는 함수는 모듈을 불러오면 사용할 수 있어요.
@{
FunctionsToExport = @(
'*Example'
)
}
CmdletsToExport
이 항목은 모듈이 내보내는 cmdlet을 지정해요. 이 항목을 사용해 모듈이 내보내는 cmdlet을 제한할 수 있어요. 이 항목은 내보낸 모듈 멤버 목록에서 cmdlet을 제거할 수는 있지만, 목록에 cmdlet을 추가할 수는 없어요.
| Value | |
|---|---|
| Input Type | System.String[] |
| Required | No |
| Value if unset | $null |
| Accepts wildcards | Yes |
이 항목의 항목은 와일드카드로 지정할 수 있어요. 내보낸 cmdlet 목록에서 일치하는 모든 cmdlet이 내보내져요.
팁
성능과 검색 가능성을 위해, 이 항목에는 와일드카드를 쓰지 말고 모듈이 내보내길 원하는 cmdlet을 항상 명시적으로 나열하는 게 좋아요.
예를 들어, 항목이 주석 처리된 모듈을 불러오면 루트 모듈과 모든 중첩 모듈의 모든 cmdlet이 내보내져요.
@{
# CmdletsToExport = @()
}
아래 매니페스트는 항목을 전혀 지정하지 않은 것과 기능적으로 동일해요.
@{
CmdletsToExport = '*'
}
CmdletsToExport를 빈 배열로 설정하면, 모듈을 불러와도 루트 모듈이나 중첩 모듈이 내보내는 cmdlet이 하나도 사용 가능하지 않아요.
@{
CmdletsToExport = @()
}
참고
New-ModuleManifest 명령으로 모듈 매니페스트를 만들 때 CmdletsToExport 매개 변수를 지정하지 않으면, 만들어진 매니페스트는 이 항목을 빈 배열로 지정해요. 매니페스트를 직접 편집하지 않는 한 모듈의 어떤 cmdlet도 내보내지지 않아요.
CmdletsToExport를 Get-Example cmdlet만 포함하도록 설정하면, 루트 모듈이나 중첩 모듈이 다른 cmdlet을 내보냈어도 모듈을 불러오면 Get-Example cmdlet만 사용할 수 있어요.
@{
CmdletsToExport = @(
'Get-Example'
)
}
CmdletsToExport를 와일드카드 문자열로 설정하면, 루트 모듈이나 중첩 모듈이 다른 cmdlet을 모듈 멤버로 내보냈어도 이름이 Example로 끝나는 cmdlet은 모듈을 불러오면 사용할 수 있어요.
@{
CmdletsToExport = @(
'*Example'
)
}
VariablesToExport
이 항목은 모듈이 내보내는 변수를 지정해요. 이 항목을 사용해 모듈이 내보내는 변수를 제한할 수 있어요. 이 항목은 내보낸 모듈 멤버 목록에서 변수를 제거할 수는 있지만, 목록에 변수를 추가할 수는 없어요.
| Value | |
|---|---|
| Input Type | System.String[] |
| Required | No |
| Value if unset | $null |
| Accepts wildcards | Yes |
이 항목의 항목은 와일드카드로 지정할 수 있어요. 내보낸 모듈 멤버 목록에서 일치하는 모든 변수가 내보내져요.
팁
성능과 검색 가능성을 위해, 이 항목에는 와일드카드를 쓰지 말고 모듈이 내보내길 원하는 변수를 항상 명시적으로 나열하는 게 좋아요.
예를 들어, 항목이 주석 처리된 모듈을 불러오면 루트 모듈과 모든 중첩 모듈의 모든 변수가 내보내져요.
@{
# VariablesToExport = @()
}
아래 매니페스트는 항목을 전혀 지정하지 않은 것과 기능적으로 동일해요.
@{
VariablesToExport = '*'
}
참고
New-ModuleManifest 명령으로 모듈 매니페스트를 만들 때 VariablesToExport 매개 변수를 지정하지 않으면, 만들어진 매니페스트는 이 항목을 '*'로 지정해요. 매니페스트를 직접 편집하지 않는 한 모듈의 모든 변수가 내보내져요.
VariablesToExport를 빈 배열로 설정하면, 모듈을 불러와도 루트 모듈이나 중첩 모듈이 내보내는 변수가 하나도 사용 가능하지 않아요.
@{
VariablesToExport = @()
}
VariablesToExport를 SomeExample 변수만 포함하도록 설정하면, 루트 모듈이나 중첩 모듈이 다른 변수를 내보냈어도 모듈을 불러오면 $SomeExample 변수만 사용할 수 있어요.
@{
VariablesToExport = @(
'SomeExample'
)
}
VariablesToExport를 와일드카드 문자열로 설정하면, 루트 모듈이나 중첩 모듈이 다른 변수를 모듈 멤버로 내보냈어도 이름이 Example로 끝나는 변수는 모듈을 불러오면 사용할 수 있어요.
@{
VariablesToExport = @(
'*Example'
)
}
DscResourcesToExport
이 항목은 모듈이 내보내는 DSC 리소스를 지정해요. 이 항목을 사용해 모듈이 내보내는 클래스 기반 DSC 리소스를 제한할 수 있어요. 이 항목은 내보낸 모듈 멤버 목록에서 DSC 리소스를 제거할 수는 있지만, 목록에 DSC 리소스를 추가할 수는 없어요.
| Value | |
|---|---|
| Input Type | System.String[] |
| Required | No |
| Value if unset | $null |
| Accepts wildcards | Yes |
이 항목의 항목은 와일드카드로 지정할 수 있어요. 모듈에서 일치하는 모든 클래스 기반 DSC 리소스가 내보내져요.
팁
검색 가능성을 위해, 모듈이 내보내는 모든 DSC 리소스를 항상 명시적으로 나열하는 게 좋아요.
DSC 리소스 작성과 사용에 대한 자세한 내용은 documentation for DSC 문서를 참고하세요.
아래 매니페스트는 루트 모듈과 모든 중첩 모듈에 정의된 클래스 기반과 MOF 기반 DSC 리소스를 모두 내보내요.
@{
# DscResourcesToExport = @()
}
아래 매니페스트는 루트 모듈과 모든 중첩 모듈에 정의된 MOF 기반 DSC 리소스를 모두 내보내지만, 클래스 기반 DSC 리소스는 ExampleClassResource 하나만 내보내요.
@{
DscResourcesToExport = @(
'ExampleClassResource'
)
}
아래 매니페스트는 포함된 모든 DSC 리소스를 내보내요. MOF 기반 리소스가 나열되지 않았어도 모듈은 그 리소스를 여전히 내보내요.
@{
DscResourcesToExport = @(
'ExampleClassResource'
'ExampleMofResourceFirst'
)
}
ModuleList
이 항목은 이 모듈에 포함된 모듈들의 정보용 목록이에요. 이 목록은 모듈의 동작에 영향을 주지 않아요.
| Value | |
|---|---|
| Input Type | System.String[], System.Collections.Hashtable[] |
| Required | No |
| Value if unset | $null |
| Accepts wildcards | No |
이 항목의 항목은 모듈 이름, 전체 모듈 사양, 또는 모듈이나 스크립트 파일 경로일 수 있어요.
값이 경로면 경로는 정규화된 경로나 상대 경로일 수 있어요.
값이 모듈 이름이나 사양이면 PowerShell은 PSModulePath에서 지정한 모듈을 찾아요.
모듈 사양은 다음 키를 가진 해시 테이블이에요.
ModuleName— 필수. 모듈 이름을 지정해요.GUID— 선택. 모듈의 GUID를 지정해요.- 아래 세 키 중 하나 이상을 지정하는 것도 필수예요.
RequiredVersion키는ModuleVersion이나MaximumVersion키와 함께 쓸 수 없어요.ModuleVersion과MaximumVersion키를 함께 지정하면 모듈의 허용 버전 범위를 정의할 수 있어요. ModuleVersion — 모듈의 허용 가능한 최소 버전을 지정해요. RequiredVersion — 모듈의 정확하고 필수인 버전을 지정해요. MaximumVersion — 모듈의 허용 가능한 최대 버전을 지정해요.
참고
RequiredVersion은 Windows PowerShell 5.0에서 추가됐어요. MaximumVersion은 Windows PowerShell 5.1에서 추가됐어요.
아래 매니페스트는 포함된 모듈들의 정보용 목록을 제공하지 않아요. 모듈이 있을 수도 있고 없을 수도 있어요. 이 항목을 지정하지 않아도, RootModule, ScriptsToProcess, NestedModules 항목에 나열된 모듈들은 여전히 정상적으로 동작해요.
@{
# ModuleList = @()
}
아래 매니페스트는 포함된 유일한 모듈이 Example.psm1이고, Submodules 폴더의 하위 모듈 First.psm1과 Second.psm1이라고 선언해요.
@{
ModuleList = @(
'Example.psm1'
'Submodules\First.psm1'
'Submodules\Second.psm1'
)
}
FileList
이 항목은 이 모듈에 포함된 파일들의 정보용 목록이에요. 이 목록은 모듈의 동작에 영향을 주지 않아요.
| Value | |
|---|---|
| Input Type | System.String[] |
| Required | No |
| Value if unset | $null |
| Accepts wildcards | Yes |
이 항목의 항목은 모듈 매니페스트가 들어 있는 폴더에서 파일까지의 상대 경로여야 해요.
사용자가 이 항목이 정의된 매니페스트에 Get-Module을 호출하면, FileList 속성은 모듈 경로와 각 항목의 상대 경로를 합친 이 파일들의 전체 경로를 포함해요.
아래 매니페스트는 파일 목록을 포함하지 않아요.
@{
# FileList = @()
}
아래 매니페스트는 포함된 유일한 파일이 이 항목에 나열된 것들이라고 선언해요.
@{
FileList = @(
'Example.psd1'
'Example.psm1'
'Assemblies\Example.dll'
'Scripts\Initialize.ps1'
'Submodules\First.psm1'
'Submodules\Second.psm1'
)
}
PrivateData
이 항목은 루트 모듈의 범위에 있는 어떤 명령이나 함수에서도 사용할 수 있는 데이터의 해시 테이블을 정의해요.
| Value | |
|---|---|
| Input Type | System.Collections.Hashtable |
| Required | PowerShell Gallery, Crescendo |
| Value if unset | $null |
| Accepts wildcards | No |
Crescendo 매니페스트를 내보내 새 모듈을 만들면, Export-CrescendoModule이 PrivateData에 두 개의 키를 추가해요.
- CrescendoGenerated — 모듈이 내보내진 타임스탬프
- CrescendoVersion — 모듈을 내보내는 데 사용된 Crescendo의 버전
추적하고 싶은 메타데이터를 담을 자신만의 키도 추가할 수 있어요. 이 항목에 추가된 키는 루트 모듈의 함수와 cmdlet에서 $MyInvocation.MyCommand.Module.PrivateData로 사용할 수 있어요. 이 해시 테이블은 모듈 범위 자체에는 없고, 모듈에서 정의한 cmdlet에서만 사용할 수 있어요.
예를 들어, 아래 매니페스트는 PrivateData에 PublishedDate 키를 정의해요.
@{
PrivateData = @{
PublishedDate = '2022-06-01'
}
}
모듈의 cmdlet은 $MyInvocation 변수로 이 값에 접근할 수 있어요.
function Get-Stale {
[CmdletBinding()]
param()
$PublishedDate = $MyInvocation.MyCommand.Module.PrivateData.PublishedDate
$CurrentDate = Get-Date
try {
$PublishedDate = Get-Date -Date $PublishedDate -ErrorAction Stop
} catch {
# The date was set in the manifest, set to an invalid value, or
# the script module was directly imported without the manifest.
throw "Unable to determine published date. Check the module manifest."
}
if ($CurrentDate -gt $PublishedDate.AddDays(30)) {
Write-Warning "This module version was published more than 30 days ago."
} else {
$TimeUntilStale = $PublishedDate.AddDays(30) - $CurrentDate
"This module will be stale in $($TimeUntilStale.Days) days"
}
}
모듈이 불러와지면 이 함수는 PrivateData의 값을 사용해 모듈이 언제 게시됐는지 판단해요.
Get-Stale -TestDate '2022-06-15'
Get-Stale -TestDate '2022-08-01'
This module will be stale in 16 days
WARNING: This module version was published more than 30 days ago.
PrivateData.PSData
PSData 하위 속성은 특정 확장 시나리오를 지원하는 값들의 해시 테이블을 정의해요.
| Value | |
|---|---|
| Input Type | System.Collections.Hashtable |
| Required | PowerShell Gallery, Experimental features, Crescendo modules |
| Value if unset | $null |
| Accepts wildcards | No |
PSData 하위 속성은 다음 시나리오에서 사용돼요.
- PowerShell Gallery —
New-ModuleManifest로 모듈 매니페스트를 만들면 cmdlet이 모듈을 PowerShell Gallery에 게시할 때 필요한 자리 표시자 키로 PSData 해시 테이블을 미리 채워요. 모듈 매니페스트와 PowerShell Gallery 게시에 대한 자세한 내용은 Package manifest values that impact the PowerShell Gallery UI 문서를 참고하세요. - 실험적 기능 — 실험적 기능에 대한 메타데이터는 PSData의
ExperimentalFeatures속성에 보관돼요.ExperimentalFeatures속성은 기능의 이름과 설명을 담은 해시 테이블들의 배열이에요. 자세한 내용은 Declaring experimental features in modules 문서를 참고하세요. - Crescendo 모듈 — Crescendo 매니페스트를 내보내 새 모듈을 만들면
Export-CrescendoModule이 PSData.Tags 속성에CrescendoBuilt값을 추가해요. 이 태그로 PowerShell Gallery에서 Crescendo로 만들어진 모듈을 찾을 수 있어요. 자세한 내용은 Export-CrescendoModule 문서를 참고하세요. - PSData.ExternalModuleDependencies 속성은 이 모듈의 종속성인 모듈 이름들의 배열이에요. 이 속성은 정보용일 뿐 모듈 설치나 불러오기에 영향을 주지 않아요.
HelpInfoURI
이 항목은 모듈의 HelpInfo XML 파일 인터넷 주소를 지정해요.
| Value | |
|---|---|
| Input Type | System.String |
| Required | No |
| Value if unset | $null |
| Accepts wildcards | No |
이 항목의 값은 http나 https로 시작하는 URI(Uniform Resource Identifier)여야 해요.
HelpInfo XML 파일은 PowerShell 3.0에서 도입된 Updatable Help 기능을 지원해요. 이 파일은 모듈의 다운로드 가능한 도움말 파일 위치와 지원되는 각 로캘의 최신 도움말 파일 버전 번호에 대한 정보를 담고 있어요.
Updatable Help에 대한 자세한 내용은 about_Updatable_Help 문서를 참고하세요. HelpInfo XML 파일에 대한 자세한 내용은 Supporting Updatable Help 문서를 참고하세요.
예를 들어, 아래 모듈은 업데이트 가능한 도움말을 지원해요.
@{
HelpInfoUri = 'http://https://go.microsoft.com/fwlink/?LinkID=603'
}
DefaultCommandPrefix
이 항목은 모듈의 모든 명령이 세션으로 불러와질 때 명령 이름의 명사 앞에 붙는 접두사를 지정해요. 접두사는 사용자 세션에서 명령 이름 충돌을 막는 데 도움을 줘요.
| Value | |
|---|---|
| Input Type | System.String |
| Required | No |
| Value if unset | $null |
| Accepts wildcards | No |
모듈 사용자는 Import-Module cmdlet의 Prefix 매개 변수로 이 접두사를 재정의할 수 있어요.
이 항목은 PowerShell 3.0에서 도입됐어요.
아래 매니페스트가 불러와지면 이 모듈에서 불러오는 cmdlet은 이름의 명사 앞에 Example이 붙어요. 예를 들어 Get-Item은 Get-ExampleItem으로 불러와져요.
@{
DefaultCommandPrefix = 'Example'
}