about_Using

Artigo
11/06/2024

Descrição breve

Permite especificar namespaces a serem usados na sessão.

Descrição longa

A using instrução 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 que você importe classes de módulos e assemblies de script.

As using instruções devem vir antes de quaisquer outras instruções em um script ou módulo. Nenhuma instruçã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 using: modificador de escopo para variáveis. Para obter mais informações, consulte about_Remote_Variables.

Sintaxe de namespace

Para resolver tipos de um namespace .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 para a cadeia de caracteres "Hello World".

Observe como o using namespace System.Text e using namespace System.IO simplificam as referências a [UnicodeEncoding] in System.Text e [Stream] e [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 completa do módulo 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 contém a using instrução.

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 é uma tabela de hash 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 originados por pontos 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 carregar a nova versão do módulo usando Import-Module 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, 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, e não no início da execução do script. Para obter mais informações, consulte Add-Type.

Exemplo - Tipos de carga de uma montagem

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

Compartilhar via