New-PSSessionOption

  • Reference
Modul:
Microsoft.PowerShell.Core

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 rozšířené možnosti pro relaci spravovanou uživatelem (PSSession). Objekt můžete použít jako hodnotu parametru SessionOption rutin, které vytvářejí instanci 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 upravit každou vlastnost, můžete výsledný objekt použít jako šablonu a vytvořit standardní objekty možností pro váš podnik.

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 účinné, 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á relaci vytvoří. Další informace o proměnné předvoleb najdete v $PSSessionOption tématu about_Preference_Variables.

Když použijete objekt SessionOption v rutině, která vytváří 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 omezeními 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 objekt SessionOption 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 Server01. Příkaz používá objekt SessionOption v hodnotě $pso proměnné jako hodnotu parametru SessionOption příkazu.

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

Tento příkaz používá rutinu Enter-PSSession ke spuštění interaktivní relace s počítačem Server01.

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žností 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 poté vytvořte jeho přizpůsobenou verzi pro konkrétní použití.

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

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

$PSSessionOption = New-PSSessionOption -OpenTimeOut 120000

$PSSessionOption Když je proměnná předvoleb nastavená v relaci, vytvoří výchozí hodnoty pro možnosti v relacích vytvořených pomocí New-PSSessionrutin , Enter-PSSessiona Invoke-Command .

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

Další informace o proměnné předvoleb najdete v $PSSessionOption 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 použít objekt SessionOption ke splnění požadavků 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í objektu SessionOption , který má vlastnost SkipCNCheck . Příkaz uloží výsledný objekt relace do $skipCN proměnné .

Druhý příkaz použije rutinu New-PSSession k vytvoření nové relace na vzdáleném počítači. Kontrolní proměnná $skipCN se používá v hodnotě parametru SessionOption .

Vzhledem k tomu, že počítač je identifikován svou 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 se vyžaduje možnost SkipCNCheck .

Příklad 7: Zpřístupnění argumentů pro vzdálenou relaci

Tento příklad ukazuje, jak použít parametr ApplicationArguments rutiny New-PSSessionOption k zpřístupnění dalších dat pro vzdálenou 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ří zatřiďovací tabulku se dvěma klíči : Team (Tým) a Use (Použít). Příkaz uloží tabulku hash do $team proměnné . Další informace o zatřiďovacích tabulkách najdete v tématu about_Hash_Tables.

Dále rutina New-PSSessionOption pomocí parametru ApplicationArguments vytvoří objekt SessionOption uložený v $team proměnné . Při New-PSSessionOption vytvoření objektu session option automaticky převede tabulku hash v hodnotě parametru ApplicationArguments na PrimitiveDictionary , aby data bylo možné 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 dostupná pro příkazy ve vzdálené relaci. Data se zobrazí ve vlastnosti $PSSenderInfoApplicationArguments automatické proměnné.

Ve finále Invoke-Command se dozvíte, jak se data můžou použít.

Parametry

-ApplicationArguments

Určuje PrimitiveDictionary , 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 najít tento slovník ve vlastnosti $PSSenderInfoApplicationArguments 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
Accept pipeline input:False
Accept wildcard characters:False

-CancelTimeout

Určuje, jak dlouho PowerShell čeká na dokončení operace zrušení (CTRL+C), než ji ukončí. Zadejte hodnotu v milisekundách.

Výchozí hodnota je 60000 (jedna minuta). Hodnota 0 (nula) znamená žádný časový limit. Příkaz pokračuje donekonečna.

Type:Int32
Aliases:CancelTimeoutMSec
Position:Named
Default value:60000
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, která obsahuje objekt CultureInfo , nebo příkaz, který získá objekt CultureInfo .

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

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

-IdleTimeout

Určuje, jak dlouho zůstane relace otevřená, pokud vzdálený počítač neobdrží žádnou komunikaci z místního počítače. To zahrnuje i signál prezenčního signálu. 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 časový limit relace nevyšel.

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

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

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

Hodnota IdleTimeoutMsvýchozího Microsoft. Konfigurace relace PowerShellu je 7200000 v milisekundách (2 hodiny). Jeho hodnota MaxIdleTimeoutMs je 2147483647 milisekund (>24 dní). Výchozí hodnota časového limitu nečinnosti prostředí WSMan (WSMan:\<ComputerName>\Shell\IdleTimeout) je 7200000 milisekundy (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 naleznete v tématech Disconnect-PSSession a Connect-PSSession.

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

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

-IncludePortInSPN

Zahrnuje číslo portu v hlavním názvu služby (SPN) používaném 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), provést ověření vůči vzdálenému počítači, který používá ověřování protokolem Kerberos.

