Skip to content

Commit

Permalink
[SelfHelp] Add new API version 2024-03-01-preview support for AzSelfH…
Browse files Browse the repository at this point in the history
…elp cmdlets for Help Resource Provider (Azure#24547)

* initial commit for SelfHelp new version

* Adding files generated by build-module powershell file

* Updating Test files

* Added unit tests

* Adding examples

* Updating DiscoverySolutions examples

* Updating examples

* Added LiveOnly tag to tests
  • Loading branch information
siddiavinashmsft authored and qinzhouxu committed Jun 5, 2024
1 parent eaf2ecf commit 7937b38
Show file tree
Hide file tree
Showing 80 changed files with 3,509 additions and 950 deletions.
2 changes: 1 addition & 1 deletion src/SelfHelp/SelfHelp.Autorest/Az.SelfHelp.psd1
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@
DotNetFrameworkVersion = '4.7.2'
RequiredAssemblies = './bin/Az.SelfHelp.private.dll'
FormatsToProcess = './Az.SelfHelp.format.ps1xml'
FunctionsToExport = 'Get-AzSelfHelpDiagnostic', 'Get-AzSelfHelpDiscoverySolution', 'Get-AzSelfHelpSolution', 'Get-AzSelfHelpTroubleshooter', 'Invoke-AzSelfHelpCheckNameAvailability', 'Invoke-AzSelfHelpContinueTroubleshooter', 'New-AzSelfHelpDiagnostic', 'New-AzSelfHelpSolution', 'New-AzSelfHelpTroubleshooter', 'Restart-AzSelfHelpTroubleshooter', 'Stop-AzSelfHelpTroubleshooter', 'Update-AzSelfHelpSolution', '*'
FunctionsToExport = 'Get-AzSelfHelpDiagnostic', 'Get-AzSelfHelpDiscoverySolution', 'Get-AzSelfHelpSimplifiedSolution', 'Get-AzSelfHelpSolution', 'Get-AzSelfHelpSolutionSelfHelp', 'Get-AzSelfHelpTroubleshooter', 'Invoke-AzSelfHelpCheckNameAvailability', 'Invoke-AzSelfHelpContinueTroubleshooter', 'Invoke-AzSelfHelpDiscoverySolutionNlpSubscriptionScope', 'Invoke-AzSelfHelpDiscoverySolutionNlpTenantScope', 'Invoke-AzSelfHelpWarmSolutionUp', 'New-AzSelfHelpDiagnostic', 'New-AzSelfHelpSimplifiedSolution', 'New-AzSelfHelpSolution', 'New-AzSelfHelpTroubleshooter', 'Restart-AzSelfHelpTroubleshooter', 'Stop-AzSelfHelpTroubleshooter', 'Update-AzSelfHelpSolution', '*'
AliasesToExport = '*'
PrivateData = @{
PSData = @{
Expand Down
5 changes: 1 addition & 4 deletions src/SelfHelp/SelfHelp.Autorest/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,9 +3,6 @@
This directory contains the PowerShell module for the SelfHelp service.

---
## Status
[![Az.SelfHelp](https://img.shields.io/powershellgallery/v/Az.SelfHelp.svg?style=flat-square&label=Az.SelfHelp "Az.SelfHelp")](https://www.powershellgallery.com/packages/Az.SelfHelp/)

## Info
- Modifiable: yes
- Generated: all
Expand All @@ -32,7 +29,7 @@ For information on how to develop for `Az.SelfHelp`, see [how-to.md](how-to.md).
```yaml
# pin the swagger version by using the commit id instead of branch name
commit: 270eeb7a7883e0ad4e183e809fb67c6551d0eaa0
commit: 1145a0df0f91b5f0f1f5ab66667899a61eda5e2b
require:
# readme.azure.noprofile.md is the common configuration file
- $(this-folder)/../../readme.azure.noprofile.md
Expand Down
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"resourceType": "diagnostics",
"apiVersion": "2023-06-01",
"apiVersion": "2024-03-01-preview",
"learnMore": {
"url": "https://learn.microsoft.com/powershell/module/az.selfhelp"
},
Expand Down
37 changes: 37 additions & 0 deletions src/SelfHelp/SelfHelp.Autorest/UX/Microsoft.Help/selfHelp.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
{
"resourceType": "selfHelp",
"apiVersion": "2024-03-01-preview",
"learnMore": {
"url": "https://learn.microsoft.com/powershell/module/az.selfhelp"
},
"commands": [
{
"name": "Get-AzSelfHelpSolutionSelfHelp",
"description": "Finds and Executes a Self Help Solution based on the Solution Id.\nThese are static self help content to help users troubleshoot their issues.",
"path": "/providers/Microsoft.Help/selfHelp/{solutionId}",
"help": {
"learnMore": {
"url": "https://learn.microsoft.com/powershell/module/az.selfhelp/get-azselfhelpsolutionselfhelp"
},
"parameterSets": [
{
"parameters": [
"-SolutionId <String>"
]
}
]
},
"examples": [
{
"description": "Finds and Executes a Self Help Solution based on the Solution Id. These are static self help content to help users troubleshoot their issues.",
"parameters": [
{
"name": "-SolutionId",
"value": "[Path.solutionId]"
}
]
}
]
}
]
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
{
"resourceType": "simplifiedSolutions",
"apiVersion": "2024-03-01-preview",
"learnMore": {
"url": "https://learn.microsoft.com/powershell/module/az.selfhelp"
},
"commands": [
{
"name": "Get-AzSelfHelpSimplifiedSolution",
"description": "Get the simplified Solutions using the applicable solutionResourceName while creating the simplified Solutions.",
"path": "/{scope}/providers/Microsoft.Help/simplifiedSolutions/{simplifiedSolutionsResourceName}",
"help": {
"learnMore": {
"url": "https://learn.microsoft.com/powershell/module/az.selfhelp/get-azselfhelpsimplifiedsolution"
},
"parameterSets": [
{
"parameters": [
"-SResourceName <String>",
"-Scope <String>"
]
}
]
},
"examples": [
{
"description": "Get the simplified Solutions using the applicable solutionResourceName while creating the simplified Solutions.",
"parameters": [
{
"name": "-SResourceName",
"value": "[Path.simplifiedSolutionsResourceName]"
},
{
"name": "-Scope",
"value": "[Path.scope]"
}
]
}
]
}
]
}
75 changes: 75 additions & 0 deletions src/SelfHelp/SelfHelp.Autorest/UX/Microsoft.Help/solutions.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
{
"resourceType": "solutions",
"apiVersion": "2024-03-01-preview",
"learnMore": {
"url": "https://learn.microsoft.com/powershell/module/az.selfhelp"
},
"commands": [
{
"name": "Get-AzSelfHelpSolution",
"description": "Get the solution using the applicable solutionResourceName while creating the solution.",
"path": "/{scope}/providers/Microsoft.Help/solutions/{solutionResourceName}",
"help": {
"learnMore": {
"url": "https://learn.microsoft.com/powershell/module/az.selfhelp/get-azselfhelpsolution"
},
"parameterSets": [
{
"parameters": [
"-ResourceName <String>",
"-Scope <String>"
]
}
]
},
"examples": [
{
"description": "Get the solution using the applicable solutionResourceName while creating the solution.",
"parameters": [
{
"name": "-ResourceName",
"value": "[Path.solutionResourceName]"
},
{
"name": "-Scope",
"value": "[Path.scope]"
}
]
}
]
},
{
"name": "Invoke-AzSelfHelpWarmSolutionUp",
"description": "Warm up the solution resource by preloading asynchronous diagnostics results into cache",
"path": "/{scope}/providers/Microsoft.Help/solutions/{solutionResourceName}/warmup",
"help": {
"learnMore": {
"url": "https://learn.microsoft.com/powershell/module/az.selfhelp/invoke-azselfhelpwarmsolutionup"
},
"parameterSets": [
{
"parameters": [
"-Scope <String>",
"-SolutionResourceName <String>"
]
}
]
},
"examples": [
{
"description": "Warm up the solution resource by preloading asynchronous diagnostics results into cache",
"parameters": [
{
"name": "-Scope",
"value": "[Path.scope]"
},
{
"name": "-SolutionResourceName",
"value": "[Path.solutionResourceName]"
}
]
}
]
}
]
}
141 changes: 141 additions & 0 deletions src/SelfHelp/SelfHelp.Autorest/UX/Microsoft.Help/troubleshooters.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,141 @@
{
"resourceType": "troubleshooters",
"apiVersion": "2024-03-01-preview",
"learnMore": {
"url": "https://learn.microsoft.com/powershell/module/az.selfhelp"
},
"commands": [
{
"name": "Get-AzSelfHelpTroubleshooter",
"description": "Gets troubleshooter instance result which includes the step status/result of the troubleshooter resource name that is being executed.<br/> Get API is used to retrieve the result of a Troubleshooter instance, which includes the status and result of each step in the Troubleshooter workflow.\nThis API requires the Troubleshooter resource name that was created using the Create API.",
"path": "/{scope}/providers/Microsoft.Help/troubleshooters/{troubleshooterName}",
"help": {
"learnMore": {
"url": "https://learn.microsoft.com/powershell/module/az.selfhelp/get-azselfhelptroubleshooter"
},
"parameterSets": [
{
"parameters": [
"-Name <String>",
"-Scope <String>"
]
}
]
},
"examples": [
{
"description": "Gets troubleshooter instance result which includes the step status/result of the troubleshooter resource name that is being executed.<br/> Get API is used to retrieve the result of a Troubleshooter instance, which includes the status and result of each step in the Troubleshooter workflow. This API requires the Troubleshooter resource name that was created using the Create API.",
"parameters": [
{
"name": "-Name",
"value": "[Path.troubleshooterName]"
},
{
"name": "-Scope",
"value": "[Path.scope]"
}
]
}
]
},
{
"name": "Invoke-AzSelfHelpContinueTroubleshooter",
"description": "Uses ‘stepId’ and ‘responses’ as the trigger to continue the troubleshooting steps for the respective troubleshooter resource name.\n<br/>Continue API is used to provide inputs that are required for the specific troubleshooter to progress into the next step in the process.\nThis API is used after the Troubleshooter has been created using the Create API.",
"path": "/{scope}/providers/Microsoft.Help/troubleshooters/{troubleshooterName}/continue",
"help": {
"learnMore": {
"url": "https://learn.microsoft.com/powershell/module/az.selfhelp/invoke-azselfhelpcontinuetroubleshooter"
},
"parameterSets": [
{
"parameters": [
"-Scope <String>",
"-TroubleshooterName <String>"
]
}
]
},
"examples": [
{
"description": "Uses ‘stepId’ and ‘responses’ as the trigger to continue the troubleshooting steps for the respective troubleshooter resource name. <br/>Continue API is used to provide inputs that are required for the specific troubleshooter to progress into the next step in the process. This API is used after the Troubleshooter has been created using the Create API.",
"parameters": [
{
"name": "-Scope",
"value": "[Path.scope]"
},
{
"name": "-TroubleshooterName",
"value": "[Path.troubleshooterName]"
}
]
}
]
},
{
"name": "Restart-AzSelfHelpTroubleshooter",
"description": "Restarts the troubleshooter API using applicable troubleshooter resource name as the input.<br/> It returns new resource name which should be used in subsequent request.\nThe old resource name is obsolete after this API is invoked.",
"path": "/{scope}/providers/Microsoft.Help/troubleshooters/{troubleshooterName}/restart",
"help": {
"learnMore": {
"url": "https://learn.microsoft.com/powershell/module/az.selfhelp/restart-azselfhelptroubleshooter"
},
"parameterSets": [
{
"parameters": [
"-Name <String>",
"-Scope <String>"
]
}
]
},
"examples": [
{
"description": "Restarts the troubleshooter API using applicable troubleshooter resource name as the input.<br/> It returns new resource name which should be used in subsequent request. The old resource name is obsolete after this API is invoked.",
"parameters": [
{
"name": "-Name",
"value": "[Path.troubleshooterName]"
},
{
"name": "-Scope",
"value": "[Path.scope]"
}
]
}
]
},
{
"name": "Stop-AzSelfHelpTroubleshooter",
"description": "Ends the troubleshooter action",
"path": "/{scope}/providers/Microsoft.Help/troubleshooters/{troubleshooterName}/end",
"help": {
"learnMore": {
"url": "https://learn.microsoft.com/powershell/module/az.selfhelp/stop-azselfhelptroubleshooter"
},
"parameterSets": [
{
"parameters": [
"-Name <String>",
"-Scope <String>"
]
}
]
},
"examples": [
{
"description": "Ends the troubleshooter action",
"parameters": [
{
"name": "-Name",
"value": "[Path.troubleshooterName]"
},
{
"name": "-Scope",
"value": "[Path.scope]"
}
]
}
]
}
]
}
8 changes: 4 additions & 4 deletions src/SelfHelp/SelfHelp.Autorest/custom/README.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
# Custom
This directory contains custom implementation for non-generated cmdlets for the `Az.SelfHelp` module. Both scripts (`.ps1`) and C# files (`.cs`) can be implemented here. They will be used during the build process in `build-module.ps1`, and create cmdlets into the `..\exports` folder. The only generated file into this folder is the `Az.SelfHelp.custom.psm1`. This file should not be modified.
This directory contains custom implementation for non-generated cmdlets for the `Az.SelfHelp` module. Both scripts (`.ps1`) and C# files (`.cs`) can be implemented here. They will be used during the build process in `build-module.ps1`, and create cmdlets into the `../exports` folder. The only generated file into this folder is the `Az.SelfHelp.custom.psm1`. This file should not be modified.

## Info
- Modifiable: yes
Expand All @@ -15,10 +15,10 @@ For C# cmdlets, they are compiled with the rest of the generated low-level cmdle
For script cmdlets, these are loaded via the `Az.SelfHelp.custom.psm1`. Then, during the build process, this module is loaded and processed in the same manner as the C# cmdlets. The fundamental difference is the script cmdlets use the `ParameterSetName` attribute and C# cmdlets do not. To create a script cmdlet variant of a generated cmdlet, simply decorate all parameters in the script with the new `ParameterSetName` in the `Parameter` attribute. This will appropriately treat each parameter set as a separate variant when processed to be exported during the build.

## Purpose
This allows the modules to have cmdlets that were not defined in the REST specification. It also allows combining logic using generated cmdlets. This is a level of customization beyond what can be done using the [readme configuration options](https://github.com/Azure/autorest/blob/master/docs/powershell/options.md) that are currently available. These custom cmdlets are then referenced by the cmdlets created at build-time in the `..\exports` folder.
This allows the modules to have cmdlets that were not defined in the REST specification. It also allows combining logic using generated cmdlets. This is a level of customization beyond what can be done using the [readme configuration options](https://github.com/Azure/autorest/blob/master/docs/powershell/options.md) that are currently available. These custom cmdlets are then referenced by the cmdlets created at build-time in the `../exports` folder.

## Usage
The easiest way currently to start developing custom cmdlets is to copy an existing cmdlet. For C# cmdlets, copy one from the `generated/cmdlets` folder. For script cmdlets, build the project using `build-module.ps1` and copy one of the scripts from the `..\exports` folder. After that, if you want to add new parameter sets, follow the guidelines in the `Details` section above. For implementing a new cmdlets, at minimum, please keep these parameters:
The easiest way currently to start developing custom cmdlets is to copy an existing cmdlet. For C# cmdlets, copy one from the `generated/cmdlets` folder. For script cmdlets, build the project using `build-module.ps1` and copy one of the scripts from the `../exports` folder. After that, if you want to add new parameter sets, follow the guidelines in the `Details` section above. For implementing a new cmdlets, at minimum, please keep these parameters:
- Break
- DefaultProfile
- HttpPipelineAppend
Expand All @@ -36,6 +36,6 @@ For processing the cmdlets, we've created some additional attributes:
- `Microsoft.Azure.PowerShell.Cmdlets.SelfHelp.DoNotExportAttribute`
- Used in C# and script cmdlets to suppress creating an exported cmdlet at build-time. These cmdlets will *not be exposed* by `Az.SelfHelp`.
- `Microsoft.Azure.PowerShell.Cmdlets.SelfHelp.InternalExportAttribute`
- Used in C# cmdlets to route exported cmdlets to the `..\internal`, which are *not exposed* by `Az.SelfHelp`. For more information, see [README.md](..\internal/README.md) in the `..\internal` folder.
- Used in C# cmdlets to route exported cmdlets to the `../internal`, which are *not exposed* by `Az.SelfHelp`. For more information, see [README.md](../internal/README.md) in the `../internal` folder.
- `Microsoft.Azure.PowerShell.Cmdlets.SelfHelp.ProfileAttribute`
- Used in C# and script cmdlets to define which Azure profiles the cmdlet supports. This is only supported for Azure (`--azure`) modules.
Loading

0 comments on commit 7937b38

Please sign in to comment.