sobre_Utilizar

Breve descrição

Permite indicar quais namespaces são usados na sessão.

Descrição longa

A using instrução permite especificar quais namespaces são usados na sessão. Adicionar namespaces simplifica o uso de classes .NET e membro e permite importar classes de módulos de script e assemblies.

As instruções using 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 instrução using não deve conter variáveis.

A using instrução não deve ser confundida com o modificador de using: escopo para variáveis. Para mais informações, veja about_Remote_Variables.

Sintaxe do namespace

Para especificar namespaces .NET a partir dos quais resolver tipos:

using namespace <.NET-namespace>

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

Sintaxe do módulo

Para carregar classes 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 completo 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 contém a instrução using.

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

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 uma das três chaves abaixo. Essas chaves não podem ser usadas juntas.
  • ModuleVersion - Especifica uma versão mínima aceitável do módulo.
  • RequiredVersion - Especifica uma versão exata e necessária do módulo.
  • MaximumVersion - Especifica a versão máxima aceitável do módulo.

A using module instrução importa classes do módulo raiz (ModuleToProcess) de um módulo de script ou módulo binário. Ele não importa consistentemente classes definidas em módulos aninhados ou classes definidas em scripts que são dot-sourced para o módulo. As classes que você deseja que estejam disponíveis para usuários fora do módulo devem ser definidas 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 de funções no módulo raiz. Import-Module não recarrega nenhum módulo aninhado. Além disso, não há como carregar classes atualizadas.

Para garantir que você esteja executando a versão mais recente, você deve descarregar o módulo usando o Remove-Module cmdlet. Remove-Module Remove o módulo raiz, todos os módulos aninhados e quaisquer classes definidas nos módulos. Em seguida, você pode recarregar o módulo e as classes usando Import-Module e a using module instrução.

Sintaxe de montagem

Para pré-carregar tipos de um assembly .NET:

using assembly <.NET-assembly-path>

Carregar um assembly pré-carrega tipos .NET desse assembly em um script no momento da análise. Isso permite que você crie novas classes do PowerShell que usam tipos do assembly pré-carregado.

Se você não estiver criando novas classes do PowerShell, use o Add-Type cmdlet. Para obter mais informações, consulte Add-Type.

Exemplos

Exemplo 1 - Adicionar namespaces para resolução typename

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] to [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)
$hashfromstream = Get-FileHash -InputStream $memorystream `
  -Algorithm $algorithm
$hashfromstream.Hash.ToString()

Exemplo 2 - Carregar classes de um módulo de script

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

• CardGames.Deck
• CardGames.Card

Import-Module e a instrução #requires importam apenas as funções, aliases e 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
using namespace CardGames

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

Exemplo 3 - Classes de carga de um assembly

Este exemplo carrega um assembly para que suas classes possam ser usadas para criar novas classes do PowerShell. O script a seguir cria uma nova classe do PowerShell que é derivada da classe DirectoryContext .

using assembly 'C:\Program Files\PowerShell\7\System.DirectoryServices.dll'
using namespace System.DirectoryServices.ActiveDirectory

class myDirectoryClass : System.DirectoryServices.ActiveDirectory.DirectoryContext
{

  [DirectoryContext]$domain

  myDirectoryClass([DirectoryContextType]$ctx) : base($ctx)
  {
    $this.domain = [DirectoryContext]::new([DirectoryContextType]$ctx)
  }

}

$myDomain = [myDirectoryClass]::new([DirectoryContextType]::Domain)
$myDomain

domain                                                    Name UserName ContextType
------                                                    ---- -------- -----------
System.DirectoryServices.ActiveDirectory.DirectoryContext                    Domain