about_Using

Descrição curta

Permite que você especifique namespaces a serem usados na sessão.

Descrição longa

A instrução using permite que você especifique namespaces a serem usados na sessão. A adição de namespaces simplifica o uso de classes e membros do .NET e permite importar classes de módulos de script e assemblies.

As instruções using devem vir antes de qualquer outra instrução em um script ou módulo. Nenhuma instrução não descompactada pode precedê-la, incluindo parâmetros.

A instrução using não deve conter variáveis.

A instrução using não é a mesma que o modificador de escopo Using: para variáveis. Para obter mais informações, consulte about_Remote_Variables.

Sintaxe de namespace

Para resolver tipos de um namespace do .NET:

using namespace <.NET-namespace>

Especificar um namespace facilita a referência de tipos por seus nomes curtos.

Exemplo – Adicionar namespaces para resolução de nome de tipo

O script a seguir obtém o hash criptográfico da cadeia de caracteres "Olá, Mundo".

Observe como o using namespace System.Text e using namespace System.IO simplificam as referências para [UnicodeEncoding] em System.Text e [Stream] e [MemoryStream] em 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()

Sintaxe do módulo

Para carregar classes e enumerações de um módulo do PowerShell:

using module <module-name>

O valor de <module-name> pode ser um nome de módulo, uma especificação de módulo completa ou um caminho para um arquivo de módulo.

Quando <module-name> é um caminho, o caminho pode ser totalmente qualificado ou relativo. Um caminho relativo é resolvido em relação ao script que tem a instrução using.

Quando <module-name> é uma especificação de nome ou módulo, o PowerShell pesquisa o PSModulePath para o módulo especificado.

Uma especificação de módulo é um hashtable que tem as seguintes chaves.

• ModuleName - necessário especifica o nome do módulo.
• GUID - opcional especifica o GUID do módulo.
• Também é necessário para especificar pelo menos uma das três chaves abaixo.
  • ModuleVersion – especifica uma versão mínima aceitável do módulo.
  • MaximumVersion – especifica a versão máxima aceitável do módulo.
  • RequiredVersion – especifica uma versão exata e necessária do módulo. Isso não pode ser usado com as outras chaves de versão.

Import-Module e a instrução #Requires importam apenas as funções, os aliases e as variáveis do módulo, conforme definido pelo módulo. Classes e enumerações não são importadas.

A instrução using module importa classes e enumerações do módulo raiz (ModuleToProcess) de um módulo de script ou módulo binário. Ele não importa consistentemente classes ou enumerações definidas em módulos aninhados ou em scripts que são originados no módulo raiz. Defina classes e enumerações que você deseja estar disponíveis para usuários fora do módulo diretamente no módulo raiz.

Durante o desenvolvimento de um módulo de script, é comum fazer alterações no código e carregar a nova versão do módulo usando Import-Module com o parâmetro Force. Isso funciona apenas para alterações em funções no módulo raiz. Import-Module não recarrega nenhum módulo aninhado. Além disso, não há como carregar classes ou enumerações atualizadas.

Para garantir que você esteja executando a versão mais recente, inicie uma nova sessão. Classes e enumerações definidas no PowerShell e importadas com uma instrução using não podem ser descarregadas.

Exemplo – Carregar classes de um módulo de script

Neste exemplo, um módulo de script do PowerShell chamado CardGames define as seguintes classes:

• Deck
• de Cartão

Import-Module e a instrução #Requires importam apenas as funções, os aliases e as variáveis do módulo, conforme definido pelo módulo. As classes não são importadas. O comando using module importa o módulo e também carrega as definições de classe.

using module CardGames

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

Sintaxe do assembly

A sintaxe a seguir carrega tipos .NET de um assembly em um script no início da execução. Você deve usar um caminho totalmente qualificado para o arquivo de assembly.

using assembly <.NET-assembly-path>

A instrução using assembly é semelhante ao uso do cmdlet Add-Type. No entanto, o cmdlet Add-Type adiciona o tipo no momento em que Add-Type é executado, em vez de no início da execução do script. Para obter mais informações, consulte de Tipo de Adição.

Exemplo – Carregar tipos de um assembly

Este exemplo carrega um assembly para que suas classes possam ser usadas ao processar dados. O script a seguir converte dados em um 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