New-PSSessionOption

  • Referens
Modul:
Microsoft.PowerShell.Core

Skapar ett objekt som innehåller avancerade alternativ för en 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

Cmdleten New-PSSessionOption skapar ett objekt som innehåller avancerade alternativ för en användarhanterad session (PSSession). Du kan använda objektet som värdet för parametern SessionOption för cmdletar som skapar en PSSession, till New-PSSessionexempel , Enter-PSSessionoch Invoke-Command.

Utan parametrar New-PSSessionOption genererar ett objekt som innehåller standardvärdena för alla alternativ. Eftersom varje egenskap kan redigeras kan du använda det resulterande objektet som en mall och skapa standardalternativobjekt för ditt företag.

Du kan också spara ett SessionOption-objekt i inställningsvariabeln $PSSessionOption . Värdena för den här variabeln etablerar nya standardvärden för sessionsalternativen. De är effektiva när inga sessionsalternativ har angetts för sessionen och de har företräde framför de alternativ som anges i sessionskonfigurationen, men du kan åsidosätta dem genom att ange sessionsalternativ eller ett SessionOption-objekt i en cmdlet som skapar en session. Mer information om inställningsvariabeln finns i $PSSessionOption about_Preference_Variables.

När du använder ett SessionOption-objekt i en cmdlet som skapar en session har sessionsalternativvärdena företräde framför standardvärdena för sessioner som angetts i $PSSessionOption inställningsvariabeln och i sessionskonfigurationen. De har dock inte företräde framför de högsta värden, kvoter eller gränser som anges i sessionskonfigurationen. För ytterligare information om sessionskonfigurationer, se about_Session_Configurations.

Exempel

Exempel 1: Skapa ett standardalternativ för sessioner

Det här kommandot skapar ett SessionOption-objekt med standardvärdena.

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

Exempel 2: Konfigurera en session med hjälp av ett sessionsalternativobjekt

Det här exemplet visar hur du använder ett SessionOption-objekt för att konfigurera en session.

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

Det första kommandot skapar ett nytt SessionOption-objekt och sparar det i värdet för variabeln $pso . Det andra kommandot använder cmdleten New-PSSession för att skapa en session på server01-fjärrdatorn. Kommandot använder Objektet SessionOption i värdet för variabeln $pso som värdet för parametern SessionOption för kommandot.

Exempel 3: Starta en interaktiv session

Det här kommandot använder cmdleten Enter-PSSession för att starta en interaktiv session med Server01-datorn.

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

Värdet för parametern SessionOption är ett New-PSSessionOption kommando som har parametrarna NoEncryption och NoCompression .

Kommandot New-PSSessionOption omges av parenteser för att se till att det körs före Enter-PSSession kommandot.

Exempel 4: Ändra ett sessionsalternativobjekt

Det här exemplet visar att du kan ändra Objektet SessionOption . Alla egenskaper har läs-/skrivvärden.

$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

Använd den här metoden för att skapa ett standardsessionsobjekt för ditt företag och skapa sedan anpassade versioner av det för specifika användningsområden.

Exempel 5: Skapa en inställningsvariabel

Det här kommandot skapar en $PSSessionOption inställningsvariabel.

$PSSessionOption = New-PSSessionOption -OpenTimeOut 120000

$PSSessionOption När inställningsvariabeln anges i sessionen upprättas standardvärden för alternativ i de sessioner som skapas med New-PSSessioncmdletarna , Enter-PSSessionoch Invoke-Command .

Om du vill göra variabeln $PSSessionOption tillgänglig i alla sessioner lägger du till den i PowerShell-sessionen och i din PowerShell-profil.

Mer information om inställningsvariabeln finns i $PSSessionOption about_Preference_Variables. Mer information om profiler finns i about_Profiles.

Exempel 6: Uppfylla kraven för en fjärrsessionskonfiguration

Det här exemplet visar hur du använder ett SessionOption-objekt för att uppfylla kraven för en fjärrsessionskonfiguration.

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

Det första kommandot använder cmdleten New-PSSessionOption för att skapa ett SessionOption-objekt som har egenskapen SkipCNCheck . Kommandot sparar det resulterande sessionsobjektet i variabeln $skipCN .

