about_PowerShell_Config

  • Artículo

Descripción breve

Archivos de configuración de PowerShell, reemplazando la configuración del Registro.

Descripción larga

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

Resumen de la configuración

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

  • DisableImplicitWinCompat
  • WindowsPowerShellCompatibilityModuleDenyList
  • WindowsPowerShellCompatibilityNoClobberModuleList
  • ExperimentalFeatures
  • LogChannels
  • LogIdentity
  • LogKeywords
  • LogLevel
  • Microsoft.PowerShell:ExecutionPolicy
  • PSModulePath
  • PowerShellPolicies
    • ExecutionPolicy
    • ConsoleSessionConfiguration
    • ModuleLogging
    • ProtectedEventLogging
    • ScriptBlockLogging
    • ScriptExecution
    • Transcription
    • UpdatableHelp

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

Advertencia

Se omiten las claves no reconocidas o los valores no válidos del archivo de configuración. Si el powershell.config.json archivo contiene JSON no válido, PowerShell no puede iniciar una sesión interactiva. Si esto ocurre, debe corregir el archivo de configuración.

Ámbito de configuración

Las opciones de configuración se pueden definir para todos los usuarios o en el nivel de usuario individual.

Configuración de AllUsers (compartido)

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

Nota:

La $PSHOME ubicación se define como el mismo directorio que el ensamblado de System.Management.Automation.dll en ejecución. Esto también se aplica a las instancias del SDK de PowerShell hospedadas.

Configuraciones currentUser (por usuario)

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

Prioridad de ámbito

En Windows, la configuración administrada por la directiva de grupo de Windows tiene prioridad sobre la configuración del archivo de configuración. La directiva de grupo no existe en plataformas que no son de Windows.

Después de la directiva de grupo, la configuración definida en el nivel AllUsers tiene prioridad sobre la configuración definida para el nivel CurrentUser .

Configuración específica de Windows

La siguiente configuración solo se aplica a las plataformas Windows.

  • DisableImplicitWinCompat
  • WindowsPowerShellCompatibilityModuleDenyList
  • WindowsPowerShellCompatibilityNoClobberModuleList
  • ExecutionPolicy
  • PowerShellPolicies

DisableImplicitWinCompat

Cuando se establece trueen , esta opción deshabilita la característica compatibilidad de Windows PowerShell. La compatibilidad de Windows PowerShell permite a PowerShell 7 cargar 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ódulo que quiere excluir de la participación en la característica compatibilidad de Windows PowerShell.

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

WindowsPowerShellCompatibilityNoClobberModuleList

Esta configuración es una matriz de nombres de módulo que no se deben ocultar cargando la versión de Windows PowerShell 5.1 del módulo.

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

ExecutionPolicy

Importante

Esta configuración solo se aplica en plataformas Windows.

Configura la directiva de ejecución para las sesiones de PowerShell y determina qué scripts se pueden ejecutar. De forma predeterminada, PowerShell usa la directiva de ejecución existente.

Para las configuraciones AllUsers , establece la directiva de ejecución LocalMachine . Para las configuraciones CurrentUser , establece la directiva de ejecución CurrentUser .

En el ejemplo siguiente se establece la directiva de ejecución de PowerShell en RemoteSigned.

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

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

PowerShellPolicies

Windows tiene varias opciones de configuración que se pueden administrar mediante la directiva de grupo. Normalmente, esas opciones se almacenan en el Registro de Windows. Esos valores también se pueden definir en el powershell.config.json archivo.

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

  • ConsoleSessionConfiguration
  • ModuleLogging
  • ProtectedEventLogging
  • ScriptBlockLogging
  • ScriptExecution
  • Transcription
  • UpdatableHelp

La ScriptExecution configuración se usa para establecer la directiva de ejecución de PowerShell. Esto tiene prioridad sobre la ExecutionPolicy configuración descrita anteriormente.

Ejemplo:

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

Para obtener descripciones de la otra configuración de directiva, consulte las descripciones de la sección Configuración común.

