New-PSRoleCapabilityFile

Skapar en fil som definierar en uppsättning funktioner som ska exponeras via en sessionskonfiguration.

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>]

Description

Cmdleten New-PSRoleCapabilityFile skapar en fil som definierar en uppsättning användarfunktioner som kan exponeras via sessionskonfigurationsfiler. Detta inkluderar att avgöra vilka cmdletar, funktioner och skript som är tillgängliga för användare. Kapacitetsfilen är en textfil som kan läsas av människor och som innehåller en hash-tabell med egenskaper och värden för sessionskonfiguration. Filen har filnamnstillägget .psrc och kan användas av mer än en sessionskonfiguration.

Alla parametrar New-PSRoleCapabilityFile i är valfria förutom parametern Path , som anger filsökvägen för filen. Om du inte inkluderar en parameter när du kör cmdleten kommenteras motsvarande nyckel i sessionskonfigurationsfilen ut, förutom där anges i parameterbeskrivningen. Om du till exempel inte inkluderar parametern AssembliesToLoad kommenteras avsnittet i sessionskonfigurationsfilen bort.

Om du vill använda rollfunktionsfilen i en sessionskonfiguration placerar du först filen i undermappen RoleCapabilities i en giltig PowerShell-modulmapp. Referera sedan till filen efter namn i fältet RoleDefinitions i en PowerShell-sessionskonfigurationsfil (.pssc).

Denna cmdlet introducerades i Windows PowerShell 5.0.

Exempel

Exempel 1: Skapa en tom rollfunktionsfil

I det här exemplet skapas en ny rollfunktionsfil som använder standardvärdena (tomma). Filen kan senare redigeras i en textredigerare för att ändra de här konfigurationsinställningarna.

New-PSRoleCapabilityFile -Path ".\ExampleFile.psrc"

Exempel 2: Skapa en rollfunktionsfil som gör det möjligt för användare att starta om tjänster och alla VDI-datorer

Det här exemplet skapar en exempelrollfunktionsfil som gör det möjligt för användare att starta om tjänster och datorer som matchar ett specifikt namnmönster. Namnfiltrering definieras genom att parametern ValidatePattern anges till det reguljära uttrycket VDI\d+.

$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 @roleParameters

Parametrar

-AliasDefinitions

Lägger till de angivna aliasen till sessioner som använder rollkapacitetsfilen. Ange en hash-tabell med följande nycklar:

  • Namn. Namnet på aliaset. Den här nyckeln krävs.
  • Värde. Kommandot som aliaset representerar. Den här nyckeln krävs.
  • Beskrivning. En textsträng som beskriver aliaset. Den här nyckeln är valfri.
  • Alternativ. Aliasalternativ. Den här nyckeln är valfri. Standardvärdet är Ingen. De godtagbara värdena för den här parametern är: None, ReadOnly, Constant, Private eller AllScope.

Exempelvis: @{Name="hlp";Value="Get-Help";Description="Gets help";Options="ReadOnly"}

Type:IDictionary[]
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-AssembliesToLoad

Anger de sammansättningar som ska läsas in i de sessioner som använder rollkapacitetsfilen.

Type:String[]
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-Author

Anger den användare som skapade rollfunktionsfilen.

Type:String
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-CompanyName

Identifierar det företag som skapade rollfunktionsfilen. Standardvärdet är Okänt.

Type:String
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-Copyright

Anger en copyright för rollfunktionsfilen. Om du utelämnar den här parametern New-PSRoleCapabilityFile genererar en copyright-instruktion med hjälp av värdet för parametern Författare .

Type:String
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-Description

Anger en beskrivning av rollfunktionsfilen.

Type:String
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-EnvironmentVariables

Anger miljövariablerna för sessioner som exponerar den här rollfunktionsfilen. Ange en hash-tabell där nycklarna är miljövariabelnamnen och värdena är miljövariabelvärdena.

Exempelvis: EnvironmentVariables=@{TestShare="\\\\Server01\TestShare"}

Type:IDictionary
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-FormatsToProcess

Anger formateringsfilerna (.ps1xml) som körs i sessioner som använder rollkapacitetsfilen. Värdet för den här parametern måste vara en fullständig eller absolut sökväg för formateringsfilerna.

Type:String[]
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-FunctionDefinitions

Lägger till de angivna funktionerna i sessioner som exponerar rollfunktionen. Ange en hash-tabell med följande nycklar:

  • Namn. Namnet på funktionen. Den här nyckeln krävs.
  • ScriptBlock. Funktionstext. Ange ett skriptblock. Den här nyckeln krävs.
  • Alternativ. Funktionsalternativ. Den här nyckeln är valfri. Standardvärdet är Ingen. De godtagbara värdena för den här parametern är: None, ReadOnly, Constant, Private eller AllScope.

Exempel:

@{Name="Get-PowerShellProcess";ScriptBlock={Get-Process PowerShell};Options="AllScope"}

Type:IDictionary[]
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-Guid

Anger en unik identifierare för rollkapacitetsfilen. Om du utelämnar den här parametern New-PSRoleCapabilityFile genererar ett GUID för filen. Om du vill skapa ett nytt GUID i PowerShell skriver du [guid]::NewGuid().