Det andra kommandot använder cmdleten New-PSSession för att skapa en ny session på en fjärrdator. Kontrollvariabeln $skipCN används i värdet för parametern SessionOption .

Eftersom datorn identifieras av dess IP-adress matchar inte värdet för parametern ComputerName något av de vanliga namnen i certifikatet som används för Secure Sockets Layer (SSL). Därför krävs alternativet SkipCNCheck .

Exempel 7: Gör argument tillgängliga för en fjärrsession

Det här exemplet visar hur du använder parametern ApplicationArguments för cmdleten New-PSSessionOption för att göra ytterligare data tillgängliga för fjärrsessionen.

$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.

Det första kommandot skapar en hash-tabell med två nycklar, Team och Use. Kommandot sparar hash-tabellen i variabeln $team . Mer information om hash-tabeller finns i about_Hash_Tables.

Därefter skapar cmdleten New-PSSessionOption , med hjälp av parametern ApplicationArguments , ett SessionOption-objekt som sparats i variabeln $team . När New-PSSessionOption du skapar sessionsalternativobjektet konverteras hash-tabellen automatiskt i värdet för parametern ApplicationArguments till en PrimitiveDictionary så att data kan överföras på ett tillförlitligt sätt till fjärrsessionen.

Cmdleten New-PSSession startar en session på Server01-datorn. Den använder parametern SessionOption för att inkludera alternativen i variabeln $teamOption .

Cmdleten Invoke-Command visar att data i variabeln $team är tillgängliga för kommandon i fjärrsessionen. Data visas i egenskapen ApplicationArguments för den $PSSenderInfo automatiska variabeln.

Den sista Invoke-Command visar hur data kan användas.

Parametrar

-ApplicationArguments

Anger en PrimitiveDictionary som skickas till fjärrsessionen. Kommandon och skript i fjärrsessionen, inklusive startskript i sessionskonfigurationen, kan hitta den här ordlistan i egenskapen ApplicationArguments för den $PSSenderInfo automatiska variabeln. Du kan använda den här parametern för att skicka data till fjärrsessionen.

Mer information finns i about_Hash_Tables, about_Session_Configurations och about_Automatic_Variables.

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

-CancelTimeout

Avgör hur länge PowerShell väntar på att en avbruten åtgärd (CTRL+C) ska slutföras innan den avslutas. Ange ett värde i millisekunder.

Standardvärdet är 60000 (en minut). 0 Värdet (noll) innebär ingen tidsgräns. Kommandot fortsätter på obestämd tid.

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

-Culture

Anger vilken kultur som ska användas för sessionen. Ange ett kulturnamn i <languagecode2>-<country/regioncode2> format (till exempel ja-JP), en variabel som innehåller ett CultureInfo-objekt eller ett kommando som hämtar ett CultureInfo-objekt .

Standardvärdet är $Null, och kulturen som anges i operativsystemet används i sessionen.

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

-IdleTimeout

Avgör hur länge sessionen är öppen om fjärrdatorn inte tar emot någon kommunikation från den lokala datorn. Detta inkluderar pulsslagssignalen. När intervallet upphör att gälla stängs sessionen.

Tidsgränsvärdet för inaktivitet är av stor betydelse om du tänker koppla från och återansluta till en session. Du kan bara återansluta om sessionen inte har överskridit tidsgränsen.

Ange ett värde i millisekunder. Minimivärdet är 60000 (1 minut). Maxvärdet är värdet för egenskapen MaxIdleTimeoutms för sessionskonfigurationen. Standardvärdet, -1, anger inte tidsgränsen för inaktivitet.

Sessionen använder tidsgränsen för inaktivitet som anges i sessionsalternativen, om det finns några. Om ingen anges (-1) använder sessionen värdet för egenskapen IdleTimeoutMs för sessionskonfigurationen eller tidsgränsvärdet för WSMan-gränssnittet (WSMan:\<ComputerName>\Shell\IdleTimeout), beroende på vilket som är kortast.

Om tidsgränsen för inaktivitet i sessionsalternativen överskrider värdet för egenskapen MaxIdleTimeoutMs för sessionskonfigurationen misslyckas kommandot för att skapa en session.

