New-PSRoleCapabilityFile
Erstellt eine Datei, die eine Reihe von Funktionen definiert, die über eine Sitzungskonfiguration verfügbar gemacht werden sollen.
Syntax
New-PSRoleCapabilityFile
[-Path] <String>
[-Guid <Guid>]
[-Author <String>]
[-Description <String>]
[-CompanyName <String>]
[-Copyright <String>]
[-ModulesToImport <Object[]>]
[-VisibleAliases <String[]>]
[-VisibleCmdlets <Object[]>]
[-VisibleFunctions <Object[]>]
[-VisibleExternalCommands <String[]>]
[-VisibleProviders <String[]>]
[-ScriptsToProcess <String[]>]
[-AliasDefinitions <IDictionary[]>]
[-FunctionDefinitions <IDictionary[]>]
[-VariableDefinitions <Object>]
[-EnvironmentVariables <IDictionary>]
[-TypesToProcess <String[]>]
[-FormatsToProcess <String[]>]
[-AssembliesToLoad <String[]>]
[<CommonParameters>] Beschreibung
Das New-PSRoleCapabilityFile Cmdlet erstellt eine Datei, die eine Reihe von Benutzerfunktionen definiert, die über Sitzungskonfigurationsdateien verfügbar gemacht werden können. Dies schließt die Ermittlung der Cmdlets, Funktionen und Skripts ein, die Benutzern zur Verfügung stehen. Die Funktionsdatei ist eine lesbare Textdatei, die eine Hashtabelle mit Sitzungskonfigurationseigenschaften und -werten enthält. Die Datei verfügt über eine PSRC-Dateinamenerweiterung und kann von mehreren Sitzungskonfigurationen verwendet werden.
Alle Parameter von New-PSRoleCapabilityFile sind optional, mit Ausnahme des Path-Parameters , der den Dateipfad für die Datei angibt. Wenn Sie beim Ausführen des Cmdlets keinen Parameter einschließen, wird der entsprechende Schlüssel in der Sitzungskonfigurationsdatei auskommentiert, außer wenn in der Parameterbeschreibung angegeben. Wenn Sie beispielsweise den AssemblysToLoad-Parameter nicht einschließen, wird dieser Abschnitt der Sitzungskonfigurationsdatei auskommentiert.
Um die Rollenfunktionsdatei in einer Sitzungskonfiguration zu verwenden, platzieren Sie die Datei zunächst in einen RoleCapabilities-Unterordner eines gültigen PowerShell-Modulordners. Verweisen Sie dann im Feld RoleDefinitions in einer Pssc-Datei (PowerShell-Sitzungskonfiguration) anhand des Namens auf die Datei.
Dieses Cmdlet wurde in Windows PowerShell 5.0 eingeführt.
Beispiele
Beispiel 1: Create einer leeren Rollenfunktionsdatei
In diesem Beispiel wird eine neue Rollenfunktionsdatei erstellt, die die (leeren) Standardwerte verwendet. Die Datei kann später in einem Text-Editor bearbeitet werden, um diese Konfigurationseinstellungen zu ändern.
New-PSRoleCapabilityFile -Path ".\ExampleFile.psrc"Beispiel 2: Create einer Rollenfunktionsdatei, mit der Benutzer Dienste und alle VDI-Computer neu starten können
In diesem Beispiel wird eine Beispieldatei für Rollenfunktionen erstellt, mit der Benutzer Dienste und Computer neu starten können, die einem bestimmten Namensmuster entsprechen. Die Namensfilterung wird definiert, indem der ValidatePattern-Parameter auf den regulären Ausdruck VDI\d+festgelegt wird.
$roleParameters = @{
Path = ".\Maintenance.psrc"
Author = "User01"
CompanyName = "Fabrikam Corporation"
Description = "This role enables users to restart any service and restart any VDI computer."
ModulesToImport = "Microsoft.PowerShell.Core"
VisibleCmdlets = "Restart-Service", @{
Name = "Restart-Computer"
Parameters = @{ Name = "ComputerName"; ValidatePattern = "VDI\d+" }
}
}
New-PSRoleCapabilityFile @roleParametersParameter
-AliasDefinitions
Fügt die angegebenen Aliase zu Sitzungen hinzu, die die Rollenfunktionsdatei verwenden. Geben Sie eine Hashtabelle mit den folgenden Schlüsseln ein:
- Name. Name des Alias. Dieser Schlüssel ist erforderlich.
- Wert. Der Befehl, den der Alias darstellt. Dieser Schlüssel ist erforderlich.
- Beschreibung Eine Textzeichenfolge, die den Alias beschreibt. Dieser Schlüssel ist optional.
- Optionen. Aliasoptionen. Dieser Schlüssel ist optional. Der Standardwert lautet „Keine“. Die zulässigen Werte für diesen Parameter sind: None, ReadOnly, Constant, Private oder AllScope.
Beispiel: @{Name="hlp";Value="Get-Help";Description="Gets help";Options="ReadOnly"}
| Type: | IDictionary[] |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-AssembliesToLoad
Gibt die Assemblys an, die in die Sitzungen geladen werden sollen, die die Rollenfunktionsdatei verwenden.
| Type: | String[] |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Author
Gibt den Benutzer an, der die Rollenfunktionsdatei erstellt hat.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-CompanyName
Identifiziert das Unternehmen, das die Rollenfunktionsdatei erstellt hat. Der Standardwert ist Unknown (Unbekannt).
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Copyright
Gibt ein Copyright für die Rollenfunktionsdatei an. Wenn Sie diesen Parameter weglassen, New-PSRoleCapabilityFile wird mithilfe des Werts des Parameters Author eine Copyright-Anweisung generiert.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Description
Gibt eine Beschreibung für die Rollenfunktionsdatei an.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-EnvironmentVariables
Gibt die Umgebungsvariablen für Sitzungen an, die diese Rollenfunktionsdatei verfügbar machen. Geben Sie eine Hashtabelle ein, in der die Schlüssel die Namen der Umgebungsvariablen und die Werte die Werte der Umgebungsvariablen sind.
Beispiel: EnvironmentVariables=@{TestShare="\\\\Server01\TestShare"}
| Type: | IDictionary |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-FormatsToProcess
Gibt die Formatierungsdateien (.ps1xml) an, die in Sitzungen ausgeführt werden, die die Rollenfunktionsdatei verwenden. Der Wert dieses Parameters muss ein vollständiger oder absoluter Pfad der Formatierungsdateien sein.
| Type: | String[] |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-FunctionDefinitions
Fügt die angegebenen Funktionen Zu Sitzungen hinzu, die die Rollenfunktion verfügbar machen. Geben Sie eine Hashtabelle mit den folgenden Schlüsseln ein:
- Name. Name der Funktion. Dieser Schlüssel ist erforderlich.
- Skriptblock. Funktionstext. Geben Sie einen Skriptblock ein. Dieser Schlüssel ist erforderlich.
- Optionen. Funktionsoptionen. Dieser Schlüssel ist optional. Der Standardwert lautet „Keine“. Die zulässigen Werte für diesen Parameter sind None, ReadOnly, Constant, Private oder AllScope.
Beispiel:
@{Name="Get-PowerShellProcess";ScriptBlock={Get-Process PowerShell};Options="AllScope"}
| Type: | IDictionary[] |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Guid
Gibt einen eindeutigen Bezeichner für die Rollenfunktionsdatei an. Wenn Sie diesen Parameter weglassen, New-PSRoleCapabilityFile generiert eine GUID für die Datei. Um eine neue GUID in PowerShell zu erstellen, geben Sie ein [guid]::NewGuid().
| Type: | Guid |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-ModulesToImport
Gibt die Module an, die automatisch in Sitzungen importiert werden, die die Rollenfunktionsdatei verwenden. Standardmäßig sind alle Befehle in den aufgelisteten Modulen sichtbar. Bei Verwendung mit VisibleCmdlets oder VisibleFunctions können die befehle eingeschränkt werden, die aus den angegebenen Modulen sichtbar sind.
Jedes Modul, das im Wert dieses Parameters verwendet wird, kann durch eine Zeichenfolge oder eine Hashtabelle dargestellt werden. Eine Modulzeichenfolge besteht nur aus dem Namen des Moduls. Eine Modulhashtabelle kann ModuleName-, ModuleVersion- und GUID-Schlüssel enthalten. Nur der ModuleName-Schlüssel ist erforderlich.
Beispielsweise besteht der folgende Wert aus einer Zeichenfolge und einer Hashtabelle. Jede Kombination aus Zeichenfolgen und Hashtabellen, in beliebiger Reihenfolge, ist gültig.
"TroubleshootingPack", @{ModuleName="PSDiagnostics"; ModuleVersion="1.0.0.0";GUID="c61d6278-02a3-4618-ae37-a524d40a7f44"}
| Type: | Object[] |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Path
Gibt den Pfad und Dateinamen der Rollenfunktionsdatei an. Die Datei muss über eine .psrc Dateinamenerweiterung verfügen.
| Type: | String |
| Position: | 0 |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-ScriptsToProcess
Gibt Skripts an, die Sitzungen hinzugefügt werden sollen, die die Rollenfunktionsdatei verwenden. Geben Sie den Pfad und die Dateinamen der Skripts ein. Der Wert dieses Parameters muss ein vollständiger oder absoluter Pfad der Skriptdateinamen sein.
| Type: | String[] |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-TypesToProcess
Gibt Typdateien (.ps1xml) an, die Sitzungen hinzugefügt werden sollen, die die Rollenfunktionsdatei verwenden. Geben Sie die Typdateinamen ein. Der Wert dieses Parameters muss ein vollständiger oder absoluter Pfad des Typs filenames sein.
| Type: | String[] |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-VariableDefinitions
Gibt Variablen an, die Sitzungen hinzugefügt werden sollen, die die Rollenfunktionsdatei verwenden. Geben Sie eine Hashtabelle mit den folgenden Schlüsseln ein:
- Name. Name der Variable. Dieser Schlüssel ist erforderlich.
- Wert. Variablenwert. Dieser Schlüssel ist erforderlich.
- Optionen. Variablenoptionen. Dieser Schlüssel ist optional. Der Standardwert lautet „Keine“. Die zulässigen Werte für diesen Parameter sind None, ReadOnly, Constant, Private oder AllScope.
Beispiel: @{Name="WarningPreference";Value="SilentlyContinue";Options="AllScope"}
| Type: | Object |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-VisibleAliases
Beschränkt die Aliase in der Sitzung auf die Aliase, die im Wert dieses Parameters angegeben sind, sowie alle Aliase, die Sie im AliasDefinition-Parameter definieren. Platzhalterzeichen werden unterstützt. Standardmäßig sind alle Aliase, die von der PowerShell-Engine definiert werden, und alle Aliase, die module exportieren, in der Sitzung sichtbar.
Verwenden Sie beispielsweise die folgende Syntax, um die verfügbaren Aliase auf gm und gcm zu beschränken: VisibleAliases="gcm", "gp"
Wenn ein Visible-Parameter in der Rollenfunktionsdatei enthalten ist, entfernt PowerShell das Cmdlet und seinen Import-Moduleipmo Alias aus der Sitzung.
| Type: | String[] |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | True |
-VisibleCmdlets
Beschränkt die Cmdlets in der Sitzung auf jene, die im Wert dieses Parameters angegeben wurden. Feldhalterzeichen und modulqualifizierte Namen werden unterstützt.
Standardmäßig sind alle Cmdlets, die die Module im Sitzungsexport enthalten, in der Sitzung sichtbar. Verwenden Sie die SessionType- und ModulesToImport-Parameter, um zu bestimmen, welche Module und Snap-Ins in die Sitzung importiert werden. Wenn das Cmdlet ohne ModuleToImport verfügbar gemacht wird, New-PSRoleCapabilityFile versucht, das entsprechende Modul zu laden.
Wenn ein Visible-Parameter in der Sitzungskonfigurationsdatei enthalten ist, entfernt PowerShell das Cmdlet und seinen Import-Moduleipmo Alias aus der Sitzung.
| Type: | Object[] |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | True |
-VisibleExternalCommands
Schränkt die externen Binärdateien, Skripts und Befehle, die in der Sitzung ausgeführt werden können, auf die im Wert dieses Parameters angegebenen ein.
Standardmäßig sind in dieser Sitzung keine externen Befehle sichtbar.
Wenn ein Visible-Parameter in der Sitzungskonfigurationsdatei enthalten ist, entfernt PowerShell das Cmdlet und seinen Import-Moduleipmo Alias aus der Sitzung.
| Type: | String[] |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-VisibleFunctions
Schränkt die Funktionen in der Sitzung auf die funktionen ein, die im Wert dieses Parameters angegeben sind, sowie alle Funktionen, die Sie im FunctionDefinitions-Parameter definieren. Platzhalterzeichen werden unterstützt.
Standardmäßig sind alle von Modulen in der Sitzung exportierten Funktionen in dieser Sitzung sichtbar. Verwenden Sie die Parameter SessionType und ModulesToImport , um zu bestimmen, welche Module in die Sitzung importiert werden.
Wenn ein Visible-Parameter in der Sitzungskonfigurationsdatei enthalten ist, entfernt PowerShell das Cmdlet und seinen Import-Moduleipmo Alias aus der Sitzung.
| Type: | Object[] |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | True |
-VisibleProviders
Beschränkt die PowerShell-Anbieter in der Sitzung auf die im Wert dieses Parameters angegebenen Anbieter. Platzhalterzeichen werden unterstützt.
Standardmäßig sind alle von einem Modul in der Sitzung exportierten Anbieter in der Sitzung sichtbar. Verwenden Sie die Parameter SessionType und ModulesToImport , um zu bestimmen, welche Module in die Sitzung importiert werden.
Wenn ein Visible-Parameter in der Sitzungskonfigurationsdatei enthalten ist, entfernt PowerShell das Cmdlet und seinen Import-Moduleipmo Alias aus der Sitzung.
| Type: | String[] |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | True |