Dela via

New-PSRoleCapabilityFile

  • Referens
Modul:
Microsoft.PowerShell.Core

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 omfattar att avgöra vilka cmdletar, funktioner och skript som är tillgängliga för användare. Funktionsfilen ä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 för New-PSRoleCapabilityFile är valfria förutom parametern Path, som anger filsökvägen för filen. Om du inte tar med 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 ut.

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

Den här cmdleten 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 dessa konfigurationsinställningar.

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 ange parametern ValidatePattern 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 i sessioner som använder rollfunktionsfilen. 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 acceptabla värdena för den här parametern är: None, ReadOnly, Constant, Private eller AllScope.

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

Typ:IDictionary[]
Position:Named
Standardvärde:None
Obligatorisk:False
Godkänn pipeline-indata:False
Godkänn jokertecken:False

-AssembliesToLoad

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

Typ:String[]
Position:Named
Standardvärde:None
Obligatorisk:False
Godkänn pipeline-indata:False
Godkänn jokertecken:False

-Author

Anger den användare som skapade rollfunktionsfilen.

Typ:String
Position:Named
Standardvärde:None
Obligatorisk:False
Godkänn pipeline-indata:False
Godkänn jokertecken:False

-CompanyName

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

Typ:String
Position:Named
Standardvärde:None
Obligatorisk:False
Godkänn pipeline-indata:False
Godkänn jokertecken:False

-Copyright

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

Typ:String
Position:Named
Standardvärde:None
Obligatorisk:False
Godkänn pipeline-indata:False
Godkänn jokertecken:False

-Description

Anger en beskrivning av rollfunktionsfilen.

Typ:String
Position:Named
Standardvärde:None
Obligatorisk:False
Godkänn pipeline-indata:False
Godkänn jokertecken: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.

Till exempel: EnvironmentVariables=@{TestShare="\\\\Server01\TestShare"}

Typ:IDictionary
Position:Named
Standardvärde:None
Obligatorisk:False
Godkänn pipeline-indata:False
Godkänn jokertecken:False

-FormatsToProcess

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

Typ:String[]
Position:Named
Standardvärde:None
Obligatorisk:False
Godkänn pipeline-indata:False
Godkänn jokertecken: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.

Till exempel:

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

Typ:IDictionary[]
Position:Named
Standardvärde:None
Obligatorisk:False
Godkänn pipeline-indata:False
Godkänn jokertecken:False

-Guid

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

Typ:Guid
Position:Named
Standardvärde:None
Obligatorisk:False
Godkänn pipeline-indata:False
Godkänn jokertecken:False

-ModulesToImport

Anger de moduler som automatiskt importeras till sessioner som använder rollfunktionsfilen. Som standard visas alla kommandon i de listade modulerna. När de används med VisibleCmdlets eller VisibleFunctionskan kommandon som visas 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, ModuleVersionoch GUID- nycklar. Endast nyckeln ModuleName krävs.

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

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

Typ:Object[]
Position:Named
Standardvärde:None
Obligatorisk:False
Godkänn pipeline-indata:False
Godkänn jokertecken:False

-Path

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

Typ:String
Position:0
Standardvärde:None
Obligatorisk:True
Godkänn pipeline-indata:False
Godkänn jokertecken:False

-ScriptsToProcess

Anger skript som ska läggas till i sessioner som använder rollfunktionsfilen. 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 för skriptfilnamnen.

Typ:String[]
Position:Named
Standardvärde:None
Obligatorisk:False
Godkänn pipeline-indata:False
Godkänn jokertecken:False

-TypesToProcess

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

Typ:String[]
Position:Named
Standardvärde:None
Obligatorisk:False
Godkänn pipeline-indata:False
Godkänn jokertecken:False

-VariableDefinitions

Anger variabler som ska läggas till i sessioner som använder rollfunktionsfilen. 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.

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

Typ:Object
Position:Named
Standardvärde:None
Obligatorisk:False
Godkänn pipeline-indata:False
Godkänn jokertecken: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 någon Visible-parameter ingår i rollfunktionsfilen tar PowerShell bort Import-Module-cmdleten och dess ipmo alias från sessionen.

Typ:String[]
Position:Named
Standardvärde:None
Obligatorisk:False
Godkänn pipeline-indata:False
Godkänn jokertecken: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 visar 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 försöker New-PSRoleCapabilityFile läsa in rätt modul.

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

Typ:Object[]
Position:Named
Standardvärde:None
Obligatorisk:False
Godkänn pipeline-indata:False
Godkänn jokertecken: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 någon visible-parameter ingår i sessionskonfigurationsfilen tar PowerShell bort cmdleten Import-Module och dess ipmo alias från sessionen.

Typ:String[]
Position:Named
Standardvärde:None
Obligatorisk:False
Godkänn pipeline-indata:False
Godkänn jokertecken: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 någon visible-parameter ingår i sessionskonfigurationsfilen tar PowerShell bort cmdleten Import-Module och dess ipmo alias från sessionen.

Typ:Object[]
Position:Named
Standardvärde:None
Obligatorisk:False
Godkänn pipeline-indata:False
Godkänn jokertecken:True

-VisibleProviders

Begränsar PowerShell-leverantörerna 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 någon visible-parameter ingår i sessionskonfigurationsfilen tar PowerShell bort cmdleten Import-Module och dess ipmo alias från sessionen.

Typ:String[]
Position:Named
Standardvärde:None
Obligatorisk:False
Godkänn pipeline-indata:False
Godkänn jokertecken:True