about_Using

Descrição breve

Permite especificar namespaces a serem usados na sessão.

Descrição longa

A using instrução permite especificar 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 using instruções devem vir antes de quaisquer outras instruções em um script ou módulo. Nenhuma declaração não comentada pode precedê-la, incluindo parâmetros.

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

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

Sintaxe do namespace

Para resolver tipos de um namespace .NET:

using namespace <.NET-namespace>

A especificação de 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 para a cadeia de caracteres "Hello World".

Observe como o using namespace System.Text e using namespace System.IO simplificar as referências a [UnicodeEncoding] in System.Text e [Stream][MemoryStream] in 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 pode ser um nome de módulo, uma especificação de módulo completo ou um caminho para um arquivo de <module-name> 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 using instrução.

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

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

• ModuleName - Obrigatório Especifica o nome do módulo.
• GUID - Opcional Especifica o GUID do módulo.
• Também é necessário 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 #requires instrução importa apenas as funções, aliases e variáveis do módulo, conforme definido pelo módulo. Classes e enumerações não são importadas.

A using module instrução 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 dot-sourced no módulo raiz. Defina classes e enumerações que você deseja que estejam 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, em seguida, 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ê está executando a versão mais recente, você deve iniciar uma nova sessão. Classes e enumerações definidas no PowerShell e importadas com uma using instrução 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:

• Conjunto
• Cartão

Import-Module e a #requires instrução importa apenas as funções, aliases e variáveis do módulo, conforme definido pelo módulo. As classes não são importadas. O using module comando 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 using assembly instrução é semelhante ao uso do Add-Type cmdlet. No entanto, o Add-Type cmdlet 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 Add-Type.

Exemplo - Tipos de carga 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