Aprenda todo sobre la transcripción de inicio de PowerShell

Como sugiere el nombre, el cmdlet Start-Transcript crea una transcripción de texto de una sesión de PowerShell. Este cmdlet resulta útil cuando desea revisar o compartir el contenido de una sesión anterior. También puede utilizar este cmdlet para solucionar problemas enviando la transcripción a alguien que pueda ayudarle.

En este tutorial, aprenderá a utilizar PowerShell Start-Transcript. Después de seguir este tutorial, conocerá las diferentes formas de iniciar una transcripción, cómo detenerla y cómo verla.

¿Listo para llevar tus habilidades de escritura de guiones al siguiente nivel? ¡Sigue leyendo para empezar!

Requisitos previos

Este tutorial será una demostración práctica. Si desea seguirnos, asegúrese de tener una computadora con Windows PowerShell 5.1 o PowerShell 7+ en cualquier plataforma compatible. Este tutorial utilizará una PC con Windows 10 con PowerShell 7.2.5.

Iniciar y detener una transcripción

Puede ejecutar el cmdlet Start-Transcript sin ningún parámetro para iniciar una transcripción. Este cmdlet inicia una transcripción de la sesión actual y la guardará en el directorio de documentos de su usuario con un nombre con marca de tiempo.

Este cmdlet genera automáticamente un nombre aleatorio con caracteres aleatorios para el archivo de transcripción. Este comportamiento evita sobrescribir archivos existentes y garantiza que si inicia varias transcripciones, cada una tendrá un nombre único.

1. Primero, abra PowerShell como administrador.

Los cmdlets Start-Transcript y Stop-Transcript deben ejecutarse en un símbolo del sistema elevado de PowerShell para que la transcripción incluya todos los comandos ejecutados durante la sesión.

2. Para iniciar una transcripción, ejecute el siguiente comando.

Start-Transcript

Verá un resultado similar al siguiente. La anatomía del archivo de transcripción consta del siguiente patrón.

<%userprofile%\Documents>\PowerShell_transcript.<hostname>.<random string>.<timestamp>.txt

3. Ejecute el comando $PSVersionTable para que su transcripción de PowerShell tenga algún contenido.

$PSVersionTable

4. Detenga la transcripción ejecutando el siguiente comando después de ejecutar su script o lo que quiera registrar. Este cmdlet detiene la transcripción actual y guarda el archivo.

Stop-Transcript

5. Vea la transcripción de PowerShell abriéndola en un editor de texto o ejecutando el cmdlet Get-Content, como se muestra a continuación.

Get-Content -Path '<%userprofile%\Documents>\PowerShell_transcript.<hostname>.<random string>.<timestamp>.txt'

Verá un resultado similar al siguiente. Como puede ver, el cmdlet Start-Transcript guarda todo, desde la consola en el archivo de transcripción, incluido el comando que ejecutó, el resultado e incluso los errores.

Este comportamiento puede resultar útil cuando desea compartir la transcripción de su sesión con otras personas, como el soporte del proveedor, para solucionar problemas.

Los cmdlets Start-Transcript y Stop-Transcript deben ejecutarse en la misma sesión para que se complete la transcripción. Si inicia una transcripción en una sesión de PowerShell, intente verla en otra sesión de PowerShell; los comandos que ejecute no aparecerán en la transcripción.

Especificación de una ruta de transcripción

Ahora que sabe cómo iniciar y detener una transcripción de PowerShell, puede ver algunos de los parámetros que puede usar con este cmdlet.

¿Qué sucede si no desea guardar la transcripción en el directorio de documentos de su usuario? ¿Quieres guardarlo en una ubicación distinta a la predeterminada?

Afortunadamente, el cmdlet Start-Transcript tiene un parámetro Path que le permite especificar una ruta personalizada para la transcripción.

Por qué querrías hacer esto? Hay unas pocas razones.

Es posible que desees guardar la transcripción en una ubicación compartida para que otros puedan verla.
Es posible que desee guardarlo en una ubicación supervisada por algún otro proceso como Azure Monitor Logs and Analytics.

Cualquiera sea el motivo, el cmdlet Start-Transcript lo tiene cubierto.

Salida a un directorio y nombre de archivo personalizados

Ejecute el siguiente comando para especificar una ruta personalizada para la transcripción de PowerShell. Como puede ver, está guardando la transcripción en la carpeta C:\Public. Puede cambiar esta ruta a cualquier ruta válida en su sistema.

Start-Transcript -Path C:\\Public\\logfiles\\PS-logs.txt
Stop-Transcript

Si el directorio no existe, Start-Transcript creará el directorio en su ruta específica.

Tenga en cuenta que debe especificar la ruta completa, incluido el nombre del archivo y la extensión. Si no especifica un nombre de archivo, Start-Transcript no podrá crear el archivo de transcripción y obtendrá un error, como se muestra a continuación.