En Windows, PowerShell busca la configuración en el Registro. Cualquier configuración que se encuentre en el Registro tenga prioridad. A continuación, PowerShell lee la configuración de JSON. Cualquier configuración que se encuentre en PowerShellPoliciesy no definida en el Registro, tenga prioridad sobre la configuración que se encuentra en el nivel raíz de la configuración JSON.

Para más información, consulte about_Group_Policy_Settings.

Configuración para plataformas que no son windows

La siguiente configuración solo se aplica a las plataformas Linux y macOS.

Las claves siguientes se usan 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.

Opciones de configuración comunes

La siguiente configuración está disponible en todas las plataformas compatibles.

  • ConsoleSessionConfiguration
  • ExperimentalFeatures
  • ModuleLogging
  • ProtectedEventLogging
  • PSModulePath
  • ScriptBlockLogging
  • ScriptExecution
  • Transcription
  • UpdatableHelp

ConsoleSessionConfiguration

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

Esta clave contiene dos subclaves:

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

  • ConsoleSessionConfigurationName : especifica el nombre del punto de conexión 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

Nombres de las características experimentales que se van a habilitar en PowerShell. El valor predeterminado es una matriz vacía.

En el ejemplo siguiente se habilitan las características experimentales PSCommandNotFoundSuggestion y PSSubsystemPluginModel cuando se inicia PowerShell.

Ejemplo:

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

Para obtener más información sobre las características experimentales, consulte Uso de características 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 trueen . Cuando se habilita, 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 se deben registrar.

Ejemplo:

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

ProtectedEventLogging

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

  • EnableProtectedEventLogging - Si habilita esta configuración de directiva, los componentes que lo admiten usan el certificado que proporcione para cifrar los datos de registro antes de escribirlos en el registro. Los datos se cifran mediante el estándar de sintaxis de mensajes criptográficos (CMS). Puede usar 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 usarán para el cifrado.

Ejemplo:

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

PSModulePath

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

Advertencia

La configuración de una ruta de acceso del módulo AllUsers o CurrentUser aquí no cambia la ubicación de instalación con ámbito para los cmdlets de PowerShellGet como Install-Module. Estos cmdlets siempre usan las rutas de acceso del módulo predeterminadas .

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

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

En este ejemplo se muestra una PSModulePath configuración para un entorno de Windows:

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

En este ejemplo se muestra una PSModulePath configuración para un entorno de macOS o Linux:

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

En este ejemplo se muestra cómo insertar una variable de entorno en una PSModulePath configuración. Tenga en cuenta que, con la HOME variable de entorno y el / separador de directorios, esta sintaxis funciona en Windows, macOS y Linux.

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

En este ejemplo se usa una variable de entorno que solo funciona en macOS y Linux:

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

Nota:

Las variables de PowerShell no se pueden incrustar en PSModulePath configuraciones. PSModulePath Las configuraciones en Linux y macOS distinguen mayúsculas de minúsculas. Una PSModulePath configuración debe usar separadores de directorio válidos para la plataforma. En macOS y Linux, esto significa /. En Windows, tanto como /\ funcionan.

ScriptBlockLogging

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

  • EnableScriptBlockLogging - Si habilita esta configuración de directiva, PowerShell registra el procesamiento de comandos, bloques de scripts, funciones y scripts, tanto si se invocan de forma interactiva como a través de la automatización.
  • EnableScriptBlockInvocationLogging : habilita el registro de eventos de inicio y detención del bloque de scripts.

Ejemplo:

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

Transcripción

Esta configuración de directiva 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 opció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 deshabilitar el encabezado mediante esta configuración.
  • OutputDirectory : esta configuración 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 Start-Transcript.

UpdatableHelp

Esta configuración de directiva permite establecer el valor predeterminado del parámetro SourcePath en el Update-Help cmdlet . Este valor predeterminado se puede invalidar especificando un valor diferente mediante el parámetro SourcePath .

Ejemplo:

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