acerca de la configuración de PowerShell

Breve descripción

Archivos de configuración para PowerShell, que reemplazan la configuración del Registro.

Descripción larga

El archivo powershell.config.json contiene ajustes de configuración para PowerShell. PowerShell carga esta configuración al inicio. La configuración también se puede modificar en tiempo de ejecución. Anteriormente, estas configuraciones se almacenaban en el Registro de Windows para PowerShell, pero ahora están contenidas en un archivo para permitir la configuración en macOS y Linux.

Resumen de configuración

El archivo powershell.config.json puede contener las siguientes claves:

DisableImplicitWinCompat

WindowsPowerShellCompatibilityModuleDenyList

WindowsPowerShellCompatibilityNoClobberModuleList

ExperimentalFeatures

LogChannels

LogIdentity

LogKeywords

LogLevel

Microsoft.PowerShell:ExecutionPolicy

PSModulePath

• Políticas de PowerShell

  ExecutionPolicy

  ConsoleSessionConfiguration

  ModuleLogging

  ProtectedEventLogging

  ScriptBlockLogging

  ScriptExecution

  Transcription

  UpdatableHelp

No todas las claves se aplican a todas las plataformas. La clave PowerShellPolicies contiene subclaves que reflejan la configuración administrada por la Política de grupo de Windows. Esas subclaves también se aplican a todas las plataformas cuando se definen en el nivel raíz del archivo JSON.

Alcance de la configuración

Los ajustes de configuración se pueden definir para todos los usuarios o a nivel de usuario individual.

Configuración de todos los usuarios (compartida)

Un archivo powershell.config.json en el directorio $PSHOME define la configuración para todas las sesiones de PowerShell que se ejecutan desde esa instalación de PowerShell.

Configuraciones de usuario actual (por usuario)

También puede configurar PowerShell por usuario colocando el archivo en el directorio de configuración del ámbito del usuario. El directorio de configuración del usuario se puede encontrar en todas las plataformas con el comando Split-Path $PROFILE.CurrentUserCurrentHost.

Prioridad del alcance

En Windows, la configuración administrada por la Política de grupo de Windows tiene prioridad sobre la configuración del archivo de configuración. La política de grupo no existe en plataformas que no sean Windows.

Después de la Política de grupo, las configuraciones definidas en el nivel Todos los usuarios tienen prioridad sobre las configuraciones definidas para el nivel CurrentUser.

Configuraciones específicas de Windows

Las siguientes configuraciones solo se aplican a las plataformas Windows.

DisableImplicitWinCompat

WindowsPowerShellCompatibilityModuleDenyList

WindowsPowerShellCompatibilityNoClobberModuleList

ExecutionPolicy

PowerShellPolicies

Deshabilitar ImplicitWinCompat

Cuando se establece en true, esta configuración deshabilita la función de compatibilidad de Windows PowerShell. La compatibilidad con Windows PowerShell permite que PowerShell 7 cargue módulos de Windows PowerShell 5.1 en modo de compatibilidad.

Para obtener más información, consulte about_Windows_PowerShell_Compatibility.

WindowsPowerShellCompatibilityModuleDenyList

Esta configuración es una matriz de nombres de módulos que desea excluir de la participación en la característica de compatibilidad de Windows PowerShell.

Para obtener más información, consulte about_Windows_PowerShell_Compatibility.

WindowsPowerShellCompatibilidadNoClobberModuleList

Esta configuración es una matriz de nombres de módulos que no deben verse afectados al cargar la versión Windows PowerShell 5.1 del módulo.

Para obtener más información, consulte about_Windows_PowerShell_Compatibility.

ExecutionPolicy

Configura la política de ejecución para las sesiones de PowerShell, determinando qué scripts se pueden ejecutar. De forma predeterminada, PowerShell utiliza la política de ejecución existente.

Para las configuraciones de AllUsers, esto establece la política de ejecución de LocalMachine. Para las configuraciones de CurrentUser, esto establece la política de ejecución de CurrentUser.

El siguiente ejemplo establece la política de ejecución de PowerShell en RemoteSigned.

{
  "Microsoft.PowerShell:ExecutionPolicy": "RemoteSigned"
}

Para obtener más información, consulte about_Execution_Policies.

Políticas de PowerShell