Värdet för IdleTimeoutMs för standardkonfigurationen för Microsoft.PowerShell-sessioner är 7200000 millisekunder (2 timmar). Dess MaxIdleTimeoutMs-värde är 2147483647 millisekunder (>24 dagar). Standardvärdet för tidsgränsen för inaktivitet i WSMan-gränssnittet (WSMan:\<ComputerName>\Shell\IdleTimeout) är 7200000 millisekunder (2 timmar).

Tidsgränsvärdet för inaktivitet för en session kan också ändras när du kopplar från en session eller återansluter till en session. Mer information finns i Disconnect-PSSession och Connect-PSSession.

I Windows PowerShell 2.0 är 240000 standardvärdet för parametern IdleTimeout (4 minuter).

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

-IncludePortInSPN

Innehåller portnumret i tjänstens huvudnamn (SPN) som används för Kerberos-autentisering, till exempel HTTP://<ComputerName>:5985. Med det här alternativet kan en klient som använder ett SPN som inte är standard autentiseras mot en fjärrdator som använder Kerberos-autentisering.

Alternativet är utformat för företag där flera tjänster som stöder Kerberos-autentisering körs under olika användarkonton. Till exempel kan ett IIS-program som tillåter Kerberos-autentisering kräva att standard-SPN registreras till ett användarkonto som skiljer sig från datorkontot. I sådana fall kan PowerShell-fjärrkommunikation inte använda Kerberos för att autentisera eftersom det kräver ett SPN som är registrerat på datorkontot. För att lösa det här problemet kan administratörer skapa olika SPN: er, till exempel genom att använda Setspn.exe, som är registrerade på olika användarkonton och kan skilja mellan dem genom att inkludera portnumret i SPN.

Mer information finns i Översikt över Setspn.

Den här parametern introducerades i Windows PowerShell 3.0.

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

-MaxConnectionRetryCount

Anger antalet gånger som PowerShell försöker upprätta en anslutning till en måldator om det aktuella försöket misslyckas på grund av nätverksproblem. Standardvärdet är 5.

Den här parametern har lagts till för PowerShell version 5.0.

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

-MaximumReceivedDataSizePerCommand

Anger det maximala antalet byte som den lokala datorn kan ta emot från fjärrdatorn i ett enda kommando. Ange ett värde i byte. Som standard finns det ingen datastorleksgräns.

Det här alternativet är utformat för att skydda resurserna på klientdatorn.

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

-MaximumReceivedObjectSize

Anger den maximala storleken på ett objekt som den lokala datorn kan ta emot från fjärrdatorn. Det här alternativet är utformat för att skydda resurserna på klientdatorn. Ange ett värde i byte.

Om du utelämnar den här parametern i Windows PowerShell 2.0 finns det ingen storleksgräns för objekt. Från och med Windows PowerShell 3.0, om du utelämnar den här parametern, är 209715200 standardvärdet byte (eller 200MB).

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

-MaximumRedirection

Avgör hur många gånger PowerShell omdirigerar en anslutning till en alternativ URI (Uniform Resource Identifier) innan anslutningen misslyckas. Standardvärdet är 5. Ett värde på 0 (noll) förhindrar all omdirigering.

Det här alternativet används endast i sessionen när parametern AllowRedirection används i kommandot som skapar sessionen.

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

-NoCompression

Inaktiverar paketkomprimering i sessionen. Komprimering använder fler processorcykler, men det gör överföringen snabbare.

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

-NoEncryption

Inaktiverar datakryptering.

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

-NoMachineProfile

Förhindrar inläsning av användarens Windows-användarprofil. Därför kan sessionen skapas snabbare, men användarspecifika registerinställningar, objekt som miljövariabler och certifikat är inte tillgängliga i sessionen.

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

-OpenTimeout

Avgör hur länge klientdatorn väntar på att sessionsanslutningen ska upprättas. När intervallet upphör att gälla misslyckas kommandot för att upprätta anslutningen. Ange ett värde i millisekunder.

Standardvärdet är 180000 (3 minuter). 0 Värdet (noll) innebär ingen tidsgräns. Kommandot fortsätter på obestämd tid.

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

-OperationTimeout

Avgör hur länge WinRM väntar på positiva anslutningstester från en live-anslutning innan tidsgränsen för anslutningen initieras. Mer information om WinRM finns i dokumentationen för Windows Remote Management.

