New-PSSessionOption

Vytvoří objekt, který obsahuje upřesňující možnosti pro PSSession.

Syntax

New-PSSessionOption
   [-MaximumRedirection <Int32>]
   [-NoCompression]
   [-NoMachineProfile]
   [-Culture <CultureInfo>]
   [-UICulture <CultureInfo>]
   [-MaximumReceivedDataSizePerCommand <Int32>]
   [-MaximumReceivedObjectSize <Int32>]
   [-OutputBufferingMode <OutputBufferingMode>]
   [-MaxConnectionRetryCount <Int32>]
   [-ApplicationArguments <PSPrimitiveDictionary>]
   [-OpenTimeout <Int32>]
   [-CancelTimeout <Int32>]
   [-IdleTimeout <Int32>]
   [-ProxyAccessType <ProxyAccessType>]
   [-ProxyAuthentication <AuthenticationMechanism>]
   [-ProxyCredential <PSCredential>]
   [-SkipCACheck]
   [-SkipCNCheck]
   [-SkipRevocationCheck]
   [-OperationTimeout <Int32>]
   [-NoEncryption]
   [-UseUTF16]
   [-IncludePortInSPN]
   [<CommonParameters>]

Description

Rutina New-PSSessionOption vytvoří objekt, který obsahuje pokročilé možnosti relace spravované uživatelem (PSSession). Objekt můžete použít jako hodnotu Parametr SessionOption rutin, které vytvářejí PSSession, například New-PSSession, Enter-PSSessiona Invoke-Command.

Bez parametrů vygeneruje objekt, New-PSSessionOption který obsahuje výchozí hodnoty pro všechny možnosti. Vzhledem k tomu, že lze každou vlastnost upravit, můžete výsledný objekt použít jako šablonu a vytvořit standardní objekty možností pro vaši firmu.

Objekt SessionOption můžete také uložit do $PSSessionOption proměnné předvoleb. Hodnoty této proměnné vytvářejí nové výchozí hodnoty pro možnosti relace. Jsou efektivní, pokud nejsou pro relaci nastaveny žádné možnosti relace a mají přednost před možnostmi nastavenými v konfiguraci relace, ale můžete je přepsat zadáním možností relace nebo objektu SessionOption v rutině, která vytvoří relaci. Další informace o $PSSessionOption proměnné předvoleb najdete v tématu about_Preference_Variables.

Při použití SessionOption objektu v rutině, která vytvoří relaci, mají hodnoty možností relace přednost před výchozími hodnotami pro relace nastavené v $PSSessionOption proměnné předvoleb a v konfiguraci relace. Nemají však přednost před maximálními hodnotami, kvótami nebo limity nastavenými v konfiguraci relace. Další informace o konfiguracích relace najdete v tématu about_Session_Configurations.

Příklady

Příklad 1: Vytvoření výchozí možnosti relace

Tento příkaz vytvoří Objekt SessionOption s výchozími hodnotami.

New-PSSessionOption

MaximumConnectionRedirectionCount : 5
NoCompression                     : False
NoMachineProfile                  : False
ProxyAccessType                   : IEConfig
ProxyAuthentication               : Negotiate
ProxyCredential                   :
SkipCACheck                       : False
SkipCNCheck                       : False
SkipRevocationCheck               : False
OperationTimeout                  : 00:03:00
NoEncryption                      : False
UseUTF16                          : False
Culture                           :
UICulture                         :
MaximumReceivedDataSizePerCommand :
MaximumReceivedObjectSize         :
ApplicationArguments              :
OpenTimeout                       : 00:03:00
CancelTimeout                     : 00:01:00
IdleTimeout                       : 00:04:00

Příklad 2: Konfigurace relace pomocí objektu možnosti relace

Tento příklad ukazuje, jak použít SessionOption objekt ke konfiguraci relace.

