Updated Readme.md #113

bgelens · 2017-07-02T10:14:47Z

Fixes: xHyper-V - Fix README.md markdown issues #112
Added missing or corrected DataType and Dsc attribute info
Added appveyor Dev badge
Added missing parameter info
Fixed / normalized examples
Added Opt In for Markdown common tests

This change is

…dsc attribute info

bgelens · 2017-07-02T10:19:14Z

@johlju or @PlagueHO Can anyone of you sign this off? Thanks!

johlju · 2017-07-02T11:33:01Z

Reviewed 2 of 2 files at r1.
Review status: all files reviewed at latest revision, 32 unresolved discussions.

README.md, line 4 at r1 (raw file):

The **xHyper-V** DSC module configures and manages a Hyper-V host using the
 **xVhd**, **xVMHyperV**, **xVMSwitch**, **xVhdFile**, **xVMDvdDrive**,

Do we need to list each resource here? Seems it could be missed when new resources are added. Could we just say something like "using Desired State Configuration." instead?
Or xSQLServer has the text 'The xSQLServer module contains DSC resources for deployment and configuration of SQL Server.'. So maybe something along those lines?

But if you want to keep it as-is, then that looks okay to me.

README.md, line 31 at r1 (raw file):

## Resources

* [**xVhd**](#xvhd) manages VHDs in a Hyper-V host.

Could you order these resources in alphabetical order?

README.md, line 31 at r1 (raw file):

## Resources

* [**xVhd**](#xvhd) manages VHDs in a Hyper-V host.

The resource and the resource folder is named xVHD (upper 'VHD'). This should reflect that. Or the resource should change the name to 'xVhd'.

README.md, line 47 at r1 (raw file):

 a Hyper-V virtual machine or to the management OS.

### xVhd

This resource has read parameters that should be listed here as well.

Example:
https://github.com/PowerShell/PSDscResources#read-only-properties-from-get-targetresource-4

README.md, line 47 at r1 (raw file):

 a Hyper-V virtual machine or to the management OS.

### xVhd

Between this and the parameters should we add the resource description? For now we could just copy the description from the ToC? If so, do that for all resources.

README.md, line 53 at r1 (raw file):

* **`[String]` ParentPath** (_Write_): Parent VHD file path, for differencing disk
* **`[Uint64]` MaximumSizeBytes** (_Write_): Maximum size of VHD to be created
* **`[String]` Generation** (_Write_): Virtual disk format: { Vhd | VHDx }

Add that the default value is 'Vhd'.

README.md, line 54 at r1 (raw file):

* **`[Uint64]` MaximumSizeBytes** (_Write_): Maximum size of VHD to be created
* **`[String]` Generation** (_Write_): Virtual disk format: { Vhd | VHDx }
* **`[String]` Ensure** (_Write_): Ensures that the VHD is Present or Absent

Add the value map to this as well. { *Present*\ | Absent }

Add that the text "Default value is 'Present'."
(also indicated with *Present* in the value map)

README.md, line 56 at r1 (raw file):

* **`[String]` Ensure** (_Write_): Ensures that the VHD is Present or Absent

### xVMHyperV

This resource has read parameters that should be listed here as well.

README.md, line 60 at r1 (raw file):

* **`[String]` Name** (_Key_): The desired VM name.
* **`[String]` VhdPath** (_Required_): The desired VHD associated with the VM.
* **`[String]` SwitchName** (_Write_): Virtual switch(es) associated with the VM.

Should be [string[]]

README.md, line 64 at r1 (raw file):

* **`[String]` State** (_Write_): State of the VM: { Running | Paused | Off }.
* **`[String]` Path** (_Write_): Folder where the VM data will be stored.
* **`[Uint32]` Generation** (_Write_): Virtual machine generation { 1 | 2 }.

Add that the default value is '1'.

README.md, line 66 at r1 (raw file):

* **`[Uint32]` Generation** (_Write_): Virtual machine generation { 1 | 2 }.
  Generation 2 virtual machines __only__ support VHDX files.
* **`[Boolean]` SecureBoot** (_Write_): Enables or disables secure boot

Add that the default value is $true.

README.md, line 81 at r1 (raw file):

* **`[Boolean]` RestartIfNeeded** (_Write_): If specified, will shutdown and
 restart the VM as needed for property changes.
* **`[String]` Ensure** (_Write_): Ensures that the VM is Present or Absent.

Add the value map to this as well. { *Present*\ | Absent }

Add that the default value is 'Present'.

README.md, line 83 at r1 (raw file):

* **`[String]` Ensure** (_Write_): Ensures that the VM is Present or Absent.
* **`[String]` Notes** (_Write_): Notes about the VM.
* **`[Boolean]` EnableGuestService** (_Write_): Enable Guest Service Interface

Add that the default value is $false.

README.md, line 86 at r1 (raw file):

 for the VM.

The following xVMHyper-V properties **cannot** be changed after VM creation:

Maybe move these up under the resource description? So this is shown before the parameters?

README.md, line 92 at r1 (raw file):

* Generation

### xVMSwitch

This resource has read parameters that should be listed here as well.

README.md, line 99 at r1 (raw file):

* **`[String[]]` NetAdapterName** (_Write_): Network adapter name(s)
 for external switch type
* **`[Boolean]` AllowManagementOS** (_Write_): Specify if the VM host

Add that the default value is $false.

README.md, line 101 at r1 (raw file):

* **`[Boolean]` AllowManagementOS** (_Write_): Specify if the VM host
 has access to the physical NIC
* **`[Boolean]` EnableEmbeddedTeaming** (_Write_): Should embedded NIC teaming

Add that the default value is $false.

README.md, line 103 at r1 (raw file):

* **`[Boolean]` EnableEmbeddedTeaming** (_Write_): Should embedded NIC teaming
 be used (Windows Server 2016 only)
* **`[String]` BandwidthReservationMode** (_Write_): Specify the QoS mode used

Add that the default value is 'NA'.

Also make NA italic in the value map.

README.md, line 106 at r1 (raw file):

 (options other than NA are only supported on Hyper-V 2012+):
 { Default | Weight | Absolute | None | NA }.
* **`[String]` Ensure** (_Write_): Ensures that the VM Switch is Present or Absent

Add the value map to this as well. { *Present*\ | Absent }

Add that the default value is 'Present'.

README.md, line 108 at r1 (raw file):

* **`[String]` Ensure** (_Write_): Ensures that the VM Switch is Present or Absent

### xVhdFile

Could you order these resources in alphabetical order?

README.md, line 108 at r1 (raw file):

* **`[String]` Ensure** (_Write_): Ensures that the VM Switch is Present or Absent

### xVhdFile

Why is it a class thatis named xFileDirectory in this schema?
https://github.com/bgelens/xHyper-V/blob/dev/DSCResources/MSFT_xVhdFileDirectory/MSFT_xVhdFileDirectory.schema.mof

README.md, line 108 at r1 (raw file):

* **`[String]` Ensure** (_Write_): Ensures that the VM Switch is Present or Absent

### xVhdFile

Missing parameter CheckSum.

Add default value is 'ModifiedDate' for parameter CheckSum.

README.md, line 111 at r1 (raw file):

[MSFT_xFileDirectory]

Should be [MSFT_xFileDirectory[]]

README.md, line 126 at r1 (raw file):

 file or physical hard disk volume for the added DVD drive.
* **`[String]` Ensure** (_Write_): Specifies if the DVD Drive should exist or not.
 { *Present* | Absent }. Defaults to Present.

Depending on how your write the others this might need to be revised.

README.md, line 128 at r1 (raw file):

 { *Present* | Absent }. Defaults to Present.

### xVMNetworkAdapter

This resource has read parameters that should be listed here as well.

README.md, line 139 at r1 (raw file):

* **`[String]` MacAddress** (_Write_): Use this to specify a Static MAC Address.
 If this parameter is not specified, dynamic MAC Address will be set.
* **`[String]` Ensure** (_Write_): Ensures that the VM Network Adapter is

Add the value map to this as well. { *Present*\ | Absent }

And add that the default value is 'Present'.

README.md, line 386 at r1 (raw file):

    xVMSwitch switch
    {
        Name = "Test-Switch"

Use single quotes on all strings with only text. Do this throughput these examples.

README.md, line 401 at r1 (raw file):

    }

    # Customize VHD by copying a folders/files to the VHD before a VM can be created

Comment block for this text.

README.md, line 412 at r1 (raw file):

create the generation 1 testVM out of the vhd.

Upper 'C' on Create.

Should be upper-case VHD?

README.md, line 1151 at r1 (raw file):

        [Parameter(Mandatory=$true, Position=0)]
        [ValidateScript({Test-Path -Path $_})]
        [string]

Maybe use [System.String]? If so, do this throughout.

README.md, line 1195 at r1 (raw file):

        [Parameter()]
        [ValidateSet ("Archive", "Hidden",  "ReadOnly", "System" )]
        $Attribute

No type on this one.

README.md, line 1229 at r1 (raw file):

    )

    Import-DscResource -Module xHyper-V

Are you sure it shouldn't be ModuleName?

https://msdn.microsoft.com/en-us/powershell/dsc/sxsresource

Comments from Reviewable

…ngelog. Linked to examples instead of duplication (created missing samples from Readme code)

bgelens · 2017-07-03T12:12:08Z

@johlju Based on your comments I decided to do the entire overhaul based on how DscResources Readme is done.

Also added a change log and removed all example code from the Readme and replaced with links.

The example files are the same as the example code was in the Readme. A couple example files where missing, these are created from the code which was in the Readme.

Examples will be checked and if needed improved (new issue #114 )

Review status: 1 of 7 files reviewed at latest revision, 32 unresolved discussions.

README.md, line 4 at r1 (raw file):