about_Using

  • Artículo

Descripción breve

Permite especificar espacios de nombres que se van a usar en la sesión.

Descripción larga

La using instrucción permite especificar espacios de nombres que se van a usar en la sesión. La adición de espacios de nombres simplifica el uso de clases y miembros de .NET y permite importar clases de módulos y ensamblados de script.

Las using instrucciones deben aparecer antes de cualquier otra instrucción de un script o módulo. Ninguna instrucción no confirmada puede precederla, incluidos los parámetros.

La using instrucción no debe contener ninguna variable.

La using instrucción no es la misma que el using: modificador de ámbito para las variables. Para obtener más información, consulte about_Remote_Variables.

Sintaxis de espacio de nombres

Para resolver los tipos de un espacio de nombres de .NET:

using namespace <.NET-namespace>

Especificar un espacio de nombres facilita la referencia de tipos por sus nombres cortos.

Ejemplo: adición de espacios de nombres para la resolución de nombres de tipo

El siguiente script obtiene el hash criptográfico de la cadena "Hola mundo".

Observe cómo y using namespace System.Textusing namespace System.IO simplifican las referencias a [UnicodeEncoding] en System.Text y [Stream] en y [MemoryStream] en System.IO.

using namespace System.Text
using namespace System.IO

[string]$string = "Hello World"
## Valid values are "SHA1", "SHA256", "SHA384", "SHA512", "MD5"
[string]$algorithm = "SHA256"

[byte[]]$stringBytes = [UnicodeEncoding]::Unicode.GetBytes($string)

[Stream]$memoryStream = [MemoryStream]::new($stringBytes)
$getFileHashSplat = @{
    InputStream = $memoryStream
    Algorithm   = $algorithm
}
$hashFromStream = Get-FileHash @getFileHashSplat
$hashFromStream.Hash.ToString()

Sintaxis del módulo

Para cargar clases y enumeraciones desde un módulo de PowerShell:

using module <module-name>

El valor de puede ser un nombre de <module-name> módulo, una especificación de módulo completa o una ruta de acceso a un archivo de módulo.

Cuando <module-name> es una ruta de acceso, la ruta de acceso puede ser completa o relativa. Una ruta de acceso relativa se resuelve en relación con el script que tiene la using instrucción .

Cuando <module-name> es un nombre o especificación de módulo, PowerShell busca en psModulePath el módulo especificado.

Una especificación de módulo es una tabla hash que tiene las siguientes claves.

  • ModuleName - Obligatorio Especifica el nombre del módulo.
  • GUID - Opcional Especifica el GUID del módulo.
  • También es necesario especificar al menos una de las tres claves siguientes.
    • ModuleVersion : especifica una versión mínima aceptable del módulo.
    • MaximumVersion : especifica la versión máxima aceptable del módulo.
    • RequiredVersion : especifica una versión exacta y necesaria del módulo. Esto no se puede usar con las otras claves de versión.

Import-Module y la #requires instrucción solo importan las funciones, alias y variables del módulo, tal como se define en el módulo. Las clases y enumeraciones no se importan.

La using module instrucción importa clases y enumeraciones desde el módulo raíz (ModuleToProcess) de un módulo de script o un módulo binario. No importa de forma coherente clases ni enumeraciones definidas en módulos anidados o en scripts con origen de puntos en el módulo raíz. Defina clases y enumeraciones que desea que estén disponibles para los usuarios fuera del módulo directamente en el módulo raíz.

Durante el desarrollo de un módulo de script, es habitual realizar cambios en el código y, a continuación, cargar la nueva versión del módulo mediante Import-Module con el parámetro Force . Esto funciona solo para los cambios en las funciones del módulo raíz. Import-Module no vuelve a cargar ningún módulo anidado. Además, no hay ninguna manera de cargar ninguna clase o enumeración actualizadas.

Para asegurarse de que ejecuta la versión más reciente, debe iniciar una nueva sesión. Las clases y enumeraciones definidas en PowerShell y importadas con una using instrucción no se pueden descargar.

Ejemplo: Carga de clases desde un módulo de script

En este ejemplo, un módulo de script de PowerShell denominado CardGames define las siguientes clases:

  • Presentación
  • Tarjeta

Import-Module y la #requires instrucción solo importan las funciones, alias y variables del módulo, tal como se define en el módulo. Las clases no se importan. El using module comando importa el módulo y también carga las definiciones de clase.

using module CardGames

[Deck]$deck = [Deck]::new()
$deck.Shuffle()
[Card[]]$hand1 = $deck.Deal(5)
[Card[]]$hand2 = $deck.Deal(5)
[Card[]]$hand3 = $deck.Deal(5)

Sintaxis de ensamblado

La sintaxis siguiente carga los tipos de .NET desde un ensamblado en un script al principio de la ejecución. Debe usar una ruta de acceso completa al archivo de ensamblado.

using assembly <.NET-assembly-path>

La using assembly instrucción es similar al uso del Add-Type cmdlet . Sin embargo, el Add-Type cmdlet agrega el tipo en el momento en que Add-Type se ejecuta, en lugar de al principio de la ejecución del script. Para obtener más información, vea Add-Type.

Ejemplo: Carga de tipos desde un ensamblado

En este ejemplo se carga un ensamblado para que se puedan usar sus clases al procesar datos. El siguiente script convierte los datos en un formato YAML.

using assembly './YamlDotNet.dll'
using namespace YamlDotNet

$yamlSerializer = [Serialization.Serializer]::new()

$info = [ordered]@{
  Inventory = @(
    @{ Name = 'Apples' ; Count = 1234 }
    @{ Name = 'Bagels' ; Count = 5678 }
  )
  CheckedAt = [datetime]'2023-01-01T01:01:01'
}

$yamlSerializer.Serialize($info)

Inventory:
- Name: Apples
  Count: 1234
- Name: Bagels
  Count: 5678
CheckedAt: 2023-01-01T01:01:01.0000000