$pso = New-PSSessionOption -Culture "fr-fr" -MaximumReceivedObjectSize 10MB
New-PSSession -ComputerName Server01 -SessionOption $pso

První příkaz vytvoří nový objekt SessionOption a uloží ho $pso do hodnoty proměnné. Druhý příkaz pomocí rutiny New-PSSession vytvoří relaci na vzdáleném počítači Serveru01. Příkaz používá SessionOption objekt v hodnotě $pso proměnné jako hodnotu SessionOption parametru příkazu.

Příklad 3: Spuštění interaktivní relace

Tento příkaz pomocí rutiny Enter-PSSession spustí interaktivní relaci s počítačem Se serverem 01.

Enter-PSSession -ComputerName Server01 -SessionOption (New-PSSessionOption -NoEncryption -NoCompression)

Hodnota parametru SessionOption je New-PSSessionOption příkaz, který má parametry NoEncryption a NoCompression.

Příkaz New-PSSessionOption je uzavřený v závorkách, aby se zajistilo, že se spustí před příkazem Enter-PSSession .

Příklad 4: Úprava objektu možnosti relace

Tento příklad ukazuje, že můžete upravit SessionOption objektu. Všechny vlastnosti mají hodnoty pro čtení a zápis.

$a = New-PSSessionOption
$a.OpenTimeout

Days              : 0
Hours             : 0
Minutes           : 3
Seconds           : 0
Milliseconds      : 0
Ticks             : 1800000000
TotalDays         : 0.00208333333333333
TotalHours        : 0.05
TotalMinutes      : 3
TotalSeconds      : 180
TotalMilliseconds : 180000

$a.UICulture = (Get-UICulture)
$a.OpenTimeout = (New-Timespan -Minutes 4)
$a.MaximumConnectionRedirectionCount = 1
$a

MaximumConnectionRedirectionCount : 1
NoCompression                     : False
NoMachineProfile                  : False
ProxyAccessType                   : IEConfig
ProxyAuthentication               : Negotiate
ProxyCredential                   :
SkipCACheck                       : False
SkipCNCheck                       : False
SkipRevocationCheck               : False
OperationTimeout                  : 00:03:00
NoEncryption                      : False
UseUTF16                          : False
Culture                           :
UICulture                         : en-US
MaximumReceivedDataSizePerCommand :
MaximumReceivedObjectSize         :
ApplicationArguments              :
OpenTimeout                       : 00:04:00
CancelTimeout                     : 00:01:00
IdleTimeout                       : 00:04:00

Tuto metodu použijte k vytvoření standardního objektu relace pro váš podnik a následnému vytvoření přizpůsobených verzí pro konkrétní použití.

Příklad 5: Vytvoření proměnné předvoleb

Tento příkaz vytvoří proměnnou $PSSessionOption předvoleb.

$PSSessionOption = New-PSSessionOption -OpenTimeOut 120000

$PSSessionOption Pokud je v relaci nastavena proměnná předvoleb, vytvoří výchozí hodnoty pro možnosti v relacích, které jsou vytvořeny pomocí New-PSSession, Enter-PSSessiona Invoke-Command rutiny.

Pokud chcete proměnnou $PSSessionOption zpřístupnit ve všech relacích, přidejte ji do relace PowerShellu a do profilu PowerShellu.

Další informace o $PSSessionOption proměnné předvoleb najdete v tématu about_Preference_Variables. Další informace o profilech najdete v tématu about_Profiles.

Příklad 6: Splnění požadavků na konfiguraci vzdálené relace

Tento příklad ukazuje, jak pomocí objektu SessionOption splnit požadavky na konfiguraci vzdálené relace.

$skipCN = New-PSSessionOption -SkipCNCheck
New-PSSession -ComputerName 171.09.21.207 -UseSSL -Credential Domain01\User01 -SessionOption $SkipCN