Ahora, confirme que el archivo de transcripción existe en la ubicación especificada.

Get-ChildItem C:\\Public\\logfiles

Debería ver el archivo de transcripción en el resultado, como se muestra a continuación.

Salida a un directorio personalizado con el nombre de archivo predeterminado

Otra forma de generar Start-Transcript es especificar el parámetro -OutputDirectory seguido de la ruta del directorio personalizado. Este parámetro le permite establecer la ruta donde desea guardar el archivo de transcripción sin especificar el nombre del archivo.

Tal como está, este parámetro genera un nombre de archivo aleatorio para la transcripción en la ruta que especifique. Es posible que desee utilizar este parámetro si está ejecutando varias transcripciones de PowerShell y no desea especificar cada nombre de archivo.

Para utilizar este parámetro, ejecute el siguiente comando.

Start-Transcript -OutputDirectory C:\\Public\\logfiles\\
Stop-Transcript

Como puede ver a continuación, PowerShell genera un nombre de archivo aleatorio para la transcripción y lo guarda en la ruta especificada.

Eliminación del encabezado inicial

De forma predeterminada, el cmdlet Start-Transcript incluye información de encabezado en el archivo de salida. Esta información rara vez es útil, por lo que tiene la opción de excluir el encabezado.

Por ejemplo, si va a compartir la transcripción con alguien para solucionar problemas, todo lo que necesita saber es qué comandos de PowerShell se ejecutaron y el resultado.

Cuando la información adicional en el encabezado no es necesaria, puede excluirla con el parámetro -UseMinimalHeader de Start-Transcript.

Ejecute los siguientes comandos para incluir un encabezado mínimo en su transcripción de PowerShell.

Start-Transcript -OutputDirectory C:\\Public\\logfiles\\ -UseMinimalHeader
$PSVersionTable
Stop-Transcript

Ahora, mire el archivo de transcripción y verá que el encabezado es mucho más corto. Como puede ver en la captura de pantalla siguiente, el encabezado solo incluye las horas de inicio de la transcripción de PowerShell.

Get-Content C:\\Public\\logfiles\\PowerShell_transcript.atadc01.LFoo9G0u.20220719103620.txt

Evitar la sobrescritura de archivos de transcripción

Si está ejecutando varias transcripciones de PowerShell, es posible que desee evitar que una sobrescriba a otra.

Por ejemplo, ejecute los siguientes comandos para crear un archivo de transcripción llamado C:\Public\logfiles\PS-log.txt.

Start-Transcript -Path C:\\Public\\logfiles\\PS-log.txt -UseMinimalHeader
Stop-Transcript

PowerShell sobrescribirá el archivo PS-log.txt sin previo aviso si ejecuta el mismo comando. Este comportamiento sería un desastre y habría perdido tiempo ejecutando la transcripción original.

Para evitar sobrescribir una transcripción existente, especifique el parámetro -NoClobber de Start-Transcript. Este parámetro hará que PowerShell genere un error si el archivo de transcripción ya existe.

Start-Transcript -Path C:\\Public\\logfiles\\PS-log.txt -NoClobber

PowerShell generará el siguiente error si el archivo PS-log.txt existe en la ruta.

Agregar a un archivo de transcripción existente

En lugar de crear nuevos archivos de transcripción, hay casos en los que preferiría agregar nuevas transcripciones a archivos de transcripción existentes.

Por ejemplo, suponga que tiene un archivo de transcripción que contiene la salida de todos los usuarios en su dominio de Active Directory. Más adelante, puede ejecutar Start-Transcript con el modificador -Append para agregar la nueva transcripción al mismo archivo mientras agrega un nuevo usuario a Active Directory.

Ejecute el siguiente comando para agregar nuevas transcripciones al archivo C:\Public\logfiles\PS-log.txt.

Start-Transcript -Path C:\\Public\\logfiles\\PS-log.txt -Append -UseMinimalHeader
Write-Host 'Appending Texts!'
Stop-Transcript

Verifique que el comando haya agregado la transcripción ejecutando el cmdlet Get-Content.

Get-Content -Path C:\\Public\\logfiles\\PS-log.txt

Conclusión

En este artículo, aprendió a utilizar el cmdlet Start-Transcript de PowerShell para crear transcripciones de sus sesiones de PowerShell.

También aprendió a personalizar esas transcripciones utilizando algunos parámetros disponibles. Las transcripciones pueden ser extremadamente útiles para documentar lo que ha hecho en PowerShell y compartirlas con otras personas para solucionar problemas.

Ahora que sabe cómo utilizar PowerShell Start-Transcript, comience a crear transcripciones de sus sesiones de PowerShell. No olvide invocar el parámetro -NoClobber, para no sobrescribir accidentalmente un archivo de transcripción existente. Por último, asegúrese siempre de detener sus transcripciones y no las deje ejecutándose indefinidamente.