Bagikan melalui


Cara menulis manifes modul PowerShell

Setelah menulis modul PowerShell, Anda dapat menambahkan manifes modul opsional yang menyertakan informasi tentang modul. Misalnya, Anda dapat menjelaskan penulis, menentukan file dalam modul (seperti modul berlapis), menjalankan skrip untuk menyesuaikan lingkungan pengguna, memuat jenis dan memformat file, menentukan persyaratan sistem, dan membatasi anggota yang diekspor modul.

Membuat manifes modul

Manifes modul adalah file data PowerShell (.psd1) yang menjelaskan konten modul dan menentukan bagaimana modul diproses. File manifes adalah file teks yang berisi tabel hash kunci dan nilai. Anda menautkan file manifes ke modul dengan menamai manifes yang sama dengan modul, dan menyimpan manifes di direktori akar modul.

Untuk modul sederhana yang hanya berisi satu .psm1 atau rakitan biner, manifes modul bersifat opsional. Namun, rekomendasinya adalah menggunakan manifes modul jika memungkinkan, karena berguna untuk membantu Anda mengatur kode dan mempertahankan informasi penerapan versi. Dan, manifes modul diperlukan untuk mengekspor assembly yang diinstal di Global Assembly Cache. Manifes modul juga diperlukan untuk modul yang mendukung fitur Bantuan yang Dapat Diperbarui. Bantuan yang Dapat Diperbarui menggunakan kunci HelpInfoUri dalam manifes modul untuk menemukan file Informasi bantuan (HelpInfo XML) yang berisi lokasi file bantuan yang diperbarui untuk modul. Untuk informasi selengkapnya tentang Bantuan yang Dapat Diperbarui, lihat Mendukung Bantuan yang Dapat Diperbarui.

Untuk membuat dan menggunakan manifes modul

  1. Praktik terbaik untuk membuat manifes modul adalah menggunakan cmdlet New-ModuleManifest . Anda dapat menggunakan parameter untuk menentukan satu atau beberapa kunci dan nilai default manifes. Satu-satunya persyaratan adalah memberi nama file. New-ModuleManifest membuat manifes modul dengan nilai yang Anda tentukan, dan menyertakan kunci yang tersisa dan nilai defaultnya. Jika Anda perlu membuat beberapa modul, gunakan New-ModuleManifest untuk membuat templat manifes modul yang dapat dimodifikasi untuk berbagai modul Anda. Untuk contoh manifes modul default, lihat manifes Modul sampel.

    New-ModuleManifest -Path C:\myModuleName.psd1 -ModuleVersion "2.0" -Author "YourNameHere"

    Alternatifnya adalah membuat tabel hash manifes modul secara manual menggunakan informasi minimal yang diperlukan, ModuleVersion. Anda menyimpan file dengan nama yang sama dengan modul Anda dan menggunakan .psd1 ekstensi file. Anda kemudian dapat mengedit file dan menambahkan kunci dan nilai yang sesuai.

  2. Tambahkan elemen tambahan apa pun yang Anda inginkan dalam file manifes.

    Untuk mengedit file manifes, gunakan editor teks apa pun yang Anda inginkan. Tetapi, file manifes adalah file skrip yang berisi kode, jadi Anda mungkin ingin mengeditnya di lingkungan pembuatan skrip atau pengembangan, seperti Visual Studio Code. Semua elemen file manifes bersifat opsional, kecuali untuk nomor ModuleVersion .

    Untuk deskripsi kunci dan nilai yang dapat Anda sertakan dalam manifes modul, lihat tabel Elemen manifes modul . Untuk informasi selengkapnya, lihat deskripsi parameter di cmdlet New-ModuleManifest .

  3. Untuk mengatasi skenario apa pun yang mungkin tidak dicakup oleh elemen manifes modul dasar, Anda memiliki opsi untuk menambahkan kode tambahan ke manifes modul Anda.

    Untuk masalah keamanan, PowerShell hanya menjalankan subset kecil operasi yang tersedia dalam file manifes modul. Umumnya, Anda dapat menggunakan if operator pernyataan, aritmetika dan perbandingan, dan jenis data PowerShell dasar.

  4. Setelah membuat manifes modul, Anda dapat mengujinya untuk mengonfirmasi bahwa jalur apa pun yang dijelaskan dalam manifes sudah benar. Untuk menguji manifes modul Anda, gunakan Test-ModuleManifest.

    Test-ModuleManifest myModuleName.psd1

  5. Pastikan manifes modul Anda terletak di tingkat atas direktori yang berisi modul Anda.

    Saat Anda menyalin modul ke sistem dan mengimpornya, PowerShell menggunakan manifes modul untuk mengimpor modul Anda.

  6. Secara opsional, Anda dapat langsung menguji manifes modul dengan panggilan ke Import-Module dengan melakukan sumber titik manifes itu sendiri.

    Import-Module .\myModuleName.psd1