Možnost je určená pro podniky, kde 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) k uživatelskému účtu, který se liší od účtu počítače. V takových případech nemůže vzdálené komunikace PowerShellu k ověření použít protokol Kerberos, protože vyžaduje hlavní název služby (SPN), který je zaregistrovaný k účtu počítače. Pokud chcete tento problém vyřešit, můžou správci vytvořit různé hlavní názvy služby (SPN), například pomocí Setspn.exe, které jsou zaregistrované k různým uživatelským účtům a můžou mezi nimi rozlišovat zahrnutím čísla portu do hlavního názvu služby (SPN).

Další informace najdete v tématu Přehled setspn.

Tento parametr byl zaveden v Windows PowerShell 3.0.

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

-MaxConnectionRetryCount

Určuje, kolikrát se PowerShell pokusí vytvořit připojení k cílovému počítači, pokud aktuální pokus selže 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
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 jedním příkazem. Zadejte hodnotu v bajtech. Ve výchozím nastavení neexistuje žádný limit velikosti dat.

Tato možnost je určená k ochraně prostředků v klientském počítači.

Type:Int32
Position:Named
Default value:None
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 určená k ochraně prostředků v klientském počítači. Zadejte hodnotu v bajtech.

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

Type:Int32
Position:Named
Default value:209715200
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), než připojení selže. Výchozí hodnota je 5. Hodnota 0 (nula) zabraňuje veškerému přesměrování.

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

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

-NoCompression

Vypne kompresi paketů v relaci. Komprese využívá více cyklů procesoru, ale přenos je rychlejší.

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

-NoEncryption

Vypne šifrování dat.

Type:SwitchParameter
Position:Named
Default value:None
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, položky, jako jsou proměnné prostředí, a certifikáty nejsou v relaci k dispozici.

Type:SwitchParameter
Position:Named
Default value: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 donekonečna.

Type:Int32
Aliases:OpenTimeoutMSec
Position:Named
Default value:180000 (3 minutes)
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 najdete v dokumentaci ke vzdálené správě systému Windows.

OperationTimeoutneuklá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)
Accept pipeline input:False
Accept wildcard characters:False

-OutputBufferingMode

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

Pokud režim ukládání výstupu do vyrovnávací paměti není v relaci nebo v konfiguraci relace nastavený, 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 odpojování relace.

Pokud tento parametr vynecháte, hodnota OutputBufferingModeobjektu SessionOption je None. Hodnota Block nebo Drop přepisuje možnost přenosu výstupního režimu ukládání do vyrovnávací paměti nastavenou v konfiguraci relace. Tento parametr přijímá tyto hodnoty:

  • Block. Když je výstupní vyrovnávací paměť plná, provádění se pozastaví, dokud se vyrovnávací paměť nesmaže.
  • Drop. Když je výstupní vyrovnávací paměť plná, provádění pokračuje. Při uložení 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 v režimu výstupní vyrovnávací paměti najdete v tématu New-PSTransportOption.

Tento parametr byl zaveden v Windows PowerShell 3.0.

Type:OutputBufferingMode
Accepted values:None, Drop, Block
Position:Named
Default value:None
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 najdete v tématu ProxyAccessType – výčet.

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

-ProxyAuthentication

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

  • Basic
  • Digest
  • Negotiate

Výchozí hodnota je Negotiate.

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

Type:AuthenticationMechanism
Accepted values:Default, Basic, Negotiate, NegotiateWithImplicitCredential, Credssp, Digest, Kerberos
Position:Named
Default value:Negotiate
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. Zadejte proměnnou, která obsahuje 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
Accept pipeline input:False
Accept wildcard characters:False

-SkipCACheck

Určuje, že při připojení přes 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 vzdálený počítač je důvěryhodný pomocí jiného mechanismu, například když je vzdálený počítač součástí fyzicky zabezpečené a izolované sítě nebo když je vzdálený počítač uvedený jako důvěryhodný hostitel v konfiguraci WinRM.

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

-SkipCNCheck

Určuje, že běžný název certifikátu (CN) serveru se nemusí shodovat s názvem 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
Accept pipeline input:False
Accept wildcard characters:False

-SkipRevocationCheck

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

Type:SwitchParameter
Position:Named
Default value: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 $null, a 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
Accept pipeline input:False
Accept wildcard characters:False

-UseUTF16

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

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

Vstupy

None

Objekty nelze do této rutiny převést.

Výstupy

PSSessionOption

Poznámky

Pokud parametr SessionOption není použit v příkazu k vytvoření PSSession, jsou možnosti relace určeny hodnotami $PSSessionOption vlastností proměnné předvolby, pokud je nastavena. Další informace o proměnné najdete v $PSSessionOption 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.