Compartir a través de


New-PSRoleCapabilityFile

Crea un archivo que define un conjunto de funcionalidades que se van a exponer a través de una configuración de sesión.

Sintaxis

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>]

Description

El New-PSRoleCapabilityFile cmdlet crea un archivo que define un conjunto de funcionalidades de usuario que se pueden exponer a través de archivos de configuración de sesión. Esto incluye determinar qué cmdlets, funciones y scripts están disponibles para los usuarios. El archivo de funcionalidad es un archivo de texto legible que contiene una tabla hash de propiedades y valores de configuración de sesión. El archivo tiene una extensión de nombre de archivo .psrc y puede usarse en más de una configuración de sesión.

Todos los parámetros de New-PSRoleCapabilityFile son opcionales, excepto el parámetro Path , que especifica la ruta de acceso del archivo. Si no incluye un parámetro al ejecutar el cmdlet, la clave correspondiente en el archivo de configuración de sesión se comenta, excepto cuando se indique en la descripción del parámetro. Por ejemplo, si no incluye el parámetro AssembliesToLoad , esa sección del archivo de configuración de sesión se comenta.

Para usar el archivo de funcionalidad de rol en una configuración de sesión, coloque primero el archivo en una subcarpeta RoleCapabilities de una carpeta de módulo de PowerShell válida. A continuación, haga referencia al archivo por nombre en el campo RoleDefinitions en un archivo de configuración de sesión de PowerShell (.pssc).

Este cmdlet se introdujo en Windows PowerShell 5.0.

Ejemplos

Ejemplo 1: Creación de un archivo de funcionalidad de rol en blanco

En este ejemplo se crea un nuevo archivo de funcionalidad de rol que usa los valores predeterminados (en blanco). El archivo se puede editar más adelante en un editor de texto para cambiar estas opciones de configuración.

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

Ejemplo 2: Creación de un archivo de funcionalidad de rol que permite a los usuarios reiniciar servicios y cualquier equipo VDI

En este ejemplo se crea un archivo de funcionalidad de rol de ejemplo que permite a los usuarios reiniciar servicios y equipos que coinciden con un patrón de nombre específico. El filtrado de nombres se define estableciendo el parámetro ValidatePattern en la expresión VDI\d+regular .

$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

Parámetros

-AliasDefinitions

Agrega los alias especificados a las sesiones que usan el archivo de funcionalidad de rol. Especifique una tabla hash con las claves siguientes:

  • Nombre. nombre del alias. Esta clave es obligatoria.
  • Valor. comando que representa el alias. Esta clave es obligatoria.
  • Descripción. cadena de texto que describe el alias. Esta clave es opcional.
  • Opciones. opciones de alias. Esta clave es opcional. El valor predeterminado es None. Los valores aceptables para este parámetro son: None, ReadOnly, Constant, Private o AllScope.

Por ejemplo: @{Name="hlp";Value="Get-Help";Description="Gets help";Options="ReadOnly"}

Tipo:IDictionary[]
Posición:Named
Valor predeterminado:None
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-AssembliesToLoad

Especifica los ensamblados que se van a cargar en las sesiones que usan el archivo de funcionalidad de rol.

Tipo:String[]
Posición:Named
Valor predeterminado:None
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-Author

Especifica el usuario que creó el archivo de funcionalidad de rol.

Tipo:String
Posición:Named
Valor predeterminado:None
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-CompanyName

Identifica la empresa que creó el archivo de funcionalidad de rol. El valor predeterminado es Desconocido.

Tipo:String
Posición:Named
Valor predeterminado:None
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

Especifica un copyright para el archivo de funcionalidad de rol. Si omite este parámetro, New-PSRoleCapabilityFile genera una declaración de copyright con el valor del parámetro Author .

Tipo:String
Posición:Named
Valor predeterminado:None
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-Description

Especifica una descripción para el archivo de funcionalidad de rol.

Tipo:String
Posición:Named
Valor predeterminado:None
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-EnvironmentVariables

Especifica las variables de entorno para las sesiones que exponen este archivo de funcionalidad de rol. Especifique una tabla hash en la que las claves sean los nombres de variables de entorno y los valores sean los valores de variables de entorno.

Por ejemplo: EnvironmentVariables=@{TestShare="\\\\Server01\TestShare"}

Tipo:IDictionary
Posición:Named
Valor predeterminado:None
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-FormatsToProcess

Especifica los archivos de formato (.ps1xml) que se ejecutan en sesiones que usan el archivo de funcionalidad de rol. El valor de este parámetro debe ser una ruta de acceso completa o absoluta de los archivos de formato.

Tipo:String[]
Posición:Named
Valor predeterminado:None
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-FunctionDefinitions

Agrega las funciones especificadas a las sesiones que exponen la funcionalidad de rol. Especifique una tabla hash con las claves siguientes:

  • Nombre. El nombre de la función. Esta clave es obligatoria.
  • ScriptBlock. cuerpo de la función. Escriba un bloque de scripts. Esta clave es obligatoria.
  • Opciones. opciones de la función. Esta clave es opcional. El valor predeterminado es None. Los valores aceptables para este parámetro son: none, ReadOnly, Constant, Private o AllScope.

Por ejemplo:

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

Tipo:IDictionary[]
Posición:Named
Valor predeterminado:None
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-Guid

Especifica un identificador único para el archivo de funcionalidad de rol. Si omite este parámetro, New-PSRoleCapabilityFile genera un GUID para el archivo. Para crear un nuevo GUID en PowerShell, escriba [guid]::NewGuid().

Tipo:Guid
Posición:Named
Valor predeterminado:None
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-ModulesToImport

Especifica los módulos que se importan automáticamente en sesiones que usan el archivo de funcionalidad de rol. De forma predeterminada, todos los comandos de los módulos enumerados están visibles. Cuando se usa con VisibleCmdlets o VisibleFunctions, los comandos visibles desde los módulos especificados se pueden restringir.

Cada módulo usado en el valor de este parámetro se puede representar mediante una cadena o mediante una tabla hash. Una cadena de módulo solo consta del nombre del módulo. Una tabla hash de módulo puede incluir moduleName, ModuleVersion y claves GUID . Solo se requiere la clave ModuleName .

Por ejemplo, el siguiente valor consta de una cadena y una tabla hash. Cualquier combinación de cadenas y tablas hash, en cualquier orden, es válida.

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

Tipo:Object[]
Posición:Named
Valor predeterminado:None
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-Path

Especifica la ruta de acceso y el nombre de archivo del archivo de funcionalidad de rol. El archivo debe tener una .psrc extensión de nombre de archivo.

Tipo:String
Posición:0
Valor predeterminado:None
Requerido:True
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-ScriptsToProcess

Especifica los scripts que se van a agregar a las sesiones que usan el archivo de funcionalidad de rol. Escriba los nombres de ruta de acceso y de archivo de los scripts. El valor de este parámetro debe ser una ruta de acceso completa o absoluta de los nombres de archivo de script.

Tipo:String[]
Posición:Named
Valor predeterminado:None
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-TypesToProcess

Especifica los archivos de tipo (.ps1xml) que se van a agregar a las sesiones que usan el archivo de funcionalidad de rol. Escriba los nombres de archivo de tipo. El valor de este parámetro debe ser una ruta de acceso completa o absoluta del tipo filenames.

Tipo:String[]
Posición:Named
Valor predeterminado:None
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-VariableDefinitions

Especifica variables que se van a agregar a las sesiones que usan el archivo de funcionalidad de rol. Especifique una tabla hash con las claves siguientes:

  • Nombre. nombre de la variable. Esta clave es obligatoria.
  • Valor. valor de variable. Esta clave es obligatoria.

Por ejemplo: @{Name="WarningPreference";Value="SilentlyContinue"}

Tipo:Object
Posición:Named
Valor predeterminado:None
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-VisibleAliases

Limita los alias de la sesión a esos alias especificados en el valor de este parámetro, además de los alias que defina en el parámetro AliasDefinition . Se admite el uso de caracteres comodín. De forma predeterminada, todos los alias definidos por el motor de PowerShell y todos los alias que exportan los módulos están visibles en la sesión.

Por ejemplo, para limitar los alias disponibles a gm y gcm, use esta sintaxis: VisibleAliases="gcm", "gp"

Cuando se incluye cualquier parámetro Visible en el archivo de funcionalidad de rol, PowerShell quita el Import-Module cmdlet y su ipmo alias de la sesión.

Tipo:String[]
Posición:Named
Valor predeterminado:None
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:True

-VisibleCmdlets

Limita los cmdlets en la sesión a los especificados en el valor de este parámetro. Se admiten caracteres comodín y nombres calificados de módulo.

De forma predeterminada, todos los cmdlets que los módulos de la exportación de sesión están visibles en la sesión. Use los parámetros SessionType y ModulesToImport para determinar qué módulos y complementos se importan en la sesión. Si ningún módulo de ModulesToImport expone el cmdlet, New-PSRoleCapabilityFile intenta cargar el módulo adecuado.

Cuando se incluye cualquier parámetro Visible en el archivo de configuración de sesión, PowerShell quita el Import-Module cmdlet y su ipmo alias de la sesión.

Tipo:Object[]
Posición:Named
Valor predeterminado:None
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:True

-VisibleExternalCommands

Limita los archivos binarios externos, scripts y comandos que se pueden ejecutar en la sesión a los especificados en el valor de este parámetro.

De forma predeterminada, no hay ningún comando externo visible en esta sesión.

Cuando se incluye cualquier parámetro Visible en el archivo de configuración de sesión, PowerShell quita el Import-Module cmdlet y su ipmo alias de la sesión.

Tipo:String[]
Posición:Named
Valor predeterminado:None
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-VisibleFunctions

Limita las funciones de la sesión a las especificadas en el valor de este parámetro, además de las funciones que defina en el parámetro FunctionDefinitions . Se admite el uso de caracteres comodín.

De forma predeterminada, todas las funciones exportadas por módulos de la sesión están visibles en esa sesión. Use los parámetros SessionType y ModulesToImport para determinar qué módulos se importan en la sesión.

Cuando se incluye cualquier parámetro Visible en el archivo de configuración de sesión, PowerShell quita el Import-Module cmdlet y su ipmo alias de la sesión.

Tipo:Object[]
Posición:Named
Valor predeterminado:None
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:True

-VisibleProviders

Limita los proveedores de PowerShell de la sesión a los especificados en el valor de este parámetro. Se admite el uso de caracteres comodín.

De forma predeterminada, todos los proveedores exportados por un módulo de la sesión están visibles en la sesión. Use los parámetros SessionType y ModulesToImport para determinar qué módulos se importan en la sesión.

Cuando se incluye cualquier parámetro Visible en el archivo de configuración de sesión, PowerShell quita el Import-Module cmdlet y su ipmo alias de la sesión.

Tipo:String[]
Posición:Named
Valor predeterminado:None
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:True