Elemen manifes modul

Tabel berikut menjelaskan elemen yang dapat Anda sertakan dalam manifes modul. Untuk informasi selengkapnya, lihat about_Module_Manifests.

Elemen Bawaan Description
RootModule
Jenis: String
<empty string> Modul skrip atau file modul biner yang terkait dengan manifes ini. Versi PowerShell sebelumnya menyebut elemen ini sebagai ModuleToProcess.
Jenis yang mungkin untuk modul akar dapat kosong, yang membuat modul Manifes , nama modul skrip (.psm1), atau nama modul biner (.exe atau .dll). Menempatkan nama manifes modul (.psd1) atau file skrip (.ps1) dalam elemen ini menyebabkan kesalahan.
Contoh: RootModule = 'ScriptModule.psm1'
ModuleVersion
Jenis: Version
'0.0.1' Nomor versi modul ini. Jika nilai tidak ditentukan, New-ModuleManifest gunakan default. String harus dapat dikonversi ke jenis Version misalnya #.#.#.#. Import-Module memuat modul pertama yang ditemukannya pada $PSModulePath yang cocok dengan nama, dan memiliki setidaknya setingg ModuleVersion, sebagai parameter MinimumVersion . Untuk mengimpor versi tertentu, gunakan Import-Module parameter RequiredVersion cmdlet.
Contoh: ModuleVersion = '1.0'
GUID
Jenis: GUID
'<GUID>' ID yang digunakan untuk mengidentifikasi modul ini secara unik. Jika nilai tidak ditentukan, New-ModuleManifest buat nilai secara otomatis. Saat ini Anda tidak dapat mengimpor modul dengan GUID.
Contoh: GUID = 'cfc45206-1e49-459d-a8ad-5b571ef94857'
Pengarang
Jenis: String
'<Current user>' Penulis modul ini. Jika nilai tidak ditentukan, New-ModuleManifest gunakan pengguna saat ini.
Contoh: Author = 'AuthorNameHere'
Nama Perusahaan
Jenis: String
'Unknown' Perusahaan atau vendor modul ini. Jika nilai tidak ditentukan, New-ModuleManifest gunakan default.
Contoh: CompanyName = 'Fabrikam'
Hak cipta
Jenis: String
'(c) <Author>. All rights reserved.' Pernyataan hak cipta untuk modul ini. Jika nilai tidak ditentukan, New-ModuleManifest gunakan default dengan pengguna saat ini sebagai <Author>. Untuk menentukan penulis, gunakan parameter Penulis .
Contoh: Copyright = '2019 AuthorName. All rights reserved.'
Deskripsi
Jenis: String
<empty string> Deskripsi fungsionalitas yang disediakan oleh modul ini.
Contoh: Description = 'This is the module's description.'
PowerShellVersion
Jenis: Version
<empty string> Versi minimum mesin PowerShell yang diperlukan oleh modul ini. Nilai yang valid adalah 1,0, 2.0, 3.0, 4.0, 5.0, 5.1, 6.0, 6.1, 6.2, 7.0 dan 7.1.
Contoh: PowerShellVersion = '5.0'
PowerShellHostName
Jenis: String
<empty string> Nama host PowerShell yang diperlukan oleh modul ini. Nama ini disediakan oleh PowerShell. Untuk menemukan nama program host, dalam program, ketik: $Host.Name.
Contoh: PowerShellHostName = 'ConsoleHost'
PowerShellHostVersion
Jenis: Version
<empty string> Versi minimum host PowerShell yang diperlukan oleh modul ini.
Contoh: PowerShellHostVersion = '2.0'
DotNetFrameworkVersion
Jenis: Version
<empty string> Versi minimum Microsoft .NET Framework yang diperlukan oleh modul ini. Prasyarat ini hanya berlaku untuk edisi PowerShell Desktop, seperti Windows PowerShell 5.1, dan hanya berlaku untuk versi .NET Framework yang lebih rendah dari 4.5.
Contoh: DotNetFrameworkVersion = '3.5'
CLRVersion
Jenis: Version
<empty string> Versi minimum runtime bahasa umum (CLR) yang diperlukan oleh modul ini. Prasyarat ini hanya berlaku untuk edisi PowerShell Desktop, seperti Windows PowerShell 5.1, dan hanya berlaku untuk versi .NET Framework yang lebih rendah dari 4.5.
Contoh: CLRVersion = '3.5'
ProcessorArchitecture
Jenis: ProcessorArchitecture
<empty string> Arsitektur prosesor (None, X86, Amd64) diperlukan oleh modul ini. Nilai yang valid adalah x86, AMD64, Arm, IA64, MSIL, dan None (tidak diketahui atau tidak ditentukan).
Contoh: ProcessorArchitecture = 'x86'
RequiredModules
Jenis: Object[]
@() Modul yang harus diimpor ke lingkungan global sebelum mengimpor modul ini. Ini memuat modul apa pun yang tercantum kecuali modul telah dimuat. Misalnya, beberapa modul mungkin sudah dimuat oleh modul yang berbeda. Anda dapat menentukan versi tertentu untuk dimuat menggunakan RequiredVersion daripada ModuleVersion. Ketika ModuleVersion digunakan, ini akan memuat versi terbaru yang tersedia dengan minimal versi yang ditentukan. Anda dapat menggabungkan string dan tabel hash dalam nilai parameter.
Contoh: RequiredModules = @("MyModule", @{ModuleName="MyDependentModule"; ModuleVersion="2.0"; GUID="cfc45206-1e49-459d-a8ad-5b571ef94857"})
Contoh: RequiredModules = @("MyModule", @{ModuleName="MyDependentModule"; RequiredVersion="1.5"; GUID="cfc45206-1e49-459d-a8ad-5b571ef94857"})
RequiredAssemblies
Jenis: String[]
@() Rakitan yang harus dimuat sebelum mengimpor modul ini. Menentukan nama file assembly (.dll) yang diperlukan modul.
PowerShell memuat rakitan yang ditentukan sebelum memperbarui jenis atau format, mengimpor modul berlapis, atau mengimpor file modul yang ditentukan dalam nilai kunci RootModule. Gunakan parameter ini untuk mencantumkan semua rakitan yang diperlukan modul.
Contoh: RequiredAssemblies = @("assembly1.dll", "assembly2.dll", "assembly3.dll")
ScriptsToProcess
Jenis: String[]
@() File skrip (.ps1) yang dijalankan dalam status sesi pemanggil saat modul diimpor. Ini bisa menjadi status sesi global atau, untuk modul berlapis, status sesi modul lain. Anda dapat menggunakan skrip ini untuk menyiapkan lingkungan sama seperti Anda mungkin menggunakan skrip masuk.
Skrip ini dijalankan sebelum salah satu modul yang tercantum dalam manifes dimuat.
Contoh: ScriptsToProcess = @("script1.ps1", "script2.ps1", "script3.ps1")
TypeToProcess
Jenis: String[]
@() Ketik file (.ps1xml) yang akan dimuat saat mengimpor modul ini.
Contoh: TypesToProcess = @("type1.ps1xml", "type2.ps1xml", "type3.ps1xml")
FormatsToProcess
Jenis: String[]
@() Format file (.ps1xml) yang akan dimuat saat mengimpor modul ini.
Contoh: FormatsToProcess = @("format1.ps1xml", "format2.ps1xml", "format3.ps1xml")
NestedModules
Jenis: Object[]
@() Modul untuk diimpor sebagai modul berlapis modul yang ditentukan dalam RootModule (alias:ModuleToProcess).
Menambahkan nama modul ke elemen ini mirip dengan panggilan Import-Module dari dalam skrip atau kode rakitan Anda. Perbedaan utama dengan menggunakan file manifes adalah lebih mudah untuk melihat apa yang Anda muat. Dan, jika modul gagal dimuat, Anda belum akan memuat modul aktual Anda.
Selain modul lain, Anda juga dapat memuat file skrip (.ps1) di sini. File-file ini akan dijalankan dalam konteks modul akar. Ini setara dengan titik sumber skrip dalam modul akar Anda.
Contoh: NestedModules = @("script.ps1", @{ModuleName="MyModule"; ModuleVersion="1.0.0.0"; GUID="50cdb55f-5ab7-489f-9e94-4ec21ff51e59"})
FunctionsToExport
Jenis: String[]
@() Menentukan fungsi yang akan diekspor dari modul ini, untuk performa terbaik, jangan gunakan kartubebas dan jangan hapus entri, gunakan array kosong jika tidak ada fungsi untuk diekspor. Secara default, tidak ada fungsi yang diekspor. Anda dapat menggunakan kunci ini untuk mencantumkan fungsi yang diekspor oleh modul.
Modul mengekspor fungsi ke status sesi pemanggil. Status sesi penelepon dapat menjadi status sesi global atau, untuk modul berlapis, status sesi modul lain. Saat menautkan modul berlapis, semua fungsi yang diekspor oleh modul berlapis akan diekspor ke status sesi global kecuali modul dalam rantai membatasi fungsi dengan menggunakan kunci FunctionsToExport .
Jika manifes mengekspor alias untuk fungsi, kunci ini dapat menghapus fungsi yang aliasnya tercantum dalam kunci AliasesToExport , tetapi kunci ini tidak dapat menambahkan alias fungsi ke daftar.
Contoh: FunctionsToExport = @("function1", "function2", "function3")
CmdletsToExport
Jenis: String[]
@() Menentukan cmdlet yang akan diekspor dari modul ini, untuk performa terbaik, jangan gunakan wildcard dan jangan hapus entri, gunakan array kosong jika tidak ada cmdlet untuk diekspor. Secara default, tidak ada cmdlet yang diekspor. Anda dapat menggunakan kunci ini untuk mencantumkan cmdlet yang diekspor oleh modul.
Status sesi penelepon dapat menjadi status sesi global atau, untuk modul berlapis, status sesi modul lain. Saat Anda merantai modul berlapis, semua cmdlet yang diekspor oleh modul berlapis akan diekspor ke status sesi global kecuali modul dalam rantai membatasi cmdlet dengan menggunakan kunci CmdletsToExport .
Jika manifes mengekspor alias untuk cmdlet, kunci ini dapat menghapus cmdlet yang aliasnya tercantum dalam kunci AliasesToExport , tetapi kunci ini tidak dapat menambahkan alias cmdlet ke daftar.
Contoh: CmdletsToExport = @("Get-MyCmdlet", "Set-MyCmdlet", "Test-MyCmdlet")
VariablesToExport
Jenis: String[]
'*' Menentukan variabel yang diekspor modul ke status sesi pemanggil. Karakter pengganti diizinkan. Secara default, semua variabel ('*') diekspor. Anda dapat menggunakan kunci ini untuk membatasi variabel yang diekspor oleh modul.
Status sesi penelepon dapat menjadi status sesi global atau, untuk modul berlapis, status sesi modul lain. Saat Anda merantai modul berlapis, semua variabel yang diekspor oleh modul berlapis akan diekspor ke status sesi global kecuali modul dalam rantai membatasi variabel dengan menggunakan kunci VariablesToExport .
Jika manifes juga mengekspor alias untuk variabel, kunci ini dapat menghapus variabel yang aliasnya tercantum dalam kunci AliasesToExport , tetapi kunci ini tidak dapat menambahkan alias variabel ke daftar.
Contoh: VariablesToExport = @('$MyVariable1', '$MyVariable2', '$MyVariable3')
AliasesToExport
Jenis: String[]
@() Menentukan alias yang akan diekspor dari modul ini, untuk performa terbaik, jangan gunakan kartubebas dan jangan hapus entri, gunakan array kosong jika tidak ada alias untuk diekspor. Secara default, tidak ada alias yang diekspor. Anda dapat menggunakan kunci ini untuk mencantumkan alias yang diekspor oleh modul.
Modul mengekspor alias ke status sesi pemanggil. Status sesi penelepon dapat menjadi status sesi global atau, untuk modul berlapis, status sesi modul lain. Saat Anda merantai modul berlapis, semua alias yang diekspor oleh modul berlapis pada akhirnya akan diekspor ke status sesi global kecuali modul dalam rantai membatasi alias dengan menggunakan kunci AliasesToExport .
Contoh: AliasesToExport = @("MyAlias1", "MyAlias2", "MyAlias3")
DscResourcesToExport
Jenis: String[]
@() Menentukan sumber daya DSC untuk diekspor dari modul ini. Kartubebas diizinkan.
Contoh: DscResourcesToExport = @("DscResource1", "DscResource2", "DscResource3")
ModuleList
Jenis: Object[]
@() Menentukan semua modul yang dibungkus dengan modul ini. Modul ini dapat dimasukkan berdasarkan nama, menggunakan string yang dipisahkan koma, atau sebagai tabel hash dengan kunci ModuleName dan GUID . Tabel hash juga dapat memiliki kunci ModuleVersion opsional. Kunci ModuleList dirancang untuk bertindak sebagai inventori modul. Modul ini tidak diproses secara otomatis.
Contoh: ModuleList = @("SampleModule", "MyModule", @{ModuleName="MyModule"; ModuleVersion="1.0.0.0"; GUID="50cdb55f-5ab7-489f-9e94-4ec21ff51e59"})
Daftar File
Jenis: String[]
@() Daftar semua file yang dibungkus dengan modul ini. Seperti halnya ModuleList, FileList adalah daftar inventori, dan tidak diproses.
Contoh: FileList = @("File1", "File2", "File3")
PrivateData
Jenis: Object
@{...} Menentukan data privat apa pun yang perlu diteruskan ke modul akar yang ditentukan oleh kunci RootModule (alias: ModuleToProcess). PrivateData adalah tabel hash yang terdiri dari beberapa elemen: Tag, LicenseUri, ProjectURI, IconUri, ReleaseNotes, Prerelease, RequireLicenseAcceptance, dan ExternalModuleDependencies.
Tags
Jenis: String[]
@() Tag membantu penemuan modul di galeri online.
Contoh: Tags = "PackageManagement", "PowerShell", "Manifest"
LicenseUri
Jenis: Uri
<empty string> URL ke lisensi untuk modul ini.
Contoh: LicenseUri = 'https://www.contoso.com/license'
ProjectUri
Jenis: Uri
<empty string> URL ke situs web utama untuk proyek ini.
Contoh: ProjectUri = 'https://www.contoso.com/project'
IconUri
Jenis: Uri
<empty string> URL ke ikon yang mewakili modul ini.
Contoh: IconUri = 'https://www.contoso.com/icons/icon.png'
Catatan Rilis
Jenis: String
<empty string> Menentukan catatan rilis modul.
Contoh: ReleaseNotes = 'The release notes provide information about the module.
Prerelease
Jenis: String
<empty string> Parameter ini ditambahkan di PowerShellGet 1.6.6. String PraRilis yang mengidentifikasi modul sebagai versi prarilis di galeri online.
Contoh: PreRelease = 'alpha'
RequireLicenseAcceptance
Jenis: Boolean
$false Parameter ini ditambahkan di PowerShellGet 1.5. Bendera untuk menunjukkan apakah modul memerlukan penerimaan pengguna eksplisit untuk menginstal, memperbarui, atau menyimpan.
Contoh: RequireLicenseAcceptance = $false
ExternalModuleDependencies
Jenis: String[]
@() Parameter ini ditambahkan di PowerShellGet v2. Daftar modul eksternal yang bergantung pada modul ini.
Contoh: ExternalModuleDependencies = @("ExtModule1", "ExtModule2", "ExtModule3"). Daftar ini hanya bersifat informasi. Tidak seperti RequiredModules, itu tidak digunakan untuk memberlakukan dependensi.
HelpInfoURI
Jenis: String
<empty string> HelpInfo URI modul ini.
Contoh: HelpInfoURI = 'https://www.contoso.com/help'
DefaultCommandPrefix
Jenis: String
<empty string> Awalan default untuk perintah yang diekspor dari modul ini. Ambil alih awalan default menggunakan Import-Module -Prefix.
Contoh: DefaultCommandPrefix = 'My'

