Поделиться через


New-PSRoleCapabilityFile

Создает файл, определяющий набор возможностей, предоставляемых через конфигурацию сеанса.

Синтаксис

New-PSRoleCapabilityFile
   [-Path] <String>
   [-Guid <Guid>]
   [-Author <String>]
   [-Description <String>]
   [-CompanyName <String>]
   [-Copyright <String>]
   [-ModulesToImport <Object[]>]
   [-VisibleAliases <String[]>]
   [-VisibleCmdlets <Object[]>]
   [-VisibleFunctions <Object[]>]
   [-VisibleExternalCommands <String[]>]
   [-VisibleProviders <String[]>]
   [-ScriptsToProcess <String[]>]
   [-AliasDefinitions <IDictionary[]>]
   [-FunctionDefinitions <IDictionary[]>]
   [-VariableDefinitions <Object>]
   [-EnvironmentVariables <IDictionary>]
   [-TypesToProcess <String[]>]
   [-FormatsToProcess <String[]>]
   [-AssembliesToLoad <String[]>]
   [<CommonParameters>]

Описание

Командлет New-PSRoleCapabilityFile создает файл, определяющий набор пользовательских возможностей, которые можно предоставить через файлы конфигурации сеанса. Сюда входит определение того, какие командлеты, функции и скрипты доступны пользователям. Файл возможностей — это доступный для чтения текстовый файл, содержащий хэш-таблицу свойств и значений конфигурации сеанса. Файл имеет расширение PSRC и может использоваться несколькими конфигурациями сеанса.

Все параметры являются необязательными New-PSRoleCapabilityFile , за исключением параметра Path , который задает путь к файлу. Если параметр не включен при выполнении командлета, соответствующий ключ в файле конфигурации сеанса будет закомментирован, за исключением тех случаев, когда это указано в описании параметра. Например, если не включить параметр AssembliesToLoad , этот раздел файла конфигурации сеанса будет закомментирован.

Чтобы использовать файл возможностей роли в конфигурации сеанса, сначала поместите файл во вложенную папку RoleCapabilities допустимой папки модуля PowerShell. Затем укажите ссылку на файл по имени в поле RoleDefinitions в pssc-файле конфигурации сеанса PowerShell.

Этот командлет появился в Windows PowerShell 5.0.

Примеры

Пример 1. Create пустого файла возможностей роли

В этом примере создается новый файл возможностей роли, в котором используются значения по умолчанию (пустые). Позже файл можно изменить в текстовом редакторе, чтобы изменить эти параметры конфигурации.

New-PSRoleCapabilityFile -Path ".\ExampleFile.psrc"

Пример 2. Create файл возможностей роли, позволяющий пользователям перезагружать службы и любой компьютер VDI

В этом примере создается пример файла возможностей роли, который позволяет пользователям перезагружать службы и компьютеры, соответствующие определенному шаблону имени. Фильтрация имен определяется путем задания для параметра ValidatePattern регулярного выражения VDI\d+.

$roleParameters = @{
    Path = ".\Maintenance.psrc"
    Author = "User01"
    CompanyName = "Fabrikam Corporation"
    Description = "This role enables users to restart any service and restart any VDI computer."
    ModulesToImport = "Microsoft.PowerShell.Core"
    VisibleCmdlets = "Restart-Service", @{
                      Name = "Restart-Computer"
                      Parameters = @{ Name = "ComputerName"; ValidatePattern = "VDI\d+" }
    }
}
New-PSRoleCapabilityFile @roleParameters

Параметры

-AliasDefinitions

Добавляет указанные псевдонимы в сеансы, использующие файл возможностей роли. Введите хэш-таблицу со следующими разделами:

  • Название Имя псевдонима. Этот раздел обязателен.
  • Значение. Команда, которая представляет псевдоним. Этот раздел обязателен.
  • Описание. Текстовая строка с описанием псевдонима. Этот раздел необязателен.
  • Параметры. Параметры псевдонима. Этот раздел необязателен. По умолчанию используется None. Допустимые значения для этого параметра: None, ReadOnly, Constant, Private или AllScope.

Пример: @{Name="hlp";Value="Get-Help";Description="Gets help";Options="ReadOnly"}

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

-AssembliesToLoad

Указывает сборки для загрузки в сеансы, использующие файл возможностей роли.

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

-Author

Указывает пользователя, создавшего файл возможностей роли.

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

-CompanyName

Идентифицирует компанию, создающую файл возможностей роли. Значение по умолчанию: Unknown.

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

Указывает авторские права для файла возможностей роли. Если этот параметр не указан, New-PSRoleCapabilityFile создается заявление об авторских правах, используя значение параметра Author .

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

-Description

Указывает описание файла возможностей роли.

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

-EnvironmentVariables

Указывает переменные среды для сеансов, которые предоставляют этот файл возможностей роли. Введите хэш-таблицу, в которой разделами являются имена переменных среды, а значениями — значения переменных среды.

Пример: EnvironmentVariables=@{TestShare="\\\\Server01\TestShare"}

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

-FormatsToProcess

Указывает файлы форматирования (.ps1xml), которые выполняются в сеансах, использующих файл возможностей роли. Значение этого параметра должно быть полным или абсолютным путем к файлам форматирования.

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

-FunctionDefinitions

Добавляет указанные функции в сеансы, предоставляющие возможность роли. Введите хэш-таблицу со следующими разделами:

  • Название Имя функции. Этот раздел обязателен.
  • ScriptBlock. Тело функции. Введите блок сценария. Этот раздел обязателен.
  • Параметры. Параметры функции. Этот раздел необязателен. По умолчанию используется None. Допустимые значения для этого параметра: None, ReadOnly, Constant, Private или AllScope.

Пример:

@{Name="Get-PowerShellProcess";ScriptBlock={Get-Process PowerShell};Options="AllScope"}

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

-Guid

Задает уникальный идентификатор для файла возможностей роли. Если этот параметр не указан, New-PSRoleCapabilityFile создается guid для файла. Чтобы создать новый GUID в PowerShell, введите [guid]::NewGuid().

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

-ModulesToImport

Указывает модули, которые автоматически импортируются в сеансы, использующие файл возможностей роли. По умолчанию отображаются все команды в перечисленных модулях. При использовании с VisibleCmdlets или VisibleFunctions команды, видимые из указанных модулей, могут быть ограничены.

Каждый модуль, используемый в значении этого параметра, может быть представлен строкой или хэш-таблицей. Строка модуля состоит только из имени модуля. Хэш-таблица модуля может включать разделы ModuleName, ModuleVersion и GUID. Обязателен только раздел ModuleName.

Например, следующее значение состоит из строки и хэш-таблицы. Допустимо любое сочетание строк и хэш-таблиц в любом порядке.

"TroubleshootingPack", @{ModuleName="PSDiagnostics"; ModuleVersion="1.0.0.0";GUID="c61d6278-02a3-4618-ae37-a524d40a7f44"}

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

-Path

Указывает путь и имя файла возможности роли. Файл должен иметь .psrc расширение имени файла.

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

-ScriptsToProcess

Указывает скрипты для добавления в сеансы, использующие файл возможностей роли. Введите путь и имена файлов сценариев. Значение этого параметра должно быть полным или абсолютным путем к именам файлов скрипта.

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

-TypesToProcess

Указывает файлы типа (.ps1xml), добавляемые в сеансы, использующие файл возможностей роли. Введите тип имен файлов. Значение этого параметра должно быть полным или абсолютным путем к именам файлов типа.

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

-VariableDefinitions

Указывает переменные, добавляемые в сеансы, использующие файл возможностей роли. Введите хэш-таблицу со следующими разделами:

  • Название Имя переменной. Этот раздел обязателен.
  • Значение. Значение переменной. Этот раздел обязателен.

Пример: @{Name="WarningPreference";Value="SilentlyContinue"}

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

-VisibleAliases

Ограничивает псевдонимы в сеансе теми псевдонимами, которые указаны в значении этого параметра, а также любыми псевдонимами, определенными в параметре AliasDefinition . Поддерживаются подстановочные знаки. По умолчанию все псевдонимы, определенные подсистемой PowerShell, и все псевдонимы, экспортируемые модулями, отображаются в сеансе.

Например, чтобы ограничить доступные псевдонимы gm и gcm, используйте следующий синтаксис: VisibleAliases="gcm", "gp"

Если в файл возможностей роли включен какой-либо параметр Visible , PowerShell удаляет Import-Module командлет и его ipmo псевдоним из сеанса.

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

-VisibleCmdlets

Ограничивает командлеты в сеансе теми, которые указаны в значении этого параметра. Поддерживаются подстановочные знаки и полные имена модулей.

По умолчанию все командлеты, которые модули экспортируются в сеансе, отображаются в сеансе. Используйте параметры SessionType и ModulesToImport, чтобы определить, какие модули и оснастки импортируются в сеанс. Если в ModulesToImport нет модулей, которые предоставляют командлет , New-PSRoleCapabilityFile пытается загрузить соответствующий модуль.

Если в файл конфигурации сеанса включен любой параметр Visible , PowerShell удаляет Import-Module командлет и его ipmo псевдоним из сеанса.

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

-VisibleExternalCommands

Ограничивает внешние двоичные файлы, скрипты и команды, которые могут выполняться в сеансе, теми, которые указаны в значении этого параметра.

По умолчанию внешние команды не отображаются в этом сеансе.

Если в файл конфигурации сеанса включен любой параметр Visible , PowerShell удаляет Import-Module командлет и его ipmo псевдоним из сеанса.

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

-VisibleFunctions

Ограничивает функции в сеансе теми, которые указаны в значении этого параметра, а также любыми функциями, определенными в параметре FunctionDefinitions . Поддерживаются подстановочные знаки.

По умолчанию все функции, экспортированные модулями в сеансе, отображаются в этом сеансе. Используйте параметры SessionType и ModulesToImport , чтобы определить, какие модули импортируются в сеанс.

Если в файл конфигурации сеанса включен любой параметр Visible , PowerShell удаляет Import-Module командлет и его ipmo псевдоним из сеанса.

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

-VisibleProviders

Ограничивает поставщики PowerShell в сеансе теми, которые указаны в значении этого параметра. Поддерживаются подстановочные знаки.

По умолчанию все поставщики, экспортированные модулем в сеансе, отображаются в сеансе. Используйте параметры SessionType и ModulesToImport , чтобы определить, какие модули импортируются в сеанс.

Если в файл конфигурации сеанса включен любой параметр Visible , PowerShell удаляет Import-Module командлет и его ipmo псевдоним из сеанса.

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