New-PSSessionConfigurationFile

New-PSSessionConfigurationFile
    [-Path] <String>
    [-SchemaVersion <Version>]
    [-Guid <Guid>]
    [-Author <String>]
    [-CompanyName <String>]
    [-Copyright <String>]
    [-Description <String>]
    [-PowerShellVersion <Version>]
    [-SessionType <SessionType>]
    [-ModulesToImport <Object[]>]
    [-AssembliesToLoad <String[]>]
    [-VisibleAliases <String[]>]
    [-VisibleCmdlets <String[]>]
    [-VisibleFunctions <String[]>]
    [-VisibleProviders <String[]>]
    [-AliasDefinitions <Hashtable[]>]
    [-FunctionDefinitions <Hashtable[]>]
    [-VariableDefinitions <Object>]
    [-EnvironmentVariables <Object>]
    [-TypesToProcess <String[]>]
    [-FormatsToProcess <String[]>]
    [-LanguageMode <PSLanguageMode>]
    [-ExecutionPolicy <ExecutionPolicy>]
    [-ScriptsToProcess <String[]>]
    [<CommonParameters>]

New-PSSessionConfigurationFile コマンドレットは、セッション構成と、セッション構成を使用して作成されるセッションの環境を定義する設定のファイルを作成します。 セッション構成でファイルを使用するには、 または Register-PSSessionConfiguration コマンドレットの Set-PSSessionConfiguration パラメーターを使用します。

New-PSSessionConfigurationFile 作成されるセッション構成ファイルは、セッション構成のプロパティと値のハッシュ テーブルを含む、人間が判読できるテキスト ファイルです。 ファイルのファイル名拡張子は .pssc です。

New-PSSessionConfigurationFile パラメーターを除き、 のすべてのパラメーターは省略可能です。 パラメーターを省略した場合、セッション構成ファイル内の対応するキーは、パラメーターの説明に記載されている場合を除き、コメント アウトされます。

セッション構成 (エンドポイントとも呼ばれます) は、コンピューターに接続する PowerShell セッション (PSSessions) の環境を定義するローカル コンピューター上の設定のコレクションです。 すべての PSSessionsions セッション構成を使用します。 特定のセッション構成を指定するには、 コマンドレットなどのセッションを作成するコマンドレットの New-PSSession パラメーターを使用します。

セッション構成ファイルを使用すると、複雑なスクリプトやコード アセンブリなしでセッション構成を簡単に定義できます。 ファイル内の設定は、オプションのスタートアップ スクリプトと、セッション構成内のすべてのアセンブリと共に使用されます。

セッション構成とセッション構成ファイルの詳細については、「about_Session_Configurations と about_Session_Configuration_Files」を参照してください。

このコマンドレットは、PowerShell 3.0 で導入されました。

この例では、言語なしのセッションを使用する方法と効果を示します。

手順は次のとおりです。

1. 新しい構成ファイルを作成します。
2. 構成を登録します。
3. 構成を使用する新しいセッションを作成します。
4. その新しいセッションでコマンドを実行します。

この例のコマンドを実行するには、[管理者として実行] オプションを使用して PowerShell を起動します。 このオプションは、Register-PSSessionConfiguration コマンドレットを実行するために必要です。

New-PSSessionConfigurationFile -Path .\NoLanguage.pssc -LanguageMode NoLanguage
Register-PSSessionConfiguration -Path .\NoLanguage.pssc -Name NoLanguage -Force
$NoLanguage = New-PSSession -ComputerName Srv01 -ConfigurationName NoLanguage
Invoke-Command -Session $NoLanguage -ScriptBlock { if ((Get-Date) -lt '1January2099') {'Before'} else {'After'} }

The syntax is not supported by this runspace. This might be because it is in no-language mode.
    + CategoryInfo          : ParserError: (if ((Get-Date) ...') {'Before'}  :String) [], ParseException
    + FullyQualifiedErrorId : ScriptsNotAllowed
    + PSComputerName        : localhost

この例では、Invoke-Command が NoLanguage に設定されているため、 は失敗します。

この例では、言語なしのセッションを使用する方法と効果を示します。

手順は次のとおりです。

1. 新しい構成ファイルを作成します。
2. 構成を登録します。
3. 構成を使用する新しいセッションを作成します。
4. その新しいセッションでコマンドを実行します。

この例のコマンドを実行するには、[管理者として実行] オプションを使用して PowerShell を起動します。 このオプションは、Register-PSSessionConfiguration コマンドレットを実行するために必要です。

New-PSSessionConfigurationFile -Path .\NoLanguage.pssc -LanguageMode RestrictedLanguage
Register-PSSessionConfiguration -Path .\NoLanguage.pssc -Name RestrictedLanguage -Force
$NoLanguage = New-PSSession -ComputerName Srv01 -ConfigurationName RestrictedLanguage
Invoke-Command -Session $NoLanguage -ScriptBlock { if ((Get-Date) -lt '1January2099') {'Before'} else {'After'} }

Before

この例では、Invoke-Command が RestrictedLanguage に設定されているため、 は成功します。

この例では、"ITTasks" という名前の既存のセッションで使用されるセッション構成ファイルを変更する方法を示します。 以前は、これらのセッションにはコア モジュールと ITTasks モジュール 内部がありました。 管理者は、PSScheduledJob モジュールを、ITTasks セッション構成を使用して作成されたセッションに追加したいと考えています。

New-PSSessionConfigurationFile -Path .\New-ITTasks.pssc -ModulesToImport Microsoft*, ITTasks, PSScheduledJob
Set-PSSessionConfiguration -Name ITTasks -Path .\New-ITTasks.pssc

必要なモジュールをインポートするセッション構成ファイルを作成する New-PSSessionConfigurationFile コマンドレット。 Set-PSSessionConfiguration コマンドレットは、現在の構成ファイルを新しい構成ファイルに置き換えます。 この新しい構成は、変更後に作成された新しいセッションにのみ影響します。 既存の "ITTasks" セッションは影響を受けません。

この例では、構成ファイルのアクティブなセッション構成コピーを編集して、セッション構成を変更する方法を示します。 構成ファイルのセッション構成コピーを変更するには、ファイルへのフル コントロール アクセス権が必要です。 これにより、ファイルのアクセス許可を変更することが必要になる場合があります。

このシナリオでは、アクティブな構成ファイルを編集して、Select-String コマンドレットの新しいエイリアスを追加します。

次のコード例では、この変更を行うために次の手順を実行します。

1. ITConfig セッションの構成ファイル パスを取得します。
2. ユーザーは、Notepad.exe を使用して構成ファイルを編集し、AliasDefinitions 値を次のように変更します:AliasDefinitions = @(@{Name='slst';Value='Select-String'})。
3. 更新された構成ファイルをテストします。

$ITConfig = Get-PSSessionConfiguration -Name ITConfig
notepad.exe $ITConfig.ConfigFilePath
Test-PSSessionConfigurationFile -Path $ITConfig.ConfigFilePath

True

検出されたエラーを表示するには、 と共に Test-PSSessionConfigurationFile パラメーターを使用します。 このコマンドレットは、ファイルでエラーが検出されない場合に $True を返します。

この例では、すべてのコマンドレット パラメーターを使用する New-PSSessionConfigurationFile コマンドを示します。 各パラメーターの正しい入力形式を示すために含まれています。

結果の SampleFile.pssc が出力に表示されます。

$configSettings = @{
    Path = '.\SampleFile.pssc'
    SchemaVersion = '1.0.0.0'
    Author = 'User01'
    Copyright = '(c) Fabrikam Corporation. All rights reserved.'
    CompanyName = 'Fabrikam Corporation'
    Description = 'This is a sample file.'
    ExecutionPolicy = 'AllSigned'
    PowerShellVersion = '3.0'
    LanguageMode = 'FullLanguage'
    SessionType = 'Default'
    EnvironmentVariables = @{TESTSHARE='\\Test2\Test'}
    ModulesToImport = @{ModuleName='PSScheduledJob'; ModuleVersion='1.0.0.0'; GUID='50cdb55f-5ab7-489f-9e94-4ec21ff51e59'},'PSDiagnostics'
    AssembliesToLoad = 'System.Web.Services','FSharp.Compiler.CodeDom.dll'
    TypesToProcess = 'Types1.ps1xml','Types2.ps1xml'
    FormatsToProcess = 'CustomFormats.ps1xml'
    ScriptsToProcess = 'Get-Inputs.ps1'
    AliasDefinitions = @{Name='hlp';Value='Get-Help';Description='Gets help.';Options='AllScope'},@{Name='Update';Value='Update-Help';Description='Updates help';Options='ReadOnly'}
    FunctionDefinitions = @{Name='Get-Function';ScriptBlock={Get-Command -CommandType Function};Options='ReadOnly'}
    VariableDefinitions = @{Name='WarningPreference';Value='SilentlyContinue'}
    VisibleAliases = 'c*','g*','i*','s*'
    VisibleCmdlets = 'Get*'
    VisibleFunctions = 'Get*'
    VisibleProviders = 'FileSystem','Function','Variable'
}
New-PSSessionConfigurationFile @configSettings
Get-Content SampleFile.pssc

@{

# Version number of the schema used for this configuration file
SchemaVersion = '1.0.0.0'

# ID used to uniquely identify this session configuration
GUID = 'f7039ffa-7e54-4382-b358-a393c75c30d3'

# Specifies the execution policy for this session configuration
ExecutionPolicy = 'AllSigned'

# Specifies the language mode for this session configuration
LanguageMode = 'FullLanguage'

# Initial state of this session configuration
SessionType = 'Default'

# Environment variables defined in this session configuration
EnvironmentVariables = @{
    TESTSHARE='\\Test2\Test'
}

# Author of this session configuration
Author = 'User01'

# Company associated with this session configuration
CompanyName = 'Fabrikam Corporation'

# Copyright statement for this session configuration
Copyright = '(c) Fabrikam Corporation. All rights reserved.'

# Description of the functionality provided by this session configuration
Description = 'This is a sample file.'

# Version of the PowerShell engine used by this session configuration
PowerShellVersion = '3.0'

# Modules that will be imported
ModulesToImport = @{
    ModuleVersion='1.0.0.0'
    ModuleName='PSScheduledJob'
    GUID='50cdb55f-5ab7-489f-9e94-4ec21ff51e59'
}, 'PSDiagnostics'

# Assemblies that will be loaded in this session configuration
AssembliesToLoad = 'System.Web.Services', 'FSharp.Compiler.CodeDom.dll'

# Aliases visible in this session configuration
VisibleAliases = 'c*', 'g*', 'i*', 's*'

# Cmdlets visible in this session configuration
VisibleCmdlets = 'Get*'

# Functions visible in this session configuration
VisibleFunctions = 'Get*'

# Providers visible in this session configuration
VisibleProviders = 'FileSystem', 'Function', 'Variable'

# Aliases defined in this session configuration
AliasDefinitions = @(
@{
    Description='Gets help.'
    Name='hlp'
    Options='AllScope'
    Value='Get-Help'
},
@{
    Description='Updates help'
    Name='Update'
    Options='ReadOnly'
    Value='Update-Help'
}
)

# Functions defined in this session configuration
FunctionDefinitions = @(
@{
    Name='Get-Function'
    Options='ReadOnly'
    ScriptBlock={Get-Command -CommandType Function}
}
)

# Variables defined in this session configuration
VariableDefinitions = @(
@{
    Value='SilentlyContinue'
    Name='WarningPreference'

# Type files (.ps1xml) that will be loaded in this session configuration
TypesToProcess = 'C:\WINDOWS\System32\WindowsPowerShell\v1.0\SessionConfig\Types1.ps1xml', 'C:\WINDOWS\System32\WindowsPowerShell\v1.0\SessionConfig\Types2.ps1xml'

# Format files (.ps1xml) that will be loaded in this session configuration
FormatsToProcess = 'C:\WINDOWS\System32\WindowsPowerShell\v1.0\SessionConfig\CustomFormats.ps1xml'

# Specifies the scripts to execute after the session is configured
ScriptsToProcess = 'C:\WINDOWS\System32\WindowsPowerShell\v1.0\SessionConfig\Get-Inputs.ps1'
}

この例では、すべてのコマンドレット パラメーターを使用する New-PSSessionConfigurationFile コマンドを表示します。 各パラメーターの正しい入力形式を示すために含まれています。

結果の SampleFile.pssc が出力に表示されます。

このコマンドレットでは、一般的なパラメーター -Debug、-ErrorAction、-ErrorVariable、-InformationAction、-InformationVariable、-OutBuffer、-OutVariable、-PipelineVariable、-ProgressAction、-Verbose、-WarningAction、-WarningVariable の各パラメーターがサポートされています。 詳細については、about_CommonParametersを参照してください。

このコマンドレットにオブジェクトをパイプすることはできません。

このコマンドレットは出力を生成しません。

• VisibleCmdlets や VisibleProviders などのパラメーターは、セッションに項目をインポートしません。 代わりに、セッションにインポートされた項目の中から選択します。 たとえば、VisibleProviders パラメーターの値が証明書プロバイダーであっても、ModulesToImport パラメーターで証明書プロバイダーを含む Microsoft.PowerShell.Security モジュール が指定されていない場合、証明書プロバイダーはセッションに表示されません。

• New-PSSessionConfigurationFile は、Path パラメーターで指定したパスに .pssc ファイル名拡張子を持つセッション構成ファイルを作成します。 セッション構成ファイルを使用してセッション構成を作成すると、Register-PSSessionConfiguration コマンドレットは構成ファイルをコピーし、 ディレクトリの $PSHOME サブディレクトリにファイルのアクティブなコピーを保存します。

  セッション構成の ConfigFilePath プロパティには、アクティブなセッション構成ファイルの完全修飾パスが含まれています。 任意のテキスト エディターを使用して、$PSHOME ディレクトリ内のアクティブな構成ファイルをいつでも変更できます。 行った変更は、セッション構成を使用するすべての新しいセッションに影響しますが、既存のセッションには影響しません。

  編集されたセッション構成ファイルを使用する前に、Test-PSSessionConfigurationFile コマンドレットを使用して、構成ファイルのエントリが有効であることを確認します。