Custom providers (#12277)

* Initial commit for custom providers

* Adding tests

* Update help

* Update New-AzCustomProvider.md

* remove tools/

* docs

* Update New-AzCustomProvider.md

Co-authored-by: Yeming Liu <[email protected]>

Author: markcowl

src/CustomProviders/.gitattributes

@@ -0,0 +1 @@
+* text=auto

src/CustomProviders/.gitignore

@@ -0,0 +1,15 @@
+bin
+obj
+.vs
+generated
+internal
+exports
+custom/*.psm1
+test/*-TestResults.xml
+/*.ps1
+/*.ps1xml
+/*.psm1
+/*.snk
+/*.csproj
+/*.nuspec
+tools/

src/CustomProviders/Az.CustomProviders.psd1

@@ -0,0 +1,24 @@
+@{
+  GUID = 'b98dded0-6e9a-4371-b2c6-d74464fb724b'
+  RootModule = './Az.CustomProviders.psm1'
+  ModuleVersion = '0.1.0'
+  CompatiblePSEditions = 'Core', 'Desktop'
+  Author = 'Microsoft Corporation'
+  CompanyName = 'Microsoft Corporation'
+  Copyright = 'Microsoft Corporation. All rights reserved.'
+  Description = 'Microsoft Azure PowerShell: Custom Providers cmdlets'
+  PowerShellVersion = '5.1'
+  DotNetFrameworkVersion = '4.7.2'
+  RequiredAssemblies = './bin/Az.CustomProviders.private.dll'
+  FormatsToProcess = './Az.CustomProviders.format.ps1xml'
+  FunctionsToExport = 'Get-AzCustomProvider', 'Get-AzCustomProviderAssociation', 'New-AzCustomProvider', 'New-AzCustomProviderAssociation', 'Remove-AzCustomProvider', 'Remove-AzCustomProviderAssociation', 'Update-AzCustomProvider', '*'
+  AliasesToExport = '*'
+  PrivateData = @{
+    PSData = @{
+      Tags = 'Azure', 'ResourceManager', 'ARM', 'PSModule', 'CustomProviders'
+      LicenseUri = 'https://aka.ms/azps-license'
+      ProjectUri = 'https://github.com/Azure/azure-powershell'
+      ReleaseNotes = ''
+    }
+  }
+}

src/CustomProviders/custom/readme.md

@@ -0,0 +1,41 @@
+# Custom
+This directory contains custom implementation for non-generated cmdlets for the `Az.CustomProviders` 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.CustomProviders.custom.psm1`. This file should not be modified.
+
+## Info
+- Modifiable: yes
+- Generated: partial
+- Committed: yes
+- Packaged: yes
+
+## Details
+For `Az.CustomProviders` to use custom cmdlets, it does this two different ways. We **highly recommend** creating script cmdlets, as they are easier to write and allow access to the other exported cmdlets. C# cmdlets *cannot access exported cmdlets*.
+
+For C# cmdlets, they are compiled with the rest of the generated low-level cmdlets into the `./bin/Az.CustomProviders.private.dll`. The names of the cmdlets (methods) and files must follow the `[cmdletName]_[variantName]` syntax used for generated cmdlets. The `variantName` is used as the `ParameterSetName`, so use something appropriate that doesn't clash with already created variant or parameter set names. You cannot use the `ParameterSetName` property in the `Parameter` attribute on C# cmdlets. Each cmdlet must be separated into variants using the same pattern as seen in the `generated/cmdlets` folder.
+
+For script cmdlets, these are loaded via the `Az.CustomProviders.custom.psm1`. Then, during the build process, this module is loaded and processed in the same manner as the C# cmdlets. The fundemental 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.
+
+## 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:
+- Break
+- DefaultProfile
+- HttpPipelineAppend
+- HttpPipelinePrepend
+- Proxy
+- ProxyCredential
+- ProxyUseDefaultCredentials
+
+These provide functionality to our HTTP pipeline and other useful features. In script, you can forward these parameters using `$PSBoundParameters` to the other cmdlets you're calling within `Az.CustomProviders`. For C#, follow the usage seen in the `ProcessRecordAsync` method.
+
+### Attributes
+For processing the cmdlets, we've created some additional attributes:
+- `Microsoft.Azure.PowerShell.Cmdlets.CustomProviders.Models.DescriptionAttribute`
+  - Used in C# cmdlets to provide a high-level description of the cmdlet. This is propegated to reference documentation via [help comments](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_comment_based_help) in the exported scripts.
+- `Microsoft.Azure.PowerShell.Cmdlets.CustomProviders.Models.DoNotExportAttribute`
+  - Used in C# and script cmdlets to suppress creating an exported cmdlet at build-time. These cmdlets will *not be exposed* by `Az.CustomProviders`.
+- `Microsoft.Azure.PowerShell.Cmdlets.CustomProviders.Models.InternalExportAttribute`
+  - Used in C# cmdlets to route exported cmdlets to the `..\internal`, which are *not exposed* by `Az.CustomProviders`. For more information, see [readme.md](..\internal/readme.md) in the `..\internal` folder.
+- `Microsoft.Azure.PowerShell.Cmdlets.CustomProviders.Models.ProfileAttribute`
+  - Used in C# and script cmdlets to define which Azure profiles the cmdlet supports. This is only supported for Azure (`--azure`) modules.

src/CustomProviders/docs/Az.CustomProviders.md

@@ -0,0 +1,35 @@
+---
+Module Name: Az.CustomProviders
+Module Guid: b98dded0-6e9a-4371-b2c6-d74464fb724b
+Download Help Link: https://docs.microsoft.com/en-us/powershell/module/az.customproviders
+Help Version: 1.0.0.0
+Locale: en-US
+---
+
+# Az.CustomProviders Module
+## Description
+Microsoft Azure PowerShell: Custom Providers cmdlets
+
+## Az.CustomProviders Cmdlets
+### [Get-AzCustomProvider](Get-AzCustomProvider.md)
+Gets the custom resource provider manifest.
+
+### [Get-AzCustomProviderAssociation](Get-AzCustomProviderAssociation.md)
+Get an association.
+
+### [New-AzCustomProvider](New-AzCustomProvider.md)
+Creates or updates the custom resource provider.
+
+### [New-AzCustomProviderAssociation](New-AzCustomProviderAssociation.md)
+Create or update an association.
+
+### [Remove-AzCustomProvider](Remove-AzCustomProvider.md)
+Deletes the custom resource provider.
+
+### [Remove-AzCustomProviderAssociation](Remove-AzCustomProviderAssociation.md)
+Delete an association.
+
+### [Update-AzCustomProvider](Update-AzCustomProvider.md)
+Updates an existing custom resource provider.
+The only value that can be updated via PATCH currently is the tags.
+

src/CustomProviders/docs/Get-AzCustomProvider.md

@@ -0,0 +1,182 @@
+---
+external help file:
+Module Name: Az.CustomProviders
+online version: https://docs.microsoft.com/en-us/powershell/module/az.customproviders/get-azcustomprovider
+schema: 2.0.0
+---
+
+# Get-AzCustomProvider
+
+## SYNOPSIS
+Gets the custom resource provider manifest.
+
+## SYNTAX
+
+### List1 (Default)
+```
+Get-AzCustomProvider [-SubscriptionId <String[]>] [-DefaultProfile <PSObject>] [<CommonParameters>]
+```
+
+### Get
+```
+Get-AzCustomProvider -Name <String> -ResourceGroupName <String> [-SubscriptionId <String[]>]
+ [-DefaultProfile <PSObject>] [<CommonParameters>]
+```
+
+### GetViaIdentity
+```
+Get-AzCustomProvider -InputObject <ICustomProvidersIdentity> [-DefaultProfile <PSObject>] [<CommonParameters>]
+```
+
+### List
+```
+Get-AzCustomProvider -ResourceGroupName <String> [-SubscriptionId <String[]>] [-DefaultProfile <PSObject>]
+ [<CommonParameters>]
+```
+
+## DESCRIPTION
+Gets the custom resource provider manifest.
+
+## EXAMPLES
+
+### Example 1: List all Custom Providers in a subscription
+```powershell
+PS C:\> Get-AzCustomProvider
+
+Location  Name             Type
+--------  ----             ----
+West US 2 Namespace.Type   Microsoft.CustomProviders/resourceproviders
+East US 2 Namespace2.Type  Microsoft.CustomProviders/resourceproviders
+```
+
+Lists all the custom providers in a subscription
+
+### Example 2: Get a single custom provider
+```powershell
+PS C:\> Get-AzCustomProvider -ResourceGroupName myRg -Name Namespace.Type | Format-List
+
+Action            :
+Id                : /subscriptions/xxxxx-yyyyy-xxxx-yyyy/resourceGroups/mc-cp01/providers/Microsoft.CustomProviders/resourceproviders/Namespace.Type
+Location          : West US 2
+Name              : Namespace.Type
+ProvisioningState : Succeeded
+ResourceType      : {CustomRoute1, associations}
+Tag               : Microsoft.Azure.PowerShell.Cmdlets.CustomProviders.Models.Api20180901Preview.ResourceTags
+Type              : Microsoft.CustomProviders/resourceproviders
+Validation        :
+
+```
+
+Gets details for a single custom provider.
+Use Format-List to show object details on the screen.
+
+## PARAMETERS
+
+### -DefaultProfile
+The credentials, account, tenant, and subscription used for communication with Azure.
+
+```yaml
+Type: System.Management.Automation.PSObject
+Parameter Sets: (All)
+Aliases: AzureRMContext, AzureCredential
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -InputObject
+Identity Parameter
+To construct, see NOTES section for INPUTOBJECT properties and create a hash table.
+
+```yaml
+Type: Microsoft.Azure.PowerShell.Cmdlets.CustomProviders.Models.ICustomProvidersIdentity
+Parameter Sets: GetViaIdentity
+Aliases:
+
+Required: True
+Position: Named
+Default value: None
+Accept pipeline input: True (ByValue)
+Accept wildcard characters: False
+```
+
+### -Name
+The name of the resource provider.
+
+```yaml
+Type: System.String
+Parameter Sets: Get
+Aliases: ResourceProviderName
+
+Required: True
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -ResourceGroupName
+The name of the resource group.
+
+```yaml
+Type: System.String
+Parameter Sets: Get, List
+Aliases:
+
+Required: True
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -SubscriptionId
+The Azure subscription ID.
+This is a GUID-formatted string (e.g.
+00000000-0000-0000-0000-000000000000)
+
+```yaml
+Type: System.String[]
+Parameter Sets: Get, List, List1
+Aliases:
+
+Required: False
+Position: Named
+Default value: (Get-AzContext).Subscription.Id
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### CommonParameters
+This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216).
+
+## INPUTS
+
+### Microsoft.Azure.PowerShell.Cmdlets.CustomProviders.Models.ICustomProvidersIdentity
+
+## OUTPUTS
+
+### Microsoft.Azure.PowerShell.Cmdlets.CustomProviders.Models.Api20180901Preview.ICustomRpManifest
+
+## NOTES
+
+ALIASES
+
+COMPLEX PARAMETER PROPERTIES
+
+To create the parameters described below, construct a hash table containing the appropriate properties. For information on hash tables, run Get-Help about_Hash_Tables.
+
+
+INPUTOBJECT <ICustomProvidersIdentity>: Identity Parameter
+  - `[AssociationName <String>]`: The name of the association.
+  - `[Id <String>]`: Resource identity path
+  - `[ResourceGroupName <String>]`: The name of the resource group.
+  - `[ResourceProviderName <String>]`: The name of the resource provider.
+  - `[Scope <String>]`: The scope of the association.
+  - `[SubscriptionId <String>]`: The Azure subscription ID. This is a GUID-formatted string (e.g. 00000000-0000-0000-0000-000000000000)
+
+## RELATED LINKS
+