První příkaz používá rutinu New-PSSessionOption k vytvoření SessionOption objektu, který má SkipCNCheck vlastnost. Příkaz uloží výsledný objekt relace do $skipCN proměnné.

Druhý příkaz pomocí rutiny New-PSSession vytvoří novou relaci ve vzdáleném počítači. Kontrolní $skipCN proměnná se používá v hodnotě parametru SessionOption .

Vzhledem k tomu, že počítač je identifikován jeho IP adresou, hodnota parametru ComputerName neodpovídá žádnému z běžných názvů v certifikátu, který se používá pro protokol SSL (Secure Sockets Layer). V důsledku toho je vyžadována možnost SkipCNCheck .

Příklad 7: Zpřístupnění argumentů vzdálené relaci

Tento příklad ukazuje, jak pomocí parametru New-PSSessionOption ApplicationArguments rutiny zpřístupnit další data vzdálené relaci.

$team = @{Team="IT"; Use="Testing"}
$TeamOption = New-PSSessionOption -ApplicationArguments $team
$s = New-PSSession -ComputerName Server01 -SessionOption $TeamOption
Invoke-Command -Session $s {$PSSenderInfo.ApplicationArguments}

Name                 Value
----                 -----
Team                 IT
Use                  Testing
PSVersionTable       {CLRVersion, BuildVersion, PSVersion, WSManStackVersion...}

Invoke-Command -Session $s {
  if ($PSSenderInfo.ApplicationArguments.Use -ne "Testing") {
    .\logFiles.ps1
  }
  else {
    "Just testing."
  }
}

Just testing.

První příkaz vytvoří tabulku hash se dvěma klíči, týmem a použitím. Příkaz uloží tabulku hash do $team proměnné. Další informace o tabulkách hash najdete v tématu about_Hash_Tables.

Dále rutina New-PSSessionOption pomocí parametru ApplicationArguments vytvoří objekt SessionOption uložený v $team proměnné. Když New-PSSessionOption vytvoří objekt možnosti relace, automaticky převede tabulku hash v hodnotě parametru ApplicationArguments na PrimitiveDictionary , takže data lze spolehlivě přenést do vzdálené relace.

Rutina New-PSSession spustí relaci na počítači Server01. Používá parametr SessionOption k zahrnutí možností do $teamOption proměnné.

Rutina Invoke-Command ukazuje, že data v $team proměnné jsou k dispozici pro příkazy ve vzdálené relaci. Data se zobrazí ve vlastnosti $PSSenderInfo ApplicationArguments automatické proměnné.

Poslední Invoke-Command ukázka ukazuje, jak se data můžou použít.

Parametry

-ApplicationArguments

Určuje primitivní slovník , který se odešle do vzdálené relace. Příkazy a skripty ve vzdálené relaci, včetně spouštěcích skriptů v konfiguraci relace, mohou tento slovník najít ve vlastnosti $PSSenderInfo ApplicationArguments automatické proměnné. Tento parametr můžete použít k odesílání dat do vzdálené relace.

Další informace najdete v tématu about_Hash_Tables, about_Session_Configurations a about_Automatic_Variables.

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

-CancelTimeout

Určuje, jak dlouho PowerShell čeká na dokončení operace zrušení (CTRL+C) před jejím ukončením. Zadejte hodnotu v milisekundách.

Výchozí hodnota je 60000 (jedna minuta). Hodnota 0 (nula) znamená žádný časový limit; příkaz pokračuje neomezeně dlouho.

Type:Int32
Aliases:CancelTimeoutMSec
Position:Named
Default value:60000
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Culture

Určuje jazykovou verzi, která se má použít pro relaci. Zadejte název jazykové verze ve <languagecode2>-<country/regioncode2> formátu (například ja-JP), proměnnou obsahující objekt CultureInfo nebo příkaz, který získá objekt CultureInfo .

Výchozí hodnota je $Nulla jazyková verze nastavená v operačním systému se používá v relaci.

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