Windows tiene varias configuraciones que pueden administrarse mediante la Política de grupo. Por lo general, esas configuraciones se almacenan en el registro de Windows. Esas configuraciones también se pueden definir en el archivo powershell.config.json.

PowerShellPolicies es un objeto JSON que contiene pares clave-valor para las distintas configuraciones de políticas. Esas configuraciones de política también se pueden enumerar en el nivel raíz del archivo JSON, fuera del objeto PowerShellPolicies. Esta configuración puede contener las siguientes subclaves:

ConsoleSessionConfiguration

ModuleLogging

ProtectedEventLogging

ScriptBlockLogging

ScriptExecution

Transcription

UpdatableHelp

La configuración ScriptExecution se utiliza para configurar la política de ejecución de PowerShell. Esto tiene prioridad sobre la configuración ExecutionPolicy descrita anteriormente.

Ejemplo :

{
    "PowerShellPolicies": {
        "ScriptExecution": {
            "ExecutionPolicy": "RemoteSigned"
        }
    }
}

Para obtener descripciones de otras configuraciones de políticas, consulte las descripciones en la sección Configuración común.

En Windows, PowerShell busca la configuración en el registro. Cualquier configuración encontrada en el registro tiene prioridad. A continuación, PowerShell lee la configuración JSON. Cualquier configuración que se encuentre en PowerShellPolicies y que no esté definida en el registro tiene prioridad sobre la configuración que se encuentra en el nivel raíz de la configuración JSON.

Para obtener más información, consulte about_Group_Policy_Settings.

Configuraciones para plataformas que no son Windows

Las siguientes configuraciones solo se aplican a las plataformas Linux y macOS.

Las siguientes claves se utilizan para configurar el registro de PowerShell para Linux y macOS.

LogChannels

LogIdentity

LogKeywords

LogLevel

Para obtener una descripción completa del registro de PowerShell para sistemas que no son Windows, consulte about_Logging_Non-Windows.

Ajustes de configuración comunes

Las siguientes configuraciones están disponibles en todas las plataformas compatibles.

ConsoleSessionConfiguration

ExperimentalFeatures

ModuleLogging

ProtectedEventLogging

PSModulePath

ScriptBlockLogging

ScriptExecution

Transcription

UpdatableHelp

Configuración de sesión de consola

Esta configuración especifica la configuración de sesión que se utilizará para todas las sesiones de PowerShell. Puede ser cualquier punto final registrado en la máquina local, incluidos los puntos finales remotos de PowerShell predeterminados o un punto final personalizado que tenga capacidades de rol de usuario específicas.

Esta clave contiene dos subclaves:

• EnableConsoleSessionConfiguration: para habilitar las configuraciones de sesión, establezca el valor en true. De forma predeterminada, este valor es false.

• ConsoleSessionConfigurationName: especifica el nombre del punto final de configuración en el que se ejecuta PowerShell. De forma predeterminada, no hay ninguna sesión definida.

{
  "ConsoleSessionConfiguration": {
    "EnableConsoleSessionConfiguration": false,
    "ConsoleSessionConfigurationName" : []
  }
}

Para obtener más información, consulte about_Session_Configurations.

ExperimentalFeatures

Los nombres de las funciones experimentales que se habilitarán en PowerShell. El valor predeterminado es una matriz vacía.

El siguiente ejemplo habilita las funciones experimentales PSCommandNotFoundSuggestion y PSSubsystemPluginModel cuando se inicia PowerShell.

Ejemplo :

{
  "ExperimentalFeatures": [
    "PSCommandNotFoundSuggestion",
    "PSSubsystemPluginModel"
  ]
}

Para obtener más información sobre funciones experimentales, consulte Uso de funciones experimentales.

ModuleLogging

Esta configuración controla el comportamiento del registro de los módulos de PowerShell. La configuración contiene dos subclaves:

• EnableModuleLogging: para habilitar las configuraciones de sesión, establezca el valor en true. Cuando está habilitado, los eventos de ejecución de canalización para los miembros de los módulos especificados se registran en los archivos de registro de PowerShell.
• ModuleNames: especifica el nombre de los módulos que deben registrarse.

Ejemplo :

{
  "ModuleLogging": {
    "EnableModuleLogging": true,
    "ModuleNames" : [
        "PSReadLine",
        "PowerShellGet"
    ]
  }
}

Registro de eventos protegido

Esta configuración le permite configurar el registro de eventos protegido. La configuración contiene dos subclaves:

