Register-PSSessionConfiguration

Membuat dan mendaftarkan konfigurasi sesi baru.

Sintaks

Register-PSSessionConfiguration
        [-ProcessorArchitecture <String>]
        [-Name] <String>
        [-ApplicationBase <String>]
        [-RunAsCredential <PSCredential>]
        [-ThreadApartmentState <ApartmentState>]
        [-ThreadOptions <PSThreadOptions>]
        [-AccessMode <PSSessionConfigurationAccessMode>]
        [-UseSharedProcess]
        [-StartupScript <String>]
        [-MaximumReceivedDataSizePerCommandMB <Double>]
        [-MaximumReceivedObjectSizeMB <Double>]
        [-SecurityDescriptorSddl <String>]
        [-ShowSecurityDescriptorUI]
        [-Force]
        [-NoServiceRestart]
        [-PSVersion <Version>]
        [-SessionTypeOption <PSSessionTypeOption>]
        [-TransportOption <PSTransportOption>]
        [-ModulesToImport <Object[]>]
        [-WhatIf]
        [-Confirm]
        [<CommonParameters>]
Register-PSSessionConfiguration
        [-ProcessorArchitecture <String>]
        [-Name] <String>
        [-AssemblyName] <String>
        [-ApplicationBase <String>]
        [-ConfigurationTypeName] <String>
        [-RunAsCredential <PSCredential>]
        [-ThreadApartmentState <ApartmentState>]
        [-ThreadOptions <PSThreadOptions>]
        [-AccessMode <PSSessionConfigurationAccessMode>]
        [-UseSharedProcess]
        [-StartupScript <String>]
        [-MaximumReceivedDataSizePerCommandMB <Double>]
        [-MaximumReceivedObjectSizeMB <Double>]
        [-SecurityDescriptorSddl <String>]
        [-ShowSecurityDescriptorUI]
        [-Force]
        [-NoServiceRestart]
        [-PSVersion <Version>]
        [-SessionTypeOption <PSSessionTypeOption>]
        [-TransportOption <PSTransportOption>]
        [-ModulesToImport <Object[]>]
        [-WhatIf]
        [-Confirm]
        [<CommonParameters>]
Register-PSSessionConfiguration
        [-ProcessorArchitecture <String>]
        [-Name] <String>
        [-RunAsCredential <PSCredential>]
        [-ThreadApartmentState <ApartmentState>]
        [-ThreadOptions <PSThreadOptions>]
        [-AccessMode <PSSessionConfigurationAccessMode>]
        [-UseSharedProcess]
        [-StartupScript <String>]
        [-MaximumReceivedDataSizePerCommandMB <Double>]
        [-MaximumReceivedObjectSizeMB <Double>]
        [-SecurityDescriptorSddl <String>]
        [-ShowSecurityDescriptorUI]
        [-Force]
        [-NoServiceRestart]
        [-TransportOption <PSTransportOption>]
        -Path <String>
        [-WhatIf]
        [-Confirm]
        [<CommonParameters>]

Deskripsi

Cmdlet ini hanya tersedia di platform Windows.

Register-PSSessionConfiguration Cmdlet membuat dan mendaftarkan konfigurasi sesi baru di komputer lokal. Ini adalah cmdlet tingkat lanjut yang dapat Anda gunakan untuk membuat sesi kustom untuk pengguna jarak jauh.

Setiap sesi PowerShell (PSSession) menggunakan konfigurasi sesi, juga dikenal sebagai titik akhir. Saat pengguna membuat sesi yang tersambung ke komputer, mereka dapat memilih konfigurasi sesi atau menggunakan konfigurasi sesi default yang terdaftar saat Anda mengaktifkan remoting PowerShell. Pengguna juga dapat mengatur variabel preferensi $PSSessionConfigurationName, yang menentukan konfigurasi default untuk sesi jarak jauh yang dibuat dalam sesi saat ini.

Konfigurasi sesi menentukan lingkungan untuk sesi jarak jauh. Konfigurasi dapat menentukan perintah dan elemen bahasa mana yang tersedia dalam sesi, dan dapat mencakup pengaturan yang melindungi komputer, seperti yang membatasi jumlah data yang dapat diterima sesi dari jarak jauh dalam satu objek atau perintah. Pendeskripsi keamanan konfigurasi sesi menentukan pengguna mana yang memiliki izin untuk menggunakan konfigurasi sesi.