-IdleTimeout

Určuje, jak dlouho relace zůstane otevřená, pokud vzdálený počítač neobdrží žádnou komunikaci z místního počítače. To zahrnuje signál prezenčních signálů. Po vypršení intervalu se relace zavře.

Hodnota časového limitu nečinnosti je velmi důležitá, pokud se chcete odpojit a znovu připojit k relaci. Můžete se znovu připojit jenom v případě, že relace nevysadila časový limit.

Zadejte hodnotu v milisekundách. Minimální hodnota je 60000 (1 minuta). Maximum je hodnota Vlastnosti MaxIdleTimeoutms konfigurace relace. Výchozí hodnota -1, nenastavuje časový limit nečinnosti.

Relace používá časový limit nečinnosti nastavený v možnostech relace( pokud existuje). Pokud není nastavena žádná hodnota (-1), relace používá hodnotu IdleTimeoutMs vlastnost konfigurace relace nebo hodnota časového limitu prostředí WSMan (WSMan:\<ComputerName>\Shell\IdleTimeout), která je nejkratší.

Pokud časový limit nečinnosti nastavený v možnostech relace překročí hodnotu vlastnosti MaxIdleTimeoutMs konfigurace relace, příkaz k vytvoření relace selže.

Hodnota IdleTimeoutMs výchozí konfigurace relace Microsoft.PowerShellu je 7200000 milisekundy (2 hodiny). Hodnota MaxIdleTimeoutMs je 2147483647 milisekundy (>24 dní). Výchozí hodnota časového limitu nečinnosti prostředí WSMan (WSMan:\<ComputerName>\Shell\IdleTimeout) je 7200000 milisekund (2 hodiny).

Hodnotu časového limitu nečinnosti relace lze také změnit při odpojení od relace nebo opětovném připojení k relaci. Další informace najdete v tématech Disconnect-PSSession a Connect-PSSession.

Ve Windows PowerShellu 2.0 je 240000 výchozí hodnota parametru IdleTimeout (4 minuty).

Type:Int32
Aliases:IdleTimeoutMSec
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-IncludePortInSPN

Zahrne číslo portu do hlavního názvu služby (SPN) používaného pro ověřování protokolem Kerberos, HTTP://<ComputerName>:5985například . Tato možnost umožňuje klientovi, který používá jiný než výchozí hlavní název služby (SPN) k ověření na vzdáleném počítači, který používá ověřování protokolem Kerberos.

Tato možnost je určená pro podniky, ve kterých pod různými uživatelskými účty běží více služeb, které podporují ověřování protokolem Kerberos. Například aplikace služby IIS, která umožňuje ověřování protokolem Kerberos, může vyžadovat registraci výchozího hlavního názvu služby (SPN) na uživatelský účet, který se liší od účtu počítače. V takových případech nemůže vzdálené komunikace Prostředí PowerShell používat k ověření protokol Kerberos, protože vyžaduje hlavní název služby (SPN), který je zaregistrovaný v účtu počítače. K vyřešení tohoto problému můžou správci vytvořit různé hlavní názvy služeb (SPN), například pomocí Setspn.exe, které jsou zaregistrované v různých uživatelských účtech a mohou mezi nimi rozlišovat zahrnutím čísla portu do hlavního názvu služby (SPN).

Další informace najdete v tématu Přehled služby Setspn.

Tento parametr byl představen ve Windows PowerShellu 3.0.

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

-MaxConnectionRetryCount

Určuje, kolikrát se PowerShell pokusí připojit k cílovému počítači, pokud se aktuální pokus nezdaří kvůli problémům se sítí. Výchozí hodnota je 5.

Tento parametr byl přidán pro PowerShell verze 5.0.

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

-MaximumReceivedDataSizePerCommand

Určuje maximální počet bajtů, které může místní počítač přijímat ze vzdáleného počítače v jednom příkazu. Zadejte hodnotu v bajtech. Ve výchozím nastavení neexistuje žádný limit velikosti dat.

