PowerShellGallery 게시 지침 및 모범 사례

아티클
06/26/2024

이 문서에서는 PowerShell 갤러리에 게시된 패키지가 널리 채택되고 PowerShell 갤러리가 매니페스트 데이터를 처리하는 방법과 많은 PowerShell 갤러리 사용자의 피드백에 따라 사용자에게 높은 가치를 제공하도록 Microsoft 팀에서 사용하는 권장 단계를 설명합니다. 이러한 지침에 따라 게시된 패키지는 설치, 신뢰할 수 있으며 더 많은 사용자를 유치할 가능성이 높습니다.

아래에는 유용한 PowerShell 갤러리 패키지를 만드는 방법, 가장 중요한 선택적 매니페스트 설정에 대한 지침이 포함되어 있으며, 초기 검토자 및 Powershell Script Analyzer피드백을 사용하여 코드를 개선하고, 모듈, 설명서, 테스트 및 공유한 항목을 사용하는 방법에 대한 예제를 버전 관리합니다. 이 설명서의 대부분은 고품질 DSC 리소스 모듈게시하기 위한 지침을 따릅니다.

PowerShell 갤러리에 패키지를 게시하는 메커니즘은 패키지 만들기 및 게시참조하세요.

이러한 지침에 대한 피드백은 환영합니다. 피드백이 있는 경우 GitHub 설명서 리포지토리문제를 여세요.

패키지 게시 모범 사례

다음 모범 사례는 PowerShell 갤러리 항목의 사용자가 중요하다고 말하는 것이며 명목상 우선 순위 순서로 나열됩니다. 이러한 지침을 따르는 패키지는 다른 사용자가 다운로드하고 채택할 가능성이 훨씬 높습니다.

PSScriptAnalyzer 사용
설명서 및 예제 포함
피드백에 응답
스크립트가 아닌 모듈 제공
프로젝트 사이트에 대한 링크 제공
호환되는 PSEdition 및 플랫폼을 사용하여 패키지에 태그 지정
모듈에 테스트 포함
사용 조건 포함 및/또는 링크
코드 서명
버전 관리 SemVer 지침을 따릅니다.
공통 PowerShell 갤러리 태그에 설명된 대로 일반 태그 사용
로컬 리포지토리를 사용하여 게시 테스트
PowerShellGet을 사용하여 게시

이러한 각 항목은 아래 섹션에서 간략하게 설명합니다.

PSScriptAnalyzer 사용

PSScriptAnalyzer PowerShell 코드에서 작동하는 무료 정적 코드 분석 도구입니다. PSScriptAnalyzer PowerShell 코드에 표시되는 가장 일반적인 문제와 문제를 해결하는 방법에 대한 권장 사항을 식별합니다. 이 도구는 사용하기 쉽고 문제를 오류(심각하고 해결해야 합니다), 경고(검토해야 하며 해결해야 합니다) 및 정보(모범 사례에 대해 확인할 가치가 있음)로 분류합니다. PowerShell 갤러리에 게시된 모든 패키지는 PSScriptAnalyzer사용하여 검사되며, 모든 오류는 소유자에게 다시 보고되며 해결해야 합니다.

가장 좋은 방법은 -Recurse 및 -Severity 경고로 Invoke-ScriptAnalyzer 실행하는 것입니다.

결과를 검토하고 다음을 확인합니다.

모든 오류는 설명서에서 수정되거나 해결됩니다.
모든 경고를 검토하고 해당하는 경우 해결합니다.

PowerShell 갤러리에서 패키지를 다운로드하는 사용자는 PSScriptAnalyzer 실행하고 모든 오류 및 경고를 평가하는 것이 좋습니다. PSScriptAnalyzer보고한 오류가 표시되는 경우 사용자는 패키지 소유자에게 문의할 가능성이 매우 높습니다. 패키지에서 오류로 플래그가 지정된 코드를 유지해야 하는 강력한 이유가 있는 경우 동일한 질문에 여러 번 답변할 필요가 없도록 설명서에 해당 정보를 추가합니다.