Anda dapat menentukan elemen konfigurasi dengan menggunakan rakitan yang mengimplementasikan kelas konfigurasi baru dan dengan menggunakan skrip yang berjalan dalam sesi. Dimulai di PowerShell 3.0, Anda juga dapat menggunakan file konfigurasi sesi untuk menentukan konfigurasi sesi.

Untuk informasi tentang konfigurasi sesi, lihat about_Session_Configurations. Untuk informasi tentang file konfigurasi sesi, lihat about_Session_Configuration_Files.

Contoh

Contoh 1: Mendaftarkan konfigurasi sesi NewShell

Dalam contoh ini, kami mendaftarkan konfigurasi sesi NewShell . Parameter AssemblyName dan ApplicationBase menentukan lokasi file MyShell.dll , yang menentukan cmdlet dan penyedia dalam konfigurasi sesi. Parameter ConfigurationTypeName menentukan kelas konfigurasi yang akan digunakan dari rakitan.

$sessionConfiguration = @{
    Name='NewShell'
    ApplicationBase='c:\MyShells\'
    AssemblyName='MyShell.dll'
    ConfigurationTypeName='MyClass'
}
Register-PSSessionConfiguration @sessionConfiguration

Untuk menggunakan konfigurasi ini, ketik New-PSSession -ConfigurationName newshell.

Contoh 2: Mendaftarkan konfigurasi sesi MaintenanceShell

Contoh ini mendaftarkan konfigurasi sesi MaintenanceShell di komputer lokal. Parameter StartupScript menentukan Maintenance.ps1 skrip.

Register-PSSessionConfiguration -Name MaintenanceShell -StartupScript C:\ps-test\Maintenance.ps1

Saat pengguna menggunakan New-PSSession perintah dan memilih konfigurasi MaintenanceShell , Maintenance.ps1 skrip berjalan di sesi baru. Skrip dapat mengonfigurasi sesi. Ini termasuk mengimpor modul dan mengatur kebijakan eksekusi untuk sesi tersebut. Jika skrip menghasilkan kesalahan apa pun, termasuk kesalahan yang tidak mengakhiri, New-PSSession perintah gagal.

Contoh 3: Mendaftarkan konfigurasi sesi

Contoh ini mendaftarkan konfigurasi sesi AdminShell .

Variabel $sessionParams adalah hashtable yang berisi semua nilai parameter. Hashtable ini diteruskan ke cmdlet menggunakan splatting PowerShell. Perintah Register-PSSessionConfiguration menggunakan parameter SecurityDescritorSDDL untuk menentukan SDDL dalam nilai $sddl variabel dan parameter MaximumReceivedObjectSizeMB untuk meningkatkan batas ukuran objek. Ini juga menggunakan parameter StartupScript untuk menentukan skrip yang mengonfigurasi sesi.

$sddl = "O:NSG:BAD:P(A;;GA;;;BA)S:P(AU;FA;GA;;;WD)(AU;FASA;GWGX;;;WD)"
$sessionParams = @{
    Name="AdminShell"
    SecurityDescriptorSDDL=$sddl
    MaximumReceivedObjectSizeMB=20
    StartupScript="C:\scripts\AdminShell.ps1"
}
Register-PSSessionConfiguration @sessionParams

Contoh 4: Mengembalikan elemen kontainer konfigurasi

Contoh ini menunjukkan cara mendaftarkan konfigurasi MaintenanceShell . Register-PSSessionConfigurationmengembalikan objek WSManConfigContainerElement yang disimpan dalam $s variabel. Format-List menampilkan semua properti objek yang dikembalikan. Properti PSPath menunjukkan bahwa objek disimpan dalam direktori WSMan: drive. Get-ChildItem (alias dir) menampilkan item di WSMan:\LocalHost\PlugIn jalur. Ini termasuk konfigurasi MaintenanceShell baru dan dua konfigurasi default yang disertakan dengan PowerShell.

$s = Register-PSSessionConfiguration -Name MaintenanceShell -StartupScript C:\ps-test\Maintenance.ps1
$s | Format-List -Property *
dir WSMan:\LocalHost\Plugin

PSPath            : Microsoft.WSMan.Management\WSMan::localhost\Plugin\MaintenanceShell
PSParentPath      : Microsoft.WSMan.Management\WSMan::localhost\Plugin
PSChildName       : MaintenanceShell
PSDrive           : WSMan
PSProvider        : Microsoft.WSMan.Management\WSMan
PSIsContainer     : True
Keys              : {Name=MaintenanceShell}
Name              : MaintenanceShell
TypeNameOfElement : Container