OperationTimeouthar ingen tidsgräns för kommandon eller processer som körs i en fjärrsession och påverkar inte andra fjärrkommunikationsprotokoll som SSH.

Standardvärdet är 180000 (3 minuter). 0 Värdet (noll) innebär ingen tidsgräns.

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

-OutputBufferingMode

Avgör hur kommandoutdata hanteras i frånkopplade sessioner när utdatabufferten blir full.

Om utdatabuffertningsläget inte har angetts i sessionen eller i sessionskonfigurationen är Blockstandardvärdet . Användare kan också ändra utdatabuffertningsläget när sessionen kopplas från.

Om du utelämnar den här parametern är värdet för Objektet OutputBufferingMode för SessionOption .None Ett värde för Block eller Drop åsidosätter transportalternativet för utdatabuffertläge som angetts i sessionskonfigurationen. De acceptabla värdena för den här parametern är:

  • Block. När utdatabufferten är full pausas körningen tills bufferten är klar.
  • Drop. När utdatabufferten är full fortsätter körningen. När nya utdata sparas ignoreras de äldsta utdata.
  • None. Inget utdatabuffertningsläge har angetts.

Mer information om transportalternativet för utdatabuffertningsläge finns i New-PSTransportOption.

Den här parametern introducerades i Windows PowerShell 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

Avgör vilken mekanism som används för att matcha värdnamnet. De acceptabla värdena för den här parametern är:

  • IEConfig
  • WinHttpConfig
  • AutoDetect
  • NoProxyServer
  • None

Standardvärdet är None.

Information om värdena för den här parametern finns i ProxyAccessType-uppräkning.

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

Anger den autentiseringsmetod som används för proxymatchning. De acceptabla värdena för den här parametern är:

  • Basic
  • Digest
  • Negotiate

Standardvärdet är Negotiate.

Mer information om värdena för den här parametern finns i AuthenticationMechanism Enumeration.

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

Anger de autentiseringsuppgifter som ska användas för proxyautentisering. Ange en variabel som innehåller ett PSCredential-objekt eller ett kommando som hämtar ett PSCredential-objekt , till exempel ett Get-Credential kommando. Om det här alternativet inte har angetts anges inga autentiseringsuppgifter.

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

-SkipCACheck

Anger att när den ansluter via HTTPS verifierar klienten inte att servercertifikatet har signerats av en betrodd certifikatutfärdare (CA).

Använd endast det här alternativet när fjärrdatorn är betrodd med hjälp av en annan mekanism, till exempel när fjärrdatorn är en del av ett nätverk som är fysiskt säkert och isolerat eller när fjärrdatorn anges som en betrodd värd i en WinRM-konfiguration.

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

-SkipCNCheck

Anger att certifikatets gemensamma namn (CN) på servern inte behöver matcha serverns värdnamn. Det här alternativet används endast i fjärråtgärder som använder HTTPS-protokollet.

Använd endast det här alternativet för betrodda datorer.

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

-SkipRevocationCheck

Verifierar inte återkallningsstatusen för servercertifikatet.

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

-UICulture

Anger den användargränssnittskultur som ska användas för sessionen.

Giltiga värden:

  • Ett kulturnamn i <languagecode2>-<country/regioncode2> format, till exempel ja-JP
  • En variabel som innehåller ett CultureInfo-objekt
  • Ett kommando som hämtar ett CultureInfo-objekt , till exempel Get-Culture

Standardvärdet är $null, och den användargränssnittskultur som anges i operativsystemet när sessionen skapas.

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

-UseUTF16

Anger att denna cmdlet kodar begäran i UTF16-format i stället för UTF8-format.

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

Indata

None

Du kan inte skicka objekt till den här cmdleten.

Utdata

PSSessionOption

Kommentarer

Om parametern SessionOption inte används i ett kommando för att skapa en PSSession bestäms sessionsalternativen av egenskapsvärdena för $PSSessionOption inställningsvariabeln, om den anges. Mer information om variabeln finns i $PSSessionOption about_Preference_Variables.

Egenskaperna för ett sessionskonfigurationsobjekt varierar med de alternativ som angetts för sessionskonfigurationen och värdena för dessa alternativ. Sessionskonfigurationer som använder en sessionskonfigurationsfil har dessutom ytterligare egenskaper.