Tato možnost je navržená tak, aby chránila prostředky v klientském počítači.

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

-MaximumReceivedObjectSize

Určuje maximální velikost objektu, který může místní počítač přijímat ze vzdáleného počítače. Tato možnost je navržená tak, aby chránila prostředky v klientském počítači. Zadejte hodnotu v bajtech.

Pokud tento parametr vynecháte, v prostředí Windows PowerShell 2.0 neexistuje žádný limit velikosti objektu. Počínaje windows PowerShellem 3.0, pokud tento parametr vynecháte, je 209715200 výchozí hodnota bajty (nebo 200MB).

Type:Int32
Position:Named
Default value:209715200
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-MaximumRedirection

Určuje, kolikrát PowerShell přesměruje připojení na alternativní identifikátor URI (Uniform Resource Identifier) před selháním připojení. Výchozí hodnota je 5. Hodnota 0 (nula) brání veškerému přesměrování.

Tato možnost se používá v relaci pouze v případě, že se v příkazu, který vytvoří relaci, použije parametr AllowRedirection .

Type:Int32
Position:Named
Default value:5
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-NoCompression

Vypne kompresi paketů v relaci. Komprese používá více cyklů procesoru, ale zrychlová přenos.

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

-NoEncryption

Vypne šifrování dat.

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

-NoMachineProfile

Zabrání načtení profilu uživatele systému Windows. V důsledku toho může být relace vytvořena rychleji, ale nastavení registru specifické pro uživatele, například proměnné prostředí a certifikáty, nejsou v relaci k dispozici.

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

-OpenTimeout

Určuje, jak dlouho klientský počítač čeká na navázání připojení relace. Po vypršení intervalu se příkaz pro navázání připojení nezdaří. Zadejte hodnotu v milisekundách.

Výchozí hodnota je 180000 (3 minuty). Hodnota 0 (nula) znamená žádný časový limit; příkaz pokračuje neomezeně dlouho.

Type:Int32
Aliases:OpenTimeoutMSec
Position:Named
Default value:180000 (3 minutes)
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-OperationTimeout

Určuje maximální dobu čekání WinRM na pozitivní testy připojení z živého připojení před zahájením časového limitu připojení. Další informace o WinRM naleznete v dokumentaci ke vzdálené správě systému Windows.

OperationTimeout neukládáčasový limit pro příkazy nebo procesy spuštěné ve vzdálené relaci a nemá vliv na jiné protokoly vzdálené komunikace, jako je SSH.

Výchozí hodnota je 180000 (3 minuty). Hodnota 0 (nula) znamená žádný časový limit.

Type:Int32
Aliases:OperationTimeoutMSec
Position:Named
Default value:180000 (3 minutes)
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-OutputBufferingMode

Určuje, jak se výstup příkazu spravuje v odpojených relacích, když se výstupní vyrovnávací paměť zaplní.

Pokud výstupní režim ukládání do vyrovnávací paměti není nastaven v relaci nebo v konfiguraci relace, výchozí hodnota je Block. Uživatelé mohou také změnit režim ukládání výstupu do vyrovnávací paměti při odpojení relace.

Pokud tento parametr vynecháte, hodnota OutputBufferingMode objektu SessionOption je None. Hodnota Block nebo Drop přepisuje možnost přenosu režimu vyrovnávací paměti výstupu nastavená v konfiguraci relace. Tento parametr přijímá tyto hodnoty:

  • Block. Pokud je výstupní vyrovnávací paměť plná, spuštění se pozastaví, dokud se vyrovnávací paměť nesmaže.
  • Drop. Jakmile je výstupní vyrovnávací paměť plná, provádění bude pokračovat. Při ukládání nového výstupu se nejstarší výstup zahodí.
  • None. Není zadán žádný režim ukládání výstupu do vyrovnávací paměti.