Name                      Type                 Keys
----                      ----                 ----
MaintenanceShell          Container            {Name=MaintenanceShell}
microsoft.powershell      Container            {Name=microsoft.powershell}
microsoft.powershell32    Container            {Name=microsoft.powershell32}

Contoh 5: Mendaftarkan konfigurasi sesi dengan skrip startup

Dalam contoh ini kita membuat dan mendaftarkan konfigurasi sesi WithProfile . Parameter StartupScript mengarahkan PowerShell untuk menjalankan skrip yang ditentukan untuk sesi apa pun yang menggunakan konfigurasi sesi.

Register-PSSessionConfiguration -Name WithProfile -StartupScript Add-Profile.ps1

Skrip berisi satu perintah yang menggunakan sumber titik untuk menjalankan profil CurrentUserAllHosts pengguna dalam cakupan sesi saat ini.

Untuk informasi selengkapnya tentang profil, lihat about_Profiles. Untuk informasi selengkapnya tentang sumber titik, lihat about_Scopes.

Parameter

-AccessMode

Mengaktifkan dan menonaktifkan konfigurasi sesi dan menentukan apakah dapat digunakan untuk sesi jarak jauh atau lokal di komputer. Nilai yang dapat diterima untuk parameter ini adalah:

  • Dinonaktifkan. Menonaktifkan konfigurasi sesi. Ini tidak dapat digunakan untuk akses jarak jauh atau lokal ke komputer.
  • Lokal. Memungkinkan pengguna komputer lokal menggunakan konfigurasi sesi untuk membuat sesi loopback lokal di komputer yang sama, tetapi menolak akses ke pengguna jarak jauh.
  • Jarak Jauh. Memungkinkan pengguna lokal dan jarak jauh menggunakan konfigurasi sesi untuk membuat sesi dan menjalankan perintah pada komputer ini.

Nilai defaultnya adalah Remote.

Cmdlet lain dapat mengambil alih nilai parameter ini nanti. Misalnya, Enable-PSRemoting cmdlet memungkinkan akses jarak jauh ke semua konfigurasi sesi, Enable-PSSessionConfiguration cmdlet memungkinkan konfigurasi sesi, dan Disable-PSRemoting cmdlet mencegah akses jarak jauh ke semua konfigurasi sesi.

Parameter ini diperkenalkan di PowerShell 3.0.

Type:PSSessionConfigurationAccessMode
Accepted values:Disabled, Local, Remote
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ApplicationBase

Menentukan jalur file rakitan (*.dll) yang ditentukan dalam nilai parameter AssemblyName . Gunakan parameter ini saat nilai parameter AssemblyName tidak menyertakan jalur. Defaultnya adalah direktori saat ini.

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-AssemblyName

Menentukan nama file rakitan (*.dll) tempat jenis konfigurasi ditentukan. Anda dapat menentukan jalur .dll dalam parameter ini atau dalam nilai parameter ApplicationBase .

Parameter ini diperlukan saat Anda menentukan parameter ConfigurationTypeName .

Type:String
Position:1
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-ConfigurationTypeName

Menentukan nama yang sepenuhnya memenuhi syarat dari jenis Microsoft .NET Framework yang digunakan untuk konfigurasi ini. Jenis yang Anda tentukan harus menerapkan kelas System.Management.Automation.Remoting.PSSessionConfiguration .

Untuk menentukan file rakitan (*.dll) yang mengimplementasikan jenis konfigurasi, tentukan parameter AssemblyName dan ApplicationBase .

Membuat jenis memungkinkan Anda mengontrol lebih banyak aspek konfigurasi sesi, seperti mengekspos atau menyembunyikan parameter cmdlet tertentu, atau mengatur ukuran data dan batas ukuran objek yang tidak dapat diambil alih pengguna.

Jika Anda menghilangkan parameter ini, kelas DefaultRemotePowerShellConfiguration digunakan untuk konfigurasi sesi.

Type:String
Position:2
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-Confirm

Meminta Anda mengonfirmasi sebelum menjalankan cmdlet.

Type:SwitchParameter
Aliases:cf
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Force

Menekan semua permintaan pengguna dan memulai ulang layanan WinRM tanpa meminta. Memulai ulang layanan membuat perubahan konfigurasi efektif.

Untuk mencegah restart dan menekan perintah hidupkan ulang, tentukan parameter NoServiceRestart .

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-MaximumReceivedDataSizePerCommandMB

Menentukan batas jumlah data yang dapat dikirim ke komputer ini dalam satu perintah jarak jauh. Masukkan ukuran data dalam megabyte (MB). Defaultnya adalah 50 MB.