Contoh manifes modul

Contoh manifes modul berikut dibuat dengan New-ModuleManifest di PowerShell 7 dan berisi kunci dan nilai default.

#
# Module manifest for module 'SampleModuleManifest'
#
# Generated by: User01
#
# Generated on: 10/15/2019
#

@{

# Script module or binary module file associated with this manifest.
# RootModule = ''

# Version number of this module.
ModuleVersion = '0.0.1'

# Supported PSEditions
# CompatiblePSEditions = @()

# ID used to uniquely identify this module
GUID = 'b632e90c-df3d-4340-9f6c-3b832646bf87'

# Author of this module
Author = 'User01'

# Company or vendor of this module
CompanyName = 'Unknown'

# Copyright statement for this module
Copyright = '(c) User01. All rights reserved.'

# Description of the functionality provided by this module
# Description = ''

# Minimum version of the PowerShell engine required by this module
# PowerShellVersion = ''

# Name of the PowerShell host required by this module
# PowerShellHostName = ''

# Minimum version of the PowerShell host required by this module
# PowerShellHostVersion = ''

# Minimum version of Microsoft .NET Framework required by this module. This prerequisite is valid for the PowerShell Desktop edition only.
# DotNetFrameworkVersion = ''

# Minimum version of the common language runtime (CLR) required by this module. This prerequisite is valid for the PowerShell Desktop edition only.
# CLRVersion = ''

# Processor architecture (None, X86, Amd64) required by this module
# ProcessorArchitecture = ''

# Modules that must be imported into the global environment prior to importing this module
# RequiredModules = @()

# Assemblies that must be loaded prior to importing this module
# RequiredAssemblies = @()

# Script files (.ps1) that are run in the caller's environment prior to importing this module.
# ScriptsToProcess = @()

# Type files (.ps1xml) to be loaded when importing this module
# TypesToProcess = @()

# Format files (.ps1xml) to be loaded when importing this module
# FormatsToProcess = @()

# Modules to import as nested modules of the module specified in RootModule/ModuleToProcess
# NestedModules = @()

# Functions to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no functions to export.
FunctionsToExport = @()

# Cmdlets to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no cmdlets to export.
CmdletsToExport = @()

# Variables to export from this module
VariablesToExport = '*'

# Aliases to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no aliases to export.
AliasesToExport = @()

# DSC resources to export from this module
# DscResourcesToExport = @()

# List of all modules packaged with this module
# ModuleList = @()

# List of all files packaged with this module
# FileList = @()

# Private data to pass to the module specified in RootModule/ModuleToProcess. This may also contain a PSData hashtable with additional module metadata used by PowerShell.
PrivateData = @{

    PSData = @{

        # Tags applied to this module. These help with module discovery in online galleries.
        # Tags = @()

        # A URL to the license for this module.
        # LicenseUri = ''

        # A URL to the main website for this project.
        # ProjectUri = ''

        # A URL to an icon representing this module.
        # IconUri = ''

        # ReleaseNotes of this module
        # ReleaseNotes = ''

        # Prerelease string of this module
        # Prerelease = ''

        # Flag to indicate whether the module requires explicit user acceptance for install/update/save
        # RequireLicenseAcceptance = $false

        # External dependent modules of this module
        # ExternalModuleDependencies = @()

    } # End of PSData hashtable

} # End of PrivateData hashtable

# HelpInfo URI of this module
# HelpInfoURI = ''

# Default prefix for commands exported from this module. Override the default prefix using Import-Module -Prefix.
# DefaultCommandPrefix = ''

}

Lihat juga