Další informace o možnosti přenosu režimu ukládání výstupu do vyrovnávací paměti naleznete v tématu New-PSTransportOption.

Tento parametr byl představen ve Windows PowerShellu 3.0.

Type:OutputBufferingMode
Accepted values:None, Drop, Block
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ProxyAccessType

Určuje, který mechanismus se používá k překladu názvu hostitele. Tento parametr přijímá tyto hodnoty:

  • IEConfig
  • WinHttpConfig
  • AutoDetect
  • NoProxyServer
  • None

Výchozí hodnota je None.

Informace o hodnotách tohoto parametru naleznete v tématu ProxyAccessType Výčet.

Type:ProxyAccessType
Accepted values:None, IEConfig, WinHttpConfig, AutoDetect, NoProxyServer
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ProxyAuthentication

Určuje metodu ověřování, která se používá pro překlad proxy serveru. Tento parametr přijímá tyto hodnoty:

  • Basic
  • Digest
  • Negotiate

Výchozí hodnota je Negotiate.

Další informace o hodnotách tohoto parametru naleznete v tématu AuthenticationMechanism – výčet.

Type:AuthenticationMechanism
Accepted values:Default, Basic, Negotiate, NegotiateWithImplicitCredential, Credssp, Digest, Kerberos
Position:Named
Default value:Negotiate
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ProxyCredential

Určuje přihlašovací údaje, které se mají použít pro ověřování proxy serveru. Zadejte proměnnou obsahující objekt PSCredential nebo příkaz, který získá objekt PSCredential , například Get-Credential příkaz. Pokud tato možnost není nastavená, nejsou zadány žádné přihlašovací údaje.

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

-SkipCACheck

Určuje, že když se připojí přes PROTOKOL HTTPS, klient neověří, že certifikát serveru je podepsaný důvěryhodnou certifikační autoritou (CA).

Tuto možnost použijte pouze v případě, že je vzdálený počítač důvěryhodný pomocí jiného mechanismu, například pokud je vzdálený počítač součástí sítě, která je fyzicky zabezpečená a izolovaná nebo pokud je vzdálený počítač uveden jako důvěryhodný hostitel v konfiguraci WinRM.

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

-SkipCNCheck

Určuje, že běžný název certifikátu (CN) serveru nemusí odpovídat názvu hostitele serveru. Tato možnost se používá pouze ve vzdálených operacích, které používají protokol HTTPS.

Tuto možnost použijte jenom pro důvěryhodné počítače.

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

-SkipRevocationCheck

Neověřuje stav odvolání certifikátu serveru.

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

-UICulture

Určuje jazykovou verzi uživatelského rozhraní, která se má použít pro relaci.

Mezi platné hodnoty patří:

  • Název jazykové verze ve <languagecode2>-<country/regioncode2> formátu, například ja-JP
  • Proměnná, která obsahuje objekt CultureInfo
  • Příkaz, který získá objekt CultureInfo , například Get-Culture

Výchozí hodnota je $nulla jazyková verze uživatelského rozhraní, která je nastavena v operačním systému při vytvoření relace.

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

-UseUTF16

Označuje, že tato rutina kóduje požadavek ve formátu UTF16 místo formátu UTF8.

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

Vstupy

None

Do této rutiny nemůžete roušit objekty.

Výstupy

PSSessionOption

Poznámky

Pokud parametr SessionOption není použit v příkazu k vytvoření PSSession, možnosti relace jsou určeny hodnotami $PSSessionOption vlastností proměnné předvolby, pokud je nastavena. Další informace o $PSSessionOption proměnné najdete v tématu about_Preference_Variables.

Vlastnosti objektu konfigurace relace se liší podle možností nastavených pro konfiguraci relace a hodnot těchto možností. Konfigurace relací, které používají konfigurační soubor relace, mají také další vlastnosti.