Jika batas ukuran data ditentukan dalam jenis konfigurasi yang ditentukan dalam parameter ConfigurationTypeName , batas dalam jenis konfigurasi digunakan dan nilai parameter ini diabaikan.

Type:Nullable<T>[Double]
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-MaximumReceivedObjectSizeMB

Menentukan batas jumlah data yang dapat dikirim ke komputer ini dalam satu objek. Masukkan ukuran data dalam megabyte. Defaultnya adalah 10 MB.

Jika batas ukuran objek ditentukan dalam jenis konfigurasi yang ditentukan dalam parameter ConfigurationTypeName , batas dalam jenis konfigurasi digunakan dan nilai parameter ini diabaikan.

Type:Nullable<T>[Double]
Position:Named
Default value:10
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ModulesToImport

Menentukan modul yang diimpor secara otomatis ke sesi yang menggunakan konfigurasi sesi.

Secara default, hanya Microsoft.PowerShell.Core yang diimpor ke dalam sesi. Kecuali cmdlet dikecualikan, Anda dapat menggunakan Import-Module untuk menambahkan modul ke sesi.

Modul yang ditentukan dalam nilai parameter ini diimpor sebagai tambahan untuk modul yang ditentukan oleh parameter SessionType dan yang tercantum dalam kunci ModulesToImport dalam file konfigurasi sesi (New-PSSessionConfigurationFile). Namun, pengaturan dalam file konfigurasi sesi dapat menyembunyikan perintah yang diekspor oleh modul atau mencegah pengguna menggunakannya.

Parameter ini diperkenalkan di PowerShell 3.0.

Type:Object[]
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Name

Menentukan nama untuk konfigurasi sesi. Parameter ini diperlukan.

Type:String
Position:0
Default value:None
Required:True
Accept pipeline input:True
Accept wildcard characters:False

-NoServiceRestart

Tidak memulai ulang layanan WinRM , dan menekan perintah untuk memulai ulang layanan.

Secara default, saat menjalankan Register-PSSessionConfiguration perintah, Anda diminta untuk memulai ulang layanan WinRM agar konfigurasi sesi baru efektif. Hingga layanan WinRM dimulai ulang, konfigurasi sesi baru tidak efektif.

Untuk memulai ulang layanan WinRM tanpa meminta, tentukan parameter Paksa . Untuk memulai ulang layanan WinRM secara manual, gunakan Restart-Service cmdlet .

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Path

Menentukan jalur dan nama file file konfigurasi sesi (.pssc), seperti yang dibuat oleh New-PSSessionConfigurationFile. Jika Anda menghilangkan jalur, defaultnya adalah direktori saat ini.

Parameter ini diperkenalkan di PowerShell 3.0.

Type:String
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-ProcessorArchitecture

Menentukan apakah versi 32-bit atau 64-bit dari proses PowerShell dimulai dalam sesi yang menggunakan konfigurasi sesi ini. Nilai yang dapat diterima untuk parameter ini adalah: x86 (32-bit) dan AMD64 (64-bit). Nilai default ditentukan oleh arsitektur prosesor komputer yang menghosting konfigurasi sesi.

Anda dapat menggunakan parameter ini untuk membuat sesi 32-bit pada komputer 64-bit. Upaya untuk membuat proses 64-bit pada komputer 32-bit gagal.

Type:String
Aliases:PA
Accepted values:x86, amd64
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-PSVersion

Menentukan versi PowerShell dalam sesi yang menggunakan konfigurasi sesi ini.

Nilai parameter ini lebih diutamakan daripada nilai kunci PowerShellVersion dalam file konfigurasi sesi.

Parameter ini diperkenalkan di PowerShell 3.0.

Type:Version
Aliases:PowerShellVersion
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-RunAsCredential

Menentukan kredensial untuk perintah dalam sesi. Secara default, perintah berjalan dengan izin pengguna saat ini.

Parameter ini diperkenalkan di PowerShell 3.0.

Type:PSCredential
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-SecurityDescriptorSddl

Menentukan string Security Descriptor Definition Language (SDDL) untuk konfigurasi.

String ini menentukan izin yang diperlukan untuk menggunakan konfigurasi sesi baru. Untuk menggunakan konfigurasi sesi dalam sesi, pengguna harus memiliki setidaknya izin Jalankan (Panggil) untuk konfigurasi.

Jika deskriptor keamanan kompleks, pertimbangkan untuk menggunakan parameter ShowSecurityDescriptorUI alih-alih parameter ini. Anda tidak dapat menggunakan kedua parameter dalam perintah yang sama.