Type:Guid
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-ModulesToImport

Anger de moduler som automatiskt importeras till sessioner som använder rollkapacitetsfilen. Som standard visas alla kommandon i de listade modulerna. När de används med VisibleCmdlets eller VisibleFunctions kan kommandon som är synliga från de angivna modulerna begränsas.

Varje modul som används i värdet för den här parametern kan representeras av en sträng eller en hash-tabell. En modulsträng består endast av namnet på modulen. En modulhashtabell kan innehålla ModuleName, ModuleVersion och GUID-nycklar . Endast ModuleName-nyckeln krävs.

Följande värde består till exempel av en sträng och en hash-tabell. Alla kombinationer av strängar och hash-tabeller är giltiga i valfri ordning.

"TroubleshootingPack", @{ModuleName="PSDiagnostics"; ModuleVersion="1.0.0.0";GUID="c61d6278-02a3-4618-ae37-a524d40a7f44"}

Type:Object[]
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-Path

Anger sökvägen och filnamnet för rollkapacitetsfilen. Filen måste ha filnamnstillägget .psrc .

Type:String
Position:0
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-ScriptsToProcess

Anger skript som ska läggas till i sessioner som använder rollkapacitetsfilen. Ange sökvägen och filnamnen för skripten. Värdet för den här parametern måste vara en fullständig eller absolut sökväg till skriptfilnamnen.

Type:String[]
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-TypesToProcess

Anger typfiler (.ps1xml) som ska läggas till i sessioner som använder rollkapacitetsfilen. Ange filnamn av typen . Värdet för den här parametern måste vara en fullständig eller absolut sökväg för typfilnamnen.

Type:String[]
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-VariableDefinitions

Anger variabler som ska läggas till i sessioner som använder rollkapacitetsfilen. Ange en hash-tabell med följande nycklar:

  • Namn. Namnet på variabeln. Den här nyckeln krävs.
  • Värde. Variabelvärde. Den här nyckeln krävs.
  • Alternativ. Variabelalternativ. Den här nyckeln är valfri. Standardvärdet är Ingen. De godtagbara värdena för den här parametern är: None, ReadOnly, Constant, Private eller AllScope.

Exempelvis: @{Name="WarningPreference";Value="SilentlyContinue";Options="AllScope"}

Type:Object
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-VisibleAliases

Begränsar aliasen i sessionen till de alias som anges i värdet för den här parametern, plus eventuella alias som du definierar i parametern AliasDefinition . Jokertecken stöds. Som standard visas alla alias som definieras av PowerShell-motorn och alla alias som moduler exporterar i sessionen.

Om du till exempel vill begränsa tillgängliga alias till gm och gcm använder du den här syntaxen: VisibleAliases="gcm", "gp"

När en Visible-parameter ingår i rollfunktionsfilen tar PowerShell bort cmdleten Import-Module och dess ipmo alias från sessionen.

Type:String[]
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:True

-VisibleCmdlets

Begränsar cmdletarna i sessionen till de som anges i värdet för den här parametern. Jokertecken och modulkvalificerade namn stöds.

Som standard visas alla cmdletar som modulerna i sessionsexporten har i sessionen. Använd parametrarna SessionType och ModulesToImport för att avgöra vilka moduler och snapin-moduler som importeras till sessionen. Om inga moduler i ModulesToImport exponerar cmdleten New-PSRoleCapabilityFile försöker läsa in lämplig modul.

När en Visible-parameter ingår i sessionskonfigurationsfilen tar PowerShell bort cmdleten Import-Module och dess ipmo alias från sessionen.

Type:Object[]
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:True

-VisibleExternalCommands

Begränsar de externa binärfiler, skript och kommandon som kan köras i sessionen till de som anges i värdet för den här parametern.

Som standard visas inga externa kommandon i den här sessionen.

När en Visible-parameter ingår i sessionskonfigurationsfilen tar PowerShell bort cmdleten Import-Module och dess ipmo alias från sessionen.

Type:String[]
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-VisibleFunctions

Begränsar funktionerna i sessionen till de som anges i värdet för den här parametern, plus alla funktioner som du definierar i parametern FunctionDefinitions . Jokertecken stöds.

Som standard visas alla funktioner som exporteras av moduler i sessionen i den sessionen. Använd parametrarna SessionType och ModulesToImport för att avgöra vilka moduler som importeras till sessionen.

När en Visible-parameter ingår i sessionskonfigurationsfilen tar PowerShell bort cmdleten Import-Module och dess ipmo alias från sessionen.

Type:Object[]
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:True

-VisibleProviders

Begränsar PowerShell-providrar i sessionen till de som anges i värdet för den här parametern. Jokertecken stöds.

Som standard visas alla leverantörer som exporteras av en modul i sessionen i sessionen. Använd parametrarna SessionType och ModulesToImport för att avgöra vilka moduler som importeras till sessionen.

När en Visible-parameter ingår i sessionskonfigurationsfilen tar PowerShell bort cmdleten Import-Module och dess ipmo alias från sessionen.

Type:String[]
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:True