설명서 및 예제 포함

설명서 및 예제는 사용자가 공유 코드를 활용할 수 있도록 하는 가장 좋은 방법입니다.

설명서는 PowerShell 갤러리에 게시된 패키지에 포함할 때 가장 유용합니다. 사용자는 일반적으로 설명서 없이 패키지를 무시합니다. 대안은 패키지의 내용과 사용 방법을 이해하기 위해 코드를 읽는 것입니다. PowerShell 패키지와 함께 설명서를 제공하는 방법에 대한 몇 가지 문서가 있습니다. 다음을 포함합니다.

도움말을 제공하는 지침은 cmdlet 도움말작성하는 방법에 있습니다.
PowerShell 스크립트, 함수 또는 cmdlet에 가장 적합한 방법인 cmdlet 도움말을 만듭니다. cmdlet 도움말을 만드는 방법에 대한 자세한 내용은 Cmdlet 도움말작성하는 방법부터 시작하세요. 스크립트 내에 도움말을 추가하려면 주석 기반 도움말참조하세요.
많은 모듈에는 MarkDown 파일과 같은 텍스트 형식의 설명서도 포함되어 있습니다. 이는 Markdown이 많이 사용되는 형식인 GitHub에 프로젝트 사이트가 있는 경우 특히 유용할 수 있습니다. GitHub 버전 Markdown사용하는 것이 가장 좋습니다.

예제에서는 패키지를 사용하는 방법을 사용자에게 보여 줍니다. 많은 개발자는 설명서 앞의 예제를 살펴보고 어떤 것을 사용하는 방법을 이해한다고 말합니다. 가장 좋은 유형의 예제는 기본 사용과 시뮬레이션된 실제 사용 사례를 보여 줍니다. 코드는 주석 처리가 잘 됩니다. PowerShell 갤러리에 게시된 모듈의 예는 모듈 루트 아래의 Examples 폴더에 있어야 합니다.

예제에 대한 좋은 패턴은 PSDscResource 모듈Examples\RegistryResource 폴더에서 찾을 수 있습니다. 각 파일의 맨 위에 설명된 내용을 문서화하는 간단한 설명이 있는 네 가지 샘플 사용 사례가 있습니다.

종속성 관리

모듈 매니페스트에서 모듈이 종속되는 모듈을 지정하는 것이 중요합니다. 이렇게 하면 최종 사용자가 종속성을 사용하는 적절한 버전의 모듈을 설치하는 것에 대해 걱정할 필요가 없습니다. 종속 모듈을 지정하려면 모듈 매니페스트에서 필요한 모듈 필드를 사용해야 합니다. 이미 로드되지 않은 경우 모듈을 가져오기 전에 나열된 모든 모듈을 전역 환경으로 로드합니다. 예를 들어 일부 모듈은 이미 다른 모듈에 의해 로드될 수 있습니다. ModuleVersion 필드가 아닌 RequiredVersion 필드를 사용하여 로드할 특정 버전을 지정할 수도 있습니다. ModuleVersion사용하는 경우 지정된 최소 버전으로 사용 가능한 최신 버전을 로드합니다. RequiredVersion 필드를 사용하지 않는 경우 특정 버전을 지정하려면 필요한 모듈에 대한 버전 업데이트를 모니터링하는 것이 중요합니다. 모듈을 사용하는 사용자 환경에 영향을 줄 수 있는 주요 변경 내용을 인식하는 것이 특히 중요합니다.

Example: RequiredModules = @(@{ModuleName="myDependentModule"; ModuleVersion="2.0"; Guid="cfc45206-1e49-459d-a8ad-5b571ef94857"})

Example: RequiredModules = @(@{ModuleName="myDependentModule"; RequiredVersion="1.5"; Guid="cfc45206-1e49-459d-a8ad-5b571ef94857"})

