Skip to content
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions src/WindowsIotServices/.gitattributes
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
* text=auto
15 changes: 15 additions & 0 deletions src/WindowsIotServices/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
bin
obj
.vs
generated
internal
exports
tools
custom/*.psm1
test/*-TestResults.xml
/*.ps1
/*.ps1xml
/*.psm1
/*.snk
/*.csproj
/*.nuspec
24 changes: 24 additions & 0 deletions src/WindowsIotServices/Az.WindowsIotServices.psd1
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
@{
GUID = 'd5c7f2ce-fe23-49d5-a869-fb780e78a663'
RootModule = './Az.WindowsIotServices.psm1'
ModuleVersion = '0.1.0'
CompatiblePSEditions = 'Core', 'Desktop'
Author = 'Microsoft Corporation'
CompanyName = 'Microsoft Corporation'
Copyright = 'Microsoft Corporation. All rights reserved.'
Description = 'Microsoft Azure PowerShell: WindowsIotServices cmdlets'
PowerShellVersion = '5.1'
DotNetFrameworkVersion = '4.7.2'
RequiredAssemblies = './bin/Az.WindowsIotServices.private.dll'
FormatsToProcess = './Az.WindowsIotServices.format.ps1xml'
FunctionsToExport = 'Get-AzWindowsIotServicesDevice', 'New-AzWindowsIotServicesDevice', 'Remove-AzWindowsIotServicesDevice', 'Update-AzWindowsIotServicesDevice', '*'
AliasesToExport = '*'
PrivateData = @{
PSData = @{
Tags = 'Azure', 'ResourceManager', 'ARM', 'PSModule', 'WindowsIotServices'
LicenseUri = 'https://aka.ms/azps-license'
ProjectUri = 'https://github.com/Azure/azure-powershell'
ReleaseNotes = ''
}
}
}
41 changes: 41 additions & 0 deletions src/WindowsIotServices/custom/readme.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
# Custom
This directory contains custom implementation for non-generated cmdlets for the `Az.WindowsIotServices` 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.WindowsIotServices.custom.psm1`. This file should not be modified.

## Info
- Modifiable: yes
- Generated: partial
- Committed: yes
- Packaged: yes

## Details
For `Az.WindowsIotServices` 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.WindowsIotServices.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.WindowsIotServices.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.WindowsIotServices`. 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.WindowsIotServices.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.WindowsIotServices.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.WindowsIotServices`.
- `Microsoft.Azure.PowerShell.Cmdlets.WindowsIotServices.Models.InternalExportAttribute`
- Used in C# cmdlets to route exported cmdlets to the `..\internal`, which are *not exposed* by `Az.WindowsIotServices`. For more information, see [readme.md](..\internal/readme.md) in the `..\internal` folder.
- `Microsoft.Azure.PowerShell.Cmdlets.WindowsIotServices.Models.ProfileAttribute`
- Used in C# and script cmdlets to define which Azure profiles the cmdlet supports. This is only supported for Azure (`--azure`) modules.
27 changes: 27 additions & 0 deletions src/WindowsIotServices/docs/Az.WindowsIotServices.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
---
Module Name: Az.WindowsIotServices
Module Guid: d5c7f2ce-fe23-49d5-a869-fb780e78a663
Download Help Link: https://docs.microsoft.com/en-us/powershell/module/az.windowsiotservices
Help Version: 1.0.0.0
Locale: en-US
---

# Az.WindowsIotServices Module
## Description
Microsoft Azure PowerShell: WindowsIotServices cmdlets

## Az.WindowsIotServices Cmdlets
### [Get-AzWindowsIotServicesDevice](Get-AzWindowsIotServicesDevice.md)
Get the non-security related metadata of a Windows IoT Device Service.

### [New-AzWindowsIotServicesDevice](New-AzWindowsIotServicesDevice.md)
Create or update the metadata of a Windows IoT Device Service.
The usual pattern to modify a property is to retrieve the Windows IoT Device Service metadata and security metadata, and then combine them with the modified values in a new body to update the Windows IoT Device Service.

### [Remove-AzWindowsIotServicesDevice](Remove-AzWindowsIotServicesDevice.md)
Delete a Windows IoT Device Service.

### [Update-AzWindowsIotServicesDevice](Update-AzWindowsIotServicesDevice.md)
Updates the metadata of a Windows IoT Device Service.
The usual pattern to modify a property is to retrieve the Windows IoT Device Service metadata and security metadata, and then combine them with the modified values in a new body to update the Windows IoT Device Service.

206 changes: 206 additions & 0 deletions src/WindowsIotServices/docs/Get-AzWindowsIotServicesDevice.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,206 @@
---
external help file:
Module Name: Az.WindowsIotServices
online version: https://docs.microsoft.com/en-us/powershell/module/az.windowsiotservices/get-azwindowsiotservicesdevice
schema: 2.0.0
---

# Get-AzWindowsIotServicesDevice

## SYNOPSIS
Get the non-security related metadata of a Windows IoT Device Service.

## SYNTAX

### List1 (Default)
```
Get-AzWindowsIotServicesDevice [-SubscriptionId <String[]>] [-DefaultProfile <PSObject>] [<CommonParameters>]
```

### Get
```
Get-AzWindowsIotServicesDevice -Name <String> -ResourceGroupName <String> [-SubscriptionId <String[]>]
[-DefaultProfile <PSObject>] [<CommonParameters>]
```

### GetViaIdentity
```
Get-AzWindowsIotServicesDevice -InputObject <IWindowsIotServicesIdentity> [-DefaultProfile <PSObject>]
[<CommonParameters>]
```

### List
```
Get-AzWindowsIotServicesDevice -ResourceGroupName <String> [-SubscriptionId <String[]>]
[-DefaultProfile <PSObject>] [<CommonParameters>]
```

## DESCRIPTION
Get the non-security related metadata of a Windows IoT Device Service.

## EXAMPLES

### Example 1: Get all Windows IoT services under a subscription
```powershell
PS C:\> Get-AzWindowsIotServicesDevice

Location Name Type Etag
-------- ---- ---- ----
West US wsi-t01 Microsoft.WindowsIoT/DeviceServices "5c006e63-0000-0700-0000-5faa37830000"
eastus wsi-t02 Microsoft.WindowsIoT/DeviceServices "5c006ad2-0000-0700-0000-5faa3e090000"
```

This command gets all Windows IoT services under a subscription.

### Example 2: Get all Windows IoT services under a resource group
```powershell
PS C:\> Get-AzWindowsIotServicesDevice -ResourceGroupName azure-rg-test

Location Name Type Etag
-------- ---- ---- ----
West US wsi-t01 Microsoft.WindowsIoT/DeviceServices "5c006e63-0000-0700-0000-5faa37830000"
eastus wsi-t02 Microsoft.WindowsIoT/DeviceServices "5c006ad2-0000-0700-0000-5faa3e090000"
```

This command gets all Windows IoT services under a resource group.

### Example 3: Get a Windows IoT service by name
```powershell
PS C:\> Get-AzWindowsIotServicesDevice -ResourceGroupName azure-rg-test -Name wsi-t01

Location Name Type Etag
-------- ---- ---- ----
West US wsi-t01 Microsoft.WindowsIoT/DeviceServices "5c006e63-0000-0700-0000-5faa37830000"
```

This command gets a Windows IoT service by name.

### Example 4: Get a Windows IoT service by object
```powershell
PS C:\> $wsi = New-AzWindowsIotServicesDevice -Name wsi-t01 -ResourceGroupName azure-rg-test -Location eastus -Quantity 10 -BillingDomainName 'microsoft.onmicrosoft.com' -AdminDomainName 'microsoft.onmicrosoft.com'
PS C:\> Get-AzWindowsIotServicesDevice -InputObject $wsi

Location Name Type Etag
-------- ---- ---- ----
West US wsi-t01 Microsoft.WindowsIoT/DeviceServices "5c006e63-0000-0700-0000-5faa37830000"
```

This command gets a Windows IoT service by object.

### Example 4: Get a Windows IoT service by pipeline
```powershell
PS C:\> $wsi = New-AzWindowsIotServicesDevice -Name wsi-t01 -ResourceGroupName azure-rg-test -Location eastus -Quantity 10 -BillingDomainName 'microsoft.onmicrosoft.com' -AdminDomainName 'microsoft.onmicrosoft.com' | Get-AzWindowsIotServicesDevice

Location Name Type Etag
-------- ---- ---- ----
West US wsi-t01 Microsoft.WindowsIoT/DeviceServices "5c006e63-0000-0700-0000-5faa37830000"
```

This command gets a Windows IoT service by pipeline.

## 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.WindowsIotServices.Models.IWindowsIotServicesIdentity
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 Windows IoT Device Service.

```yaml
Type: System.String
Parameter Sets: Get
Aliases:

Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
```

### -ResourceGroupName
The name of the resource group that contains the Windows IoT Device Service.

```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 subscription identifier.

```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.WindowsIotServices.Models.IWindowsIotServicesIdentity

## OUTPUTS

### Microsoft.Azure.PowerShell.Cmdlets.WindowsIotServices.Models.Api20190601.IDeviceService

## 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 <IWindowsIotServicesIdentity>: Identity Parameter
- `[DeviceName <String>]`: The name of the Windows IoT Device Service.
- `[Id <String>]`: Resource identity path
- `[ResourceGroupName <String>]`: The name of the resource group that contains the Windows IoT Device Service.
- `[SubscriptionId <String>]`: The subscription identifier.

## RELATED LINKS

Loading