Skip to content

Commit 900d8de

Browse files
author
Maddie Clayton
authored
Merge pull request #6427 from Azure/maddieclayton-patch-2
Move wiki changes to docs
2 parents dc4027b + 8ca6a0a commit 900d8de

File tree

2 files changed

+143
-93
lines changed

2 files changed

+143
-93
lines changed

‎documentation/development-docs/azure-powershell-developer-guide.md

Lines changed: 4 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ The Azure PowerShell Developer Guide was created to help with the development an
4040
- [After Development](#after-development)
4141
- [Misc](#misc)
4242
- [Publish to PowerShell Gallery](#publish-to-powershell-gallery)
43-
- [AsJob Parameters](#asjob-parameters)
43+
- [AsJob Parameter](#asjob-parameter)
4444
- [Argument Completers](#argument-completers)
4545
- [Resource Group Completer](#resource-group-completers)
4646
- [Location Completer](#location-completer)
@@ -52,8 +52,6 @@ The following prerequisites should be completed before contributing to the Azure
5252

5353
- Install [Visual Studio 2015](https://www.visualstudio.com/downloads/)
5454
- Install the latest version of [Git](https://git-scm.com/downloads)
55-
- Install the latest version of [WiX](http://wixtoolset.org/releases/)
56-
- After installation, ensure that the path to "WiX Toolset\bin" has been added to your `PATH` environment variable
5755
- Install the [`platyPS` module](https://github.com/Azure/azure-powershell/blob/preview/documentation/development-docs/help-generation.md#installing-platyps)
5856
- Set the PowerShell [execution policy](https://technet.microsoft.com/en-us/library/ee176961.aspx) to **Unrestricted** for the following versions of PowerShell:
5957
- `C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe`
@@ -116,8 +114,6 @@ By default, we build the `dll-Help.xml` files (used to display the help content
116114
msbuild build.proj /p:SkipHelp=true
117115
```
118116

119-
_Note_: when [updating the installer](#updating-the-installer), you **should not** skip the help generation step, as it removes the `dll-Help.xml` files from the wxi file.
120-
121117
## Running Tests
122118

123119
With the same terminal open from the previous section, run the cmdlet `Invoke-CheckinTests` to run all of the tests in the project
@@ -142,10 +138,9 @@ Before development, you must meet with the Azure PowerShell team to have a desig
142138

143139
Before submitting a design review, please be sure that you have read the [Azure PowerShell Design Guidelines](./azure-powershell-design-guidelines.md) document.
144140

145-
Please email the **azdevxpsdr** alias to set up this review and include the following information:
146-
- Short description of the top-level scenarios
147-
- Proposed cmdlet syntax
148-
- Sample output of cmdlets
141+
Please submit a design review here: https://github.com/Azure/azure-powershell-cmdlet-review-pr
142+
143+
_Note_: You will need to be part of the GitHub Azure org to see this repository. Please go to [this link](aka.ms/azuregithub) to become part of the Azure org.
149144

150145
We recommend using the `platyPS` module to easily generate markdown files that contains the above information and including the files in the email.
151146

‎documentation/development-docs/piping-in-powershell.md

Lines changed: 139 additions & 84 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,141 @@
1-
# Piping in PowerShell
1+
# Azure PowerShell Piping Scenarios
2+
3+
There are two main scenarios that we wish to enable in cmdlets for Azure PowerShell:
4+
- piping by value using an `InputObject` parameter
5+
- piping by property name using a `ResourceId` parameter
6+
7+
## Using the `InputObject` parameter
8+
9+
### Short explanation
10+
For all resources, `InputObject` should be implemented for the Remove/Set/Update cmdlets (and any other cmdlet where an existing resource is being operated on). The implementation of this will be a new parameter set:
11+
12+
```powershell
13+
Remove/Set/Update-AzureRm<ExampleResource> -InputObject <TypeOfExampleResource> <Other parameters that cannot be obtained from TypeOfExampleResource>
14+
```
15+
16+
For all child resources, `InputObject` should also be implemented for the Get/New cmdlets. The implementation of this will be a new parameter set:
17+
18+
```powershell
19+
Get/New-AzureRm<ExampleResource> -ParentObject <TypeOfParentOfExampleResource> <Other parameters that cannot be obtained from TypeOfParentOfExampleResource>
20+
```
21+
22+
### Long explanation
23+
This scenario should be used when piping objects around within the same module. For example, if you have a set of `Get-AzureRmFoo`, `Remove-AzureRmFoo`, and `Set-AzureRmFoo` cmdlets, the `Remove-AzureRmFoo` and `Set-AzureRmFoo` cmdlets should have a parameter set that takes the `InputObject` parameter of type `PSFoo` so that a user can do the following:
24+
25+
```powershell
26+
# --- Piping scenario ---
27+
# Setting and removing an individual object
28+
Get-AzureRmFoo -Name "FooName" -ResourceGroupName "RG" | Set-AzureRmFoo <additional parameters>
29+
Get-AzureRmFoo -Name "FooName" -ResourceGroupName "RG" | Remove-AzureRmFoo
30+
31+
# Setting and removing a collection of objects
32+
Get-AzureRmFoo | Set-AzureRmFoo <additional parameters>
33+
Get-AzureRmFoo | Remove-AzureRmFoo
34+
35+
36+
# --- Non-piping scenario ---
37+
# Setting and removing an individual object
38+
$foo = Get-AzureRmFoo -Name "FooName" -ResourceGroupName "RG"
39+
Set-AzureRmFoo -InputObject $foo <additional parameters>
40+
Remove-AzureRmFoo -InputObject $foo
41+
42+
# Setting and removing a collection of objects
43+
Get-AzureRmFoo | ForEach-Object { Set-AzureRmFoo -InputObject $_ <additional parameters> }
44+
Get-AzureRmFoo | ForEach-Object { Remove-AzureRmFoo -InputObject $_ }
45+
```
46+
47+
Another time that this scenario applies is when you have cmdlets for child resources that need information about the parent (top-level) resource. For example you can pipe in the whole parent object to the `New-AzureRmFooBar` and `Get-AzureRmFooBar` cmdlets to get the child resources, and then pipe the child resource object to the `Remove-AzureRmFooBar` and `Set-AzureRmFooBar` cmdlets.
48+
49+
```powershell
50+
# --- Piping scenario ---
51+
# Getting all of child resources from all of the parent resources and removing them
52+
Get-AzureRmFoo | Get-AzureRmFooBar | Remove-AzureRmFooBar
53+
54+
# Getting all of the child resources from all of the parent resources in a resource group and removing them
55+
Get-AzureRmFoo -ResourceGroupName "RG" | Get-AzureRmFooBar | Remove-AzureRmFooBar
56+
57+
# Getting all of the child resources from a specific parent resource and removing them
58+
Get-AzureRmFoo -ResourceGroupName "RG" -Name "FooName" | Get-AzureRmFooBar | Remove-AzureRmFooBar
59+
60+
61+
# --- Non-piping scenario ---
62+
# Getting all of the child resources from a specific parent resource and removing them
63+
$foo = Get-AzureRmFoo -ResourceGroupName "RG" -Name "FooName"
64+
$fooBar = Get-AzureRmFooBar -InputObject $foo
65+
Remove-AzureRmFooBar -InputObject $fooBar
66+
```
67+
68+
## Using the `ResourceId` parameter
69+
70+
### Short explanation
71+
For all resources, `ResourceId` should be implemented for the Remove/Set/Update cmdlets (and any other cmdlet where an existing resource is being operated on). The implementation of this will be a new parameter set:
72+
73+
```powershell
74+
Remove/Set/Update-AzureRm<ExampleResource> -ResourceId <string (accepts ExampleResource ResourceId> <Other parameters that cannot be obtained from ExampleResource ResourceId>
75+
```
76+
77+
For all child resources, `ResourceId` should also be implemented for the Get/New cmdlets. The implementation of this will be a new parameter set:
78+
79+
```powershell
80+
Get/New-AzureRm<ExampleResource> -ParentResourceId <string (accepts ResourceId of the parent of ExampleResource> <Other parameters that cannot be obtained from the ResourceId of the parent of ExampleResource>
81+
```
82+
83+
### Long explanation
84+
85+
In this scenario, we are using the generic cmdlets found in the `AzureRM.Resources` module. These cmdlets, `Find-AzureRmResource` and `Get-AzureRmResource`, return a `PSCustomObject` that has a `ResourceId` property, which is the unique identifier for the given resource. Since this identifier can parsed to get the name and resource group name for a top-level resource, we can create a parameter set that has a `ResourceId` parameter that accepts its value from the pipeline by property name, allowing us to accept piping from these generic cmdlets.
86+
87+
```powershell
88+
# --- Piping scenario ---
89+
# Remove all Foo objects in the current subscription
90+
Find-AzureRmResource -ResourceType Microsoft.Foo/foo | Remove-AzureRmFoo
91+
92+
# Remove all Foo objects in a given resource group
93+
Find-AzureRmResource -ResourceType Microsoft.Foo/foo -ResourceGroupEquals "RG" | Remove-AzureRmFoo
94+
95+
# Remove a specific Foo object
96+
Find-AzureRmResource -ResourceGroupEquals "RG" -ResourceNameEquals "FooName" | Remove-AzureRmFoo
97+
98+
99+
# -- Non-piping scenario ---
100+
# Removing all Foo objects in the current subscription
101+
Find-AzureRmResource -ResourceType Microsoft.Foo/foo | ForEach-Object { Remove-AzureRmFoo -ResourceId $_.ResourceId }
102+
103+
# Remove all Foo objects in a given resource group
104+
Find-AzureRmResource -ResourceType Microsoft.Foo/foo -ResourceGroupEquals "RG" | ForEach-Object { Remove-AzureRmFoo -ResourceId $_.ResourceId }
105+
106+
# Remove a specific Foo object
107+
Find-AzureRmResource -ResourceGroupEquals "RG" -ResourceNameEquals "FooName" | ForEach-Object { Remove-AzureRmFoo -ResourceId $_.ResourceId }
108+
```
109+
110+
To implement this scenario, please see the [`ResourceIdentifier`](https://github.com/Azure/azure-powershell/blob/preview/src/ResourceManager/Common/Commands.ResourceManager.Common/Utilities/Models/ResourceIdentifier.cs) class in the `Commands.ResourceManager.Common` project. This class will allow you to create a `ResourceIdentifier` object that accepts a `ResourceId` string in its constructor and has properties `ResourceName`, `ResourceGroupName`, and others.
111+
112+
## Summary
113+
For all Remove/Set/Update cmdlets (and any other cmdlet where an existing resource is being operated on), you will have three parameter sets (and potentially a multiple of three if you have initially have multiple parameter sets):
114+
```powershell
115+
Remove/Set/Update-AzureRm<ExampleResource> <parameters that are required to identify ExampleResource> <Other parameters>
116+
Remove/Set/Update-AzureRm<ExampleResource> -InputObject <TypeOfExampleResource> <Other parameters that cannot be obtained from TypeOfExampleResource>
117+
Remove/Set/Update-AzureRm<ExampleResource> -ResourceId <string (accepts ExampleResource ResourceId> <Other parameters that cannot be obtained from ExampleResource ResourceId>
118+
```
119+
For example, for child resource "Widget" with parent "Foo", there will be these three parameter sets for Remove:
120+
```powershell
121+
Remove-AzureRmWidget -ResourceGroupName <string> -FooName <string> -Name <string>
122+
Remove-AzureRmWidget -InputObject <Widget>
123+
Remove-AzureRmWidget -ResourceId <string>
124+
```
125+
For all child resources, Get/New cmdlets will also have these three parameter sets:
126+
```powershell
127+
Get/New-AzureRm<ExampleResource> <parameters needed to identify/create ExampleResource>
128+
Get-AzureRm<ExampleResource> -InputObject <TypeOfParentOfExampleResource> <Other parameters that cannot be obtained from TypeOfParentOfExampleResource>
129+
Get/New-AzureRm<ExampleResource> -ResourceId <string (accepts ResourceId of the parent of ExampleResource> <Other parameters that cannot be obtained from the ResourceId of the parent of ExampleResource>
130+
```
131+
For example, for child resource "Widget" with parent "Foo", there will be these three parameter sets for New:
132+
```powershell
133+
New-AzureRmWidget -ResourceGroupName <string> -FooName <String> -Name <string>
134+
New-AzureRmWidget -WidgetObject <Foo> -Name <string>
135+
New-AzureRmWidget -WidgetResourceId <string> -Name <string>
136+
```
137+
138+
# Piping in PowerShell (additional information)
2139

3140
## Understanding Piping
4141

@@ -107,88 +244,6 @@ public override void ExecuteCmdlet()
107244
}
108245
```
109246

110-
## Azure PowerShell Piping Scenarios
111-
112-
There are two main scenarios that we wish to enable in cmdlets for Azure PowerShell:
113-
- piping by value using an `InputObject` parameter
114-
- piping by property name using a `ResourceId` parameter
115-
116-
### Using the `InputObject` parameter
117-
118-
This scenario should be used when piping objects around within the same module. For example, if you have a set of `Get-AzureRmFoo`, `Remove-AzureRmFoo`, and `Set-AzureRmFoo` cmdlets, the `Remove-AzureRmFoo` and `Set-AzureRmFoo` cmdlets should have a parameter set that takes the `InputObject` parameter of type `PSFoo` so that a user can do the following:
119-
120-
```powershell
121-
# --- Piping scenario ---
122-
# Setting and removing an individual object
123-
Get-AzureRmFoo -Name "FooName" -ResourceGroupName "RG" | Set-AzureRmFoo <additional parameters>
124-
Get-AzureRmFoo -Name "FooName" -ResourceGroupName "RG" | Remove-AzureRmFoo
125-
126-
# Setting and removing a collection of objects
127-
Get-AzureRmFoo | Set-AzureRmFoo <additional parameters>
128-
Get-AzureRmFoo | Remove-AzureRmFoo
129-
130-
131-
# --- Non-piping scenario ---
132-
# Setting and removing an individual object
133-
$foo = Get-AzureRmFoo -Name "FooName" -ResourceGroupName "RG"
134-
Set-AzureRmFoo -InputObject $foo <additional parameters>
135-
Remove-AzureRmFoo -InputObject $foo
136-
137-
# Setting and removing a collection of objects
138-
Get-AzureRmFoo | ForEach-Object { Set-AzureRmFoo -InputObject $_ <additional parameters> }
139-
Get-AzureRmFoo | ForEach-Object { Remove-AzureRmFoo -InputObject $_ }
140-
```
141-
142-
Another time that this scenario applies is when you have cmdlets for child resources that need information about the parent (top-level) resource. For example you can pipe in the whole parent object to the `New-AzureRmFooBar` and `Get-AzureRmFooBar` cmdlets to get the child resources, and then pipe the child resource object to the `Remove-AzureRmFooBar` and `Set-AzureRmFooBar` cmdlets.
143-
144-
```powershell
145-
# --- Piping scenario ---
146-
# Getting all of child resources from all of the parent resources and removing them
147-
Get-AzureRmFoo | Get-AzureRmFooBar | Remove-AzureRmFooBar
148-
149-
# Getting all of the child resources from all of the parent resources in a resource group and removing them
150-
Get-AzureRmFoo -ResourceGroupName "RG" | Get-AzureRmFooBar | Remove-AzureRmFooBar
151-
152-
# Getting all of the child resources from a specific parent resource and removing them
153-
Get-AzureRmFoo -ResourceGroupName "RG" -Name "FooName" | Get-AzureRmFooBar | Remove-AzureRmFooBar
154-
155-
156-
# --- Non-piping scenario ---
157-
# Getting all of the child resources from a specific parent resource and removing them
158-
$foo = Get-AzureRmFoo -ResourceGroupName "RG" -Name "FooName"
159-
$fooBar = Get-AzureRmFooBar -InputObject $foo
160-
Remove-AzureRmFooBar -InputObject $fooBar
161-
```
162-
163-
### Using the `ResourceId` parameter
164-
165-
In this scenario, we are using the generic cmdlets found in the `AzureRM.Resources` module. These cmdlets, `Find-AzureRmResource` and `Get-AzureRmResource`, return a `PSCustomObject` that has a `ResourceId` property, which is the unique identifier for the given resource. Since this identifier can parsed to get the name and resource group name for a top-level resource, we can create a parameter set that has a `ResourceId` parameter that accepts its value from the pipeline by property name, allowing us to accept piping from these generic cmdlets.
166-
167-
```powershell
168-
# --- Piping scenario ---
169-
# Remove all Foo objects in the current subscription
170-
Find-AzureRmResource -ResourceType Microsoft.Foo/foo | Remove-AzureRmFoo
171-
172-
# Remove all Foo objects in a given resource group
173-
Find-AzureRmResource -ResourceType Microsoft.Foo/foo -ResourceGroupEquals "RG" | Remove-AzureRmFoo
174-
175-
# Remove a specific Foo object
176-
Find-AzureRmResource -ResourceGroupEquals "RG" -ResourceNameEquals "FooName" | Remove-AzureRmFoo
177-
178-
179-
# -- Non-piping scenario ---
180-
# Removing all Foo objects in the current subscription
181-
Find-AzureRmResource -ResourceType Microsoft.Foo/foo | ForEach-Object { Remove-AzureRmFoo -ResourceId $_.ResourceId }
182-
183-
# Remove all Foo objects in a given resource group
184-
Find-AzureRmResource -ResourceType Microsoft.Foo/foo -ResourceGroupEquals "RG" | ForEach-Object { Remove-AzureRmFoo -ResourceId $_.ResourceId }
185-
186-
# Remove a specific Foo object
187-
Find-AzureRmResource -ResourceGroupEquals "RG" -ResourceNameEquals "FooName" | ForEach-Object { Remove-AzureRmFoo -ResourceId $_.ResourceId }
188-
```
189-
190-
To implement this scenario, please see the [`ResourceIdentifier`](https://github.com/Azure/azure-powershell/blob/preview/src/ResourceManager/Common/Commands.ResourceManager.Common/Utilities/Models/ResourceIdentifier.cs) class in the `Commands.ResourceManager.Common` project. This class will allow you to create a `ResourceIdentifier` object that accepts a `ResourceId` string in its constructor and has properties `ResourceName`, `ResourceGroupName`, and others.
191-
192247
## More Information
193248

194-
For more information on piping, see the article ["Understanding the Windows PowerShell Pipeline"](https://msdn.microsoft.com/en-us/powershell/scripting/getting-started/fundamental/understanding-the-windows-powershell-pipeline).
249+
For more information on piping, see the article ["Understanding the Windows PowerShell Pipeline"](https://msdn.microsoft.com/en-us/powershell/scripting/getting-started/fundamental/understanding-the-windows-powershell-pipeline).

0 commit comments

Comments
 (0)