Jika Anda menghilangkan parameter ini, SDDL akar untuk layanan WinRM digunakan untuk konfigurasi ini. Untuk melihat atau mengubah SDDL akar, gunakan penyedia WSMan. Contoh: Get-Item wsman:\localhost\service\rootSDDL. Untuk informasi selengkapnya tentang penyedia WSMan, ketik Get-Help wsman.

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-SessionTypeOption

Menentukan opsi khusus jenis untuk konfigurasi sesi. Masukkan objek opsi jenis sesi, seperti objek PSWorkflowExecutionOption yang New-PSWorkflowExecutionOption dikembalikan cmdlet.

Opsi sesi yang menggunakan konfigurasi sesi ditentukan oleh nilai opsi sesi dan opsi konfigurasi sesi. Kecuali ditentukan, opsi yang diatur dalam sesi, seperti dengan menggunakan New-PSSessionOption cmdlet, lebih diutamakan daripada opsi yang diatur dalam konfigurasi sesi. Namun, nilai opsi sesi tidak boleh melebihi nilai maksimum yang ditetapkan dalam konfigurasi sesi.

Parameter ini diperkenalkan di PowerShell 3.0.

Type:PSSessionTypeOption
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ShowSecurityDescriptorUI

Menunjukkan bahwa cmdlet ini menampilkan lembar properti yang membantu Anda membuat SDDL untuk konfigurasi sesi. Lembar properti muncul setelah Anda memasukkan Register-PSSessionConfiguration perintah lalu memulai ulang layanan WinRM .

Saat mengatur izin untuk konfigurasi, ingatlah bahwa pengguna harus memiliki setidaknya izin Jalankan (Panggil) untuk menggunakan konfigurasi sesi dalam sesi.

Anda tidak dapat menggunakan parameter SecurityDescriptorSDDL dan parameter ini dalam perintah yang sama.

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-StartupScript

Menentukan jalur skrip PowerShell yang sepenuhnya memenuhi syarat. Skrip yang ditentukan berjalan di sesi baru yang menggunakan konfigurasi sesi.

Anda dapat menggunakan skrip untuk mengonfigurasi sesi secara tambahan. Jika skrip menghasilkan kesalahan, bahkan kesalahan yang tidak mengakhiri, sesi tidak dibuat dan New-PSSession perintah gagal.

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ThreadApartmentState

Menentukan status apartemen modul utas yang akan digunakan. Nilai yang dapat diterima adalah:

  • Tidak dikenal
  • MTA
  • STA
Type:ApartmentState
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ThreadOptions

Menentukan bagaimana utas dibuat dan digunakan saat perintah berjalan dalam sesi. Nilai yang dapat diterima untuk parameter ini adalah:

  • Default
  • ReuseThread
  • UseCurrentThread
  • GunakanNewThread

Nilai defaultnya adalah UseCurrentThread.

Untuk informasi selengkapnya, lihat Enumerasi PSThreadOptions.

Type:PSThreadOptions
Accepted values:Default, UseNewThread, ReuseThread, UseCurrentThread
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-TransportOption

Menentukan opsi transportasi.

Parameter ini diperkenalkan di PowerShell 3.0.

Type:PSTransportOption
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-UseSharedProcess

Gunakan hanya satu proses untuk menghosting semua sesi yang dimulai oleh pengguna yang sama dan menggunakan konfigurasi sesi yang sama. Secara default, setiap sesi dihosting dalam prosesnya sendiri.

Parameter ini diperkenalkan di PowerShell 3.0.

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-WhatIf

Menunjukkan apa yang akan terjadi jika cmdlet berjalan. Cmdlet tidak dijalankan.

Type:SwitchParameter
Aliases:wi
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

Input

None

Anda tidak dapat menyalurkan objek ke cmdlet ini.

Output

WSManConfigContainerElement

Catatan

Cmdlet ini hanya tersedia di platform Windows.

Untuk menjalankan cmdlet ini, Anda harus memulai PowerShell dengan menggunakan opsi Jalankan sebagai administrator .

Cmdlet ini menghasilkan XML yang mewakili konfigurasi plug-in Layanan Web untuk Manajemen (WS-Management) dan mengirim XML ke WS-Management, yang mendaftarkan plug-in di komputer lokal (New-Item wsman:\localhost\plugin).

Properti objek konfigurasi sesi bervariasi menurut opsi yang diatur untuk konfigurasi sesi dan nilai opsi tersebut. Selain itu, konfigurasi sesi yang menggunakan file konfigurasi sesi memiliki properti tambahan.