피드백에 응답

피드백에 적절하게 응답하는 패키지 소유자는 커뮤니티에서 높은 평가를 받고 있습니다. 건설적인 피드백을 제공하는 사용자는 패키지 개선에 충분히 관심이 있으므로 응답하는 것이 중요합니다.

PowerShell 갤러리에서 사용할 수 있는 피드백 방법은 다음과 같습니다.

연락처 소유자: 이렇게 하면 사용자가 패키지 소유자에게 전자 메일을 보낼 수 있습니다. 패키지 소유자는 PowerShell 갤러리 패키지와 함께 사용되는 이메일 주소를 모니터링하고 발생한 문제에 대응하는 것이 중요합니다. 이 방법의 한 가지 단점은 사용자와 소유자만 통신을 볼 수 있으므로 소유자가 동일한 질문에 여러 번 대답해야 할 수 있다는 것입니다.

피드백에 건설적으로 응답하는 소유자는 커뮤니티에 감사드립니다. 보고서의 기회를 사용하여 자세한 정보를 요청합니다. 필요한 경우 해결 방법을 제공하거나 업데이트에서 문제를 해결하는지 식별합니다.

이러한 통신 채널 중 하나에서 부적절한 동작이 관찰된 경우 PowerShell 갤러리의 보고서 남용 기능을 사용하여 갤러리 관리자에게 문의하세요.

모듈 및 스크립트

스크립트를 다른 사용자와 공유하는 것이 좋으며 다른 사용자에게 발생할 수 있는 문제를 해결하는 방법의 예를 제공합니다. 문제는 PowerShell 갤러리의 스크립트가 별도의 설명서, 예제 및 테스트가 없는 단일 파일이라는 것입니다.

PowerShell 모듈에는 여러 폴더와 파일을 패키지에 포함할 수 있는 폴더 구조가 있습니다. 모듈 구조를 사용하면 cmdlet 도움말, 설명서, 예제 및 테스트와 같은 모범 사례로 나열하는 다른 패키지를 포함할 수 있습니다. 가장 큰 단점은 모듈 내의 스크립트를 노출하고 함수로 사용해야 한다는 것입니다. 모듈을 만드는 방법에 대한 자세한 내용은 Windows PowerShell 모듈작성을 참조하세요.

스크립트가 특히 DSC 구성을 사용하여 사용자에게 더 나은 환경을 제공하는 상황이 있습니다. DSC 구성의 모범 사례는 문서, 예제 및 테스트를 포함하는 함께 제공되는 모듈을 사용하여 구성을 스크립트로 게시하는 것입니다. 스크립트는 RequiredModules = @(Name of the Module)사용하여 함께 제공되는 모듈을 나열합니다. 이 방법은 모든 스크립트와 함께 사용할 수 있습니다.

다른 모범 사례를 따르는 독립 실행형 스크립트는 다른 사용자에게 실제 가치를 제공합니다. PowerShell 갤러리에 스크립트를 게시할 때 주석 기반 설명서와 프로젝트 사이트에 대한 링크를 제공하는 것이 좋습니다.

프로젝트 사이트에 대한 링크 제공

프로젝트 사이트는 게시자가 PowerShell 갤러리 패키지의 사용자와 직접 상호 작용할 수 있는 위치입니다. 사용자는 패키지에 대한 정보를 더 쉽게 얻을 수 있으므로 이를 제공하는 패키지를 선호합니다. PowerShell 갤러리의 많은 패키지는 GitHub에서 개발되며, 다른 패키지는 전용 웹이 있는 조직에서 제공합니다. 이러한 각 사이트는 프로젝트 사이트로 간주될 수 있습니다.

링크 추가는 다음과 같이 매니페스트의 PSData 섹션에 ProjectURI를 포함하여 수행됩니다.

  # A URL to the main website for this project.
  ProjectUri = 'https://github.com/powershell/powershell'

ProjectURI가 제공되면 PowerShell 갤러리에는 패키지 페이지의 왼쪽에 있는 프로젝트 사이트에 대한 링크가 포함됩니다.

호환되는 PSEdition 및 플랫폼을 사용하여 패키지에 태그 지정

다음 태그를 사용하여 사용자에게 해당 환경에서 잘 작동하는 패키지를 보여 줍니다.

PSEdition_Desktop: Windows PowerShell과 호환되는 패키지
PSEdition_Core: PowerShell 6 이상과 호환되는 패키지
Windows: Windows 운영 체제와 호환되는 패키지
Linux: Linux 운영 체제와 호환되는 패키지
MacOS: Mac 운영 체제와 호환되는 패키지

호환되는 플랫폼으로 패키지에 태그를 지정하면 검색 결과의 왼쪽 창에 있는 갤러리 검색 필터에 포함됩니다. GitHub에서 패키지를 호스트하는 경우 패키지에 태그를 지정할 때 PowerShell 갤러리 호환성 보호 호환성 보호 예제 활용할 수도 있습니다.

테스트 포함

오픈 소스 코드로 테스트를 포함하는 것은 사용자에게 중요합니다. 이는 유효성 검사에 대한 보증을 제공하고 코드 작동 방식에 대한 정보를 제공하기 때문에 사용자에게 중요합니다. 또한 사용자가 자신의 환경에 맞게 코드를 수정하는 경우 원래 기능을 중단하지 않도록 할 수 있습니다.

PowerShell용으로 특별히 설계된 Pester 테스트 프레임워크를 활용하기 위해 테스트를 작성하는 것이 좋습니다. Pester는 GitHub, PowerShell 갤러리사용할 수 있으며 Windows 10, Windows Server 2016, WMF 5.0 및 WMF 5.1에서 제공됩니다.

GitHub Pester 프로젝트 사이트에는 시작부터 모범 사례에 이르기까지 Pester 테스트 작성에 대한 좋은 설명서가 포함되어 있습니다.

테스트 검사 대상은고품질 리소스 모듈 설명서에서 호출되며, 70개의% 단위 테스트 코드 검사가 권장됩니다.

사용 조건 포함 및/또는 링크

PowerShell 갤러리에 게시된 모든 패키지는 사용 조건을 지정하거나 전시 A따라 사용 약관 포함된 라이선스에 바인딩되어야 합니다. 다른 라이선스를 지정하는 가장 좋은 방법은 PSDataLicenseURI 사용하여 라이선스에 대한 링크를 제공하는 것입니다. 자세한 내용은 패키지 매니페스트 및 갤러리 UI참조하세요.

PrivateData = @{
    PSData = @{

        # Tags applied to this module. These help with module discovery in online galleries.
        Tags = @('.net','acl','active-directory')

        # A URL to the license for this module.
        LicenseUri = 'http://www.apache.org/licenses/LICENSE-2.0'

코드 서명

코드 서명은 패키지를 게시한 사용자에 대해 가장 높은 수준의 보증을 제공하며, 사용자가 획득한 코드의 복사본이 게시자가 릴리스한 것과 정확히 일치합니다. 일반적으로 코드 서명에 대한 자세한 내용은 코드 서명소개를 참조하세요. PowerShell은 다음 두 가지 기본 방법을 통해 코드 서명의 유효성 검사를 지원합니다.

서명 스크립트 파일
모듈 카탈로그 서명

PowerShell 파일 서명은 실행 중인 코드가 신뢰할 수 있는 소스에 의해 생성되고 수정되지 않았는지 확인하는 잘 설정된 접근 방식입니다. PowerShell 스크립트 파일에 서명하는 방법에 대한 자세한 내용은 서명 정보 문서에서 설명합니다. 개요에서 서명은 스크립트가 로드될 때 PowerShell에서 유효성을 검사하는 모든 .PS1 파일에 추가할 수 있습니다. 서명된 스크립트를 사용하도록 실행 정책 cmdlet을 사용하여 PowerShell을 제한할 수 있습니다.

카탈로그 서명 모듈은 버전 5.1에서 PowerShell에 추가된 기능입니다. 모듈에 서명하는 방법은 카탈로그 cmdlet 문서에서 설명합니다. 개요에서 카탈로그 서명은 모듈의 모든 파일에 대한 해시 값을 포함하는 카탈로그 파일을 만든 다음 해당 파일에 서명하여 수행됩니다.

PowerShellGetPublish-Module, Install-Module및 Update-Module cmdlet은 서명이 유효한지 확인한 다음 각 패키지의 해시 값이 카탈로그에 있는 것과 일치하는지 확인합니다. Save-Module 서명의 유효성을 검사하지 않습니다. 이전 버전의 모듈이 시스템에 설치된 경우 Install-Module 새 버전에 대한 서명 기관이 이전에 설치된 것과 일치하는지 확인합니다. Install-Module 및 Update-Module 패키지가 카탈로그 서명되지 않은 경우 .PSD1 파일에서 서명을 사용합니다. 카탈로그 서명은 작동하지만 서명 스크립트 파일은 대체하지 않습니다. PowerShell은 모듈 로드 시 카탈로그 서명의 유효성을 검사하지 않습니다.

버전 관리용 SemVer 지침 따르기

SemVer 변경 내용을 쉽게 해석할 수 있도록 버전을 구성하고 변경하는 방법을 설명하는 공용 규칙입니다. 패키지의 버전은 매니페스트 데이터에 포함되어야 합니다.

버전은 0.1.1 또는 4.11.192같이 마침표로 구분된 세 개의 숫자 블록으로 구성되어야 합니다.
0 시작하는 버전은 패키지가 아직 프로덕션 준비가 되지 않았음을 나타내며, 첫 번째 숫자는 사용된 유일한 숫자인 경우에만 0 시작해야 합니다.
첫 번째 숫자의 변경 내용(2.0.01.9.9999)은 버전 간의 주요 변경 내용과 호환성이 손상되는 변경 내용을 나타냅니다.
두 번째 숫자(1.21.1)를 변경하면 모듈에 새 cmdlet을 추가하는 등의 기능 수준 변경 내용이 표시됩니다.
세 번째 숫자를 변경하면 새 매개 변수, 업데이트된 샘플 또는 새 테스트와 같은 호환되지 않는 변경 내용이 표시됩니다.
버전을 나열할 때 PowerShell은 버전을 문자열로 정렬하므로 1.01.01.001.0초과로 처리됩니다.

PowerShell은 SemVer가 게시되기 전에 만들어졌으므로 특히 SemVer의 모든 요소를 지원하지는 않지만 대부분 지원합니다.

버전 번호의 시험판 문자열은 지원하지 않습니다. 이는 게시자가 버전 1.0.0제공한 후 새 주 버전의 미리 보기 릴리스를 제공하려는 경우에 유용합니다. 이 기능은 PowerShell 갤러리 및 PowerShellGet cmdlet의 향후 릴리스에서 지원됩니다.
PowerShell 및 PowerShell 갤러리는 1, 2 및 4 세그먼트가 있는 버전 문자열을 허용합니다. 대부분의 초기 모듈은 지침을 따르지 않았으며 Microsoft의 제품 릴리스에는 빌드 정보가 4번째 숫자 블록(예: 5.1.14393.1066)으로 포함됩니다. 버전 관리 관점에서 이러한 차이점은 무시됩니다.

로컬 리포지토리를 사용하여 테스트

PowerShell 갤러리는 게시 프로세스를 테스트하기 위한 대상으로 설계되지 않았습니다. PowerShell 갤러리에 게시하는 엔드투엔드 프로세스를 테스트하는 가장 좋은 방법은 고유한 로컬 리포지토리를 설정하고 사용하는 것입니다. 이 작업은 다음을 비롯한 몇 가지 방법으로 수행할 수 있습니다.

GitHub에서 PS 프라이빗 갤러리 프로젝트 사용하여 로컬 PowerShell 갤러리 인스턴스를 설정합니다. 이 미리 보기 프로젝트는 테스트에 대해 제어하고 사용할 수 있는 PowerShell 갤러리의 인스턴스를 설정하는 데 도움이 됩니다.
내부 Nuget 리포지토리설정합니다. 이렇게 하려면 설정하는 데 더 많은 작업이 필요하지만, 특히 API 키 사용의 유효성을 검사하고 게시할 때 대상에 종속성이 있는지 여부를 확인하는 몇 가지 요구 사항의 유효성을 검사하는 이점이 있습니다.
테스트 리포지토리파일 공유를 설정합니다. 쉽게 설정할 수 있지만 파일 공유이므로 위에서 설명한 유효성 검사가 수행되지 않습니다. 이 경우 파일 공유가 필요한 API 키를 확인하지 않으므로 PowerShell 갤러리에 게시하는 데 사용하는 것과 동일한 키를 사용할 수 있다는 장점이 있습니다.

이러한 솔루션 중에서 Register-PSRepository 사용하여 Publish-Module-Repository 매개 변수에 사용하는 새 리포지토리정의합니다.

테스트 게시에 대한 한 가지 추가 사항: PowerShell 갤러리에 게시하는 패키지는 게시하려는 패키지에 종속되지 않음을 확인하는 운영 팀의 도움 없이는 삭제할 수 없습니다. 이러한 이유로 PowerShell 갤러리를 테스트 대상으로 지원하지 않으며 그렇게 하는 게시자에 문의합니다.

PowerShellGet을 사용하여 게시

게시자는 PowerShell 갤러리로 작업할 때 Publish-Module 및 Publish-Script cmdlet을 사용하는 것이 좋습니다. PowerShellGet PowerShell 갤러리에서 설치 및 게시에 대한 중요한 세부 정보를 기억하지 않도록 하기 위해 만들어졌습니다. 경우에 따라 게시자는 powerShellGet 건너뛰고 대신 NuGet 클라이언트 또는 PackageManagement cmdlet을 사용하도록 선택했습니다. 쉽게 놓칠 수 있는 다양한 세부 정보가 있으며, 이로 인해 다양한 지원 요청이 발생합니다.

Publish-Module 또는 Publish-Script사용할 수 없는 이유가 있는 경우 알려주세요. PowerShellGet GitHub 리포지토리에 문제를 제출하고 NuGet 또는 PackageManagement선택할 수 있는 세부 정보를 제공합니다.

권장 워크플로

PowerShell 갤러리에 게시된 패키지에 대해 가장 성공적인 방법은 다음과 같습니다.

오픈 소스 프로젝트 사이트에서 초기 개발을 수행합니다. PowerShell 팀은 GitHub를 사용합니다.
검토자의 피드백을 사용하고 PowerShell 스크립트 분석기 코드를 안정적인 상태로 전환합니다.
다른 사용자가 작업을 사용하는 방법을 알 수 있도록 설명서를 포함합니다.
로컬 리포지토리를 사용하여 게시 작업을 테스트합니다.
안정적인 또는 알파 릴리스를 PowerShell 갤러리에 게시하여 설명서와 프로젝트 사이트에 대한 링크를 포함해야 합니다.
피드백을 수집하고 프로젝트 사이트의 코드를 반복한 다음 안정적인 업데이트를 PowerShell 갤러리에 게시합니다.
프로젝트 및 모듈에 예제 및 Pester 테스트를 추가합니다.
패키지에 코드를 서명할지 여부를 결정합니다.
프로젝트가 프로덕션 환경에서 사용할 준비가 되었다고 생각되면 1.0.0 버전을 PowerShell 갤러리에 게시합니다.
사용자 입력에 따라 계속해서 피드백을 수집하고 코드를 반복합니다.

다음을 통해 공유