Register-ArgumentCompleter

Register-ArgumentCompleter
    -CommandName <String[]>
    -ScriptBlock <ScriptBlock>
    [-Native]
    [<CommonParameters>]

Register-ArgumentCompleter
    -ParameterName <String>
    -ScriptBlock <ScriptBlock>
    [-CommandName <String[]>]
    [<CommonParameters>]

Polecenie cmdlet Register-ArgumentCompleter rejestruje niestandardowy moduł uzupełniania argumentów. Moduł uzupełniania argumentów umożliwia zapewnienie dynamicznego uzupełniania kart w czasie wykonywania dla dowolnego określonego polecenia.

Wywołając to polecenie za pomocą parametru CommandName i bez parametru ParameterName lub Native parametrów, polecenie jest uruchamiane tak, jakby określono parametr Native. Zapobiega to pracy elementu completer argumentu dla parametrów poleceń programu PowerShell. Zawsze określ parametr ParameterName, gdy chcesz zarejestrować moduł uzupełniania argumentów dla poleceń programu PowerShell.

Poniższy przykład rejestruje completer argumentu dla parametru identyfikatora polecenia cmdlet .

$s = {
    param(
        $commandName,
        $parameterName,
        $wordToComplete,
        $commandAst,
        $fakeBoundParameters
    )

    (Get-TimeZone -ListAvailable).Id | Where-Object {
        $_ -like "$wordToComplete*"
    } | ForEach-Object {
        "'$_'"
    }
}

Register-ArgumentCompleter -CommandName Set-TimeZone -ParameterName Id -ScriptBlock $s

Pierwsze polecenie tworzy blok skryptu, który przyjmuje wymagane parametry, które są przekazywane, gdy użytkownik naciska Tab. Aby uzyskać więcej informacji, zobacz opis parametru ScriptBlock.

W bloku skryptu dostępne wartości Identyfikator są pobierane przy użyciu polecenia cmdlet Get-TimeZone. Właściwość Id dla każdej strefy czasowej jest potokowana do polecenia cmdlet Where-Object. Polecenie cmdlet Where-Object filtruje wszystkie identyfikatory, które nie zaczynają się od wartości podanej przez $wordToComplete, która reprezentuje tekst wpisany przez użytkownika przed naciśnięciem tab. Filtrowane identyfikatory są przesyłane potokami do polecenia cmdlet ForEach-Object, które otacza każdą wartość w cudzysłowach w celu obsługi wartości zawierających spacje.

Drugie polecenie rejestruje completer argumentów, przekazując skryptblock, Nazwa parametruid i CommandNameSet-TimeZone.

Poniższy przykład zastępuje uzupełnianie kart dla parametru nazwa polecenia cmdlet i zwraca tylko uruchomione usługi.

$s = {
    param(
        $commandName,
        $parameterName,
        $wordToComplete,
        $commandAst,
        $fakeBoundParameters
    )

    $services = Get-Service | Where-Object {
        $_.Status -eq 'Running' -and $_.Name -like "$wordToComplete*"
    }

    $services | ForEach-Object {
        New-Object -Type System.Management.Automation.CompletionResult -ArgumentList @(
            $_.Name          # completionText
            $_.Name          # listItemText
            'ParameterValue' # resultType
            $_.Name          # toolTip
        )
    }
}

Register-ArgumentCompleter -CommandName Stop-Service -ParameterName Name -ScriptBlock $s

Pierwsze polecenie tworzy blok skryptu, który przyjmuje wymagane parametry, które są przekazywane, gdy użytkownik naciska Tab. Aby uzyskać więcej informacji, zobacz opis parametru ScriptBlock.

W bloku skryptu pierwsze polecenie pobiera wszystkie uruchomione usługi przy użyciu polecenia cmdlet Where-Object. Usługi są przesyłane potokami do polecenia cmdlet ForEach-Object. Polecenie cmdlet ForEach-Object tworzy nowy obiekt System.Management.Automation.CompletionResult i wypełnia go nazwą bieżącej usługi (reprezentowaną przez zmienną potoku $_.Name).

Obiekt CompletionResult umożliwia podanie dodatkowych szczegółów dla każdej zwróconej wartości:

• completionText (Ciąg) — tekst, który ma być używany jako wynik automatycznego uzupełniania. Jest to wartość wysłana do polecenia .
• listItemText (ciąg) — tekst, który ma być wyświetlany na liście, na przykład gdy użytkownik naciska ctrl+spacji. Program PowerShell używa go tylko do wyświetlania. Po wybraniu polecenia nie jest przekazywany do polecenia.
• resultType (CompletionResultType) — typ wyniku ukończenia.
• toolTip (ciąg) — tekst etykietki narzędzia ze szczegółami wyświetlanymi na temat obiektu. Jest to widoczne, gdy użytkownik wybierze element po naciśnięciu Ctrl+spacji.

Możesz użyć parametru Native, aby zapewnić uzupełnianie tabulacji dla natywnego polecenia. W poniższym przykładzie dodano uzupełnianie tabulacji dla interfejsu wiersza polecenia (CLI) dotnet.

$scriptblock = {
    param(
        $wordToComplete,
        $commandAst,
        $cursorPosition
    )

    dotnet complete --position $cursorPosition $commandAst.ToString() | ForEach-Object {
        [System.Management.Automation.CompletionResult]::new(
            $_,               # completionText
            $_,               # listItemText
            'ParameterValue', # resultType
            $_                # toolTip
        )
    }
}

Register-ArgumentCompleter -Native -CommandName dotnet -ScriptBlock $scriptblock

Pierwsze polecenie tworzy blok skryptu, który przyjmuje wymagane parametry, które są przekazywane, gdy użytkownik naciska Tab. Aby uzyskać więcej informacji, zobacz opis parametru ScriptBlock.

W bloku skryptu polecenie dotnet complete wykonuje uzupełnianie karty. Wyniki są przesyłane potokiem do polecenia cmdlet ForEach-Object, które używa nowej metody statycznejSystem.Management.Automation.CompletionResult, aby utworzyć obiekt CompletionResult dla każdej wartości.

To polecenie cmdlet obsługuje typowe parametry: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction i -WarningVariable. Aby uzyskać więcej informacji, zobacz about_CommonParameters.

Nie można przekazywać obiektów do tego cmdletu.

To polecenie cmdlet nie zwraca żadnych danych wyjściowych.