• EnableProtectedEventLogging: si habilita esta configuración de política, los componentes que la admiten utilizan el certificado que usted proporciona para cifrar los datos del registro antes de escribirlos en el registro. Los datos se cifran utilizando el estándar de sintaxis de mensajes criptográficos (CMS). Puede utilizar Unprotect-CmsMessage para descifrar estos mensajes cifrados, si tiene acceso a la clave privada del certificado.
• EncryptionCertificate: proporciona una lista de nombres de certificados que se utilizarán para el cifrado.

Ejemplo :

{
  "ProtectedEventLogging": {
    "EnableProtectedEventLogging": false,
    "EncryptionCertificate": [
      "Joe"
    ]
  }
}

Ruta del módulo PS

Anula la configuración de PSModulePath para esta sesión de PowerShell. Si la configuración es para el usuario actual, establece la ruta del módulo CurrentUser. Si la configuración es para todos los usuarios, establece la ruta del módulo AllUsers.

Si no se establece ningún valor, PowerShell usa el valor predeterminado para la configuración de ruta del módulo respectivo. Para obtener más información sobre estos valores predeterminados, consulte about_PSModulePath.

Esta configuración permite utilizar variables de entorno incrustándolas entre caracteres %, como "%HOME%\Documents\PowerShell\Modules", de la misma manera que el comando de Windows Shell lo permite. Esta sintaxis también se aplica en Linux y macOS. Vea a continuación ejemplos.

Este ejemplo muestra una configuración PSModulePath para un entorno Windows:

{
  "PSModulePath": "C:\\Program Files\\PowerShell\\6\\Modules"
}

Este ejemplo muestra una configuración PSModulePath para un entorno macOS o Linux:

{
  "PSModulePath": "/opt/powershell/6/Modules"
}

Este ejemplo muestra la incorporación de una variable de entorno en una configuración PSModulePath. Tenga en cuenta que al utilizar la variable de entorno HOME y el separador de directorio /, esta sintaxis funciona en Windows, macOS y Linux.

{
  "PSModulePath": "%HOME%/Documents/PowerShell/Modules"
}

Este ejemplo utiliza una variable de entorno que solo funciona en macOS y Linux:

{
  "PSModulePath": "%XDG_CONFIG_HOME%/powershell/Modules"
}

Registro de bloques de scripts

Esta configuración controla el registro de todas las entradas del script de PowerShell. Esta configuración contiene dos subclaves:

• EnableScriptBlockLogging: si habilita esta configuración de política, PowerShell registra el procesamiento de comandos, bloques de secuencias de comandos, funciones y secuencias de comandos, ya sea que se invoquen de forma interactiva o mediante automatización.
• EnableScriptBlockInvocationLogging: habilita el registro de eventos de inicio y detención del bloque de script.

Ejemplo :

"ScriptBlockLogging": {
  "EnableScriptBlockInvocationLogging": true,
  "EnableScriptBlockLogging": false
}

Transcripción

Esta configuración de política le permite capturar la entrada y salida de los comandos de PowerShell en transcripciones basadas en texto. Si habilita esta configuración de directiva, PowerShell habilita la transcripción para todas las sesiones de PowerShell.

Esta configuración controla cómo funciona la transcripción en PowerShell. Esta configuración contiene tres subclaves:

• EnableTranscripting: cuando esta configuración está habilitada, PowerShell crea archivos de registro de transcripción en la ubicación configurada.
• EnableInvocationHeader: de forma predeterminada, PowerShell incluye un encabezado en la parte superior del archivo de registro de transcripción. Puede desactivar el encabezado usando esta configuración.
• OutputDirectory: esta configuración le permite recopilar archivos de registro de transcripción en una ubicación central en lugar de la ubicación predeterminada.

Ejemplo :

{
    "Transcription": {
        "EnableTranscripting": true,
        "EnableInvocationHeader": true,
        "OutputDirectory": "c:\\tmp"
      }
}

Para obtener más información, consulte Inicio-Transcripción.

UpdatableHelp

Esta configuración de política le permite establecer el valor predeterminado del parámetro SourcePath en el cmdlet Update-Help. Este valor predeterminado se puede anular especificando un valor diferente utilizando el parámetro SourcePath.

Ejemplo :

{
    "UpdatableHelp": {
      "DefaultSourcePath": "f:\\temp"
    }
}