Convert-Byte PowerShell Cmdlet


Today is an interesting day for me at work. I was tidying up another PowerShell script for shadowcopystorage when I pondered into some part of the script and decided to rip it off to turn it into a cmdlet.

Why? I was checking some disk space alert in our production environment when I came to the conclusion that every administrator tends to go online to Google for storage unit conversion for convert byte to kilobyte, megabyte, gigabyte, terabyte and vice versa. Unless you are those few mathematicians out there in the world that can convert those numbers on the fly.

Since I am not and my job do rely on those conversion  a lot so that I know how much disk resource, memory resource or network resource we are actually talking about, I came to the conclusion that we need a cmdlet for it.

What is the big deal? We can always go Google it and convert those units. Of course, a PowerShell cmdlet of converting units is not new but it is just handy for me as I am always on the command prompt or in Windows Core where opening internet explorer is costing more than 2 movements for it. I sound like couch potatoes. Ouch!

Alright, here it is below. It is properly commented and documented for ease of use to all administrators out there.

Convert-Byte is a PowerShell Cmdlet to convert unit types. It a handy tool to have on the PowerShell Console for engineers and administrators. No more having to open up internet explorer and Google for unit converter to calculate the disk, memory or network resources for analysis or reporting. The cmdlet allows pipeline for other cmdlet and can return values for another piplined cmdlet.

Download Link – http://gallery.technet.microsoft.com/Convert-Byte-f90c0195

This will be extremely handy when you install Windows 2012 Server Core Installation where you have no GUI or Internet Explorer.

[Update]
19/07/2012 Update: Added IsNumeric check to verify input value is numeric data type or not.

Reason: Because I tried to pipeline to Convert-Byte and it threw me an error. To my horror, I took it for granted that we will be dealing with numbers most of the time but in fact not always the case in PowerShell. Everything is an object. Duh…

function Convert-Byte {

<#   
.SYNOPSIS   
    Convert any 64bit numeric value between the following unit types, Kilobyte, 
    Megabyte, Gigabyte, Terabyte and Petabyte
  
.DESCRIPTION   
    Allows the administrator to convert any 64bit numeric value from the following unit 
    types; Kilobyte, Megabyte, Gigabyte, Terabyte and Petabyte to another type of units 
    type for easier calculation of disk space usage, memory usage, shadowcopystorage 
    usage or network usage.
    
    By default, the conversion result value will be rounded up to the nearest 2 decimal 
    places. There are some optional parameter switch to round up all decimal places or 
    truncate all decimal places for easier pipeline calculation in integer data type.

.PARAMETER Value
    
    Specify a numeric value
    
.PARAMETER ValueIsKB
    
    ALIAS -KB
    
    Specify the current numeric value unit is kilobyte
         
.PARAMETER ValueIsMB
    
    ALIAS -MB
    
    Specify the current numeric value unit is megabyte
    
.PARAMETER ValueIsGB
    
    ALIAS -GB
    
    Specify the current numeric value unit is gigabyte

.PARAMETER ValueIsTB
    
    ALIAS -TB
    
    Specify the current numeric value unit is terabyte

.PARAMETER ValueIsPB
    
    ALIAS -PB
    
    Specify the current numeric value unit is petabyte

.PARAMETER ConvertToKB
    
    ALIAS -CKB
    
    Specify to convert the current numeric value unit to kilobyte
         
.PARAMETER ConvertToMB
    
    ALIAS -CMB
    
    Specify to convert the current numeric value unit to megabyte
    
.PARAMETER ConvertToGB
    
    ALIAS -CGB
    
    Specify to convert the current numeric value unit to gigabyte

.PARAMETER ConvertToTB
    
    ALIAS -CTB
    
    Specify to convert the current numeric value unit to terabyte

.PARAMETER ConvertToPB
    
    ALIAS -CPB
    
    Specify to convert the current numeric value unit to petabyte

.PARAMETER Truncate
    
    ALIAS -T
    
    Specify to truncate all decimal places from the numeric value result

.PARAMETER RoundUp
    
    ALIAS -R
    
    Specify to round up decimal place on the numeric value result
        
.INPUTS
    Any numeric data type such as Integer, Long, Decimal, Single or Double

.OUTPUTS
    By default, the output will be rounded up to 2 decimal places of the input numeric 
    data type such as Integer, Long, Decimal, Single or Double unless optional parameter 
    is specified to round up or truncate the decimal places.


.EXAMPLE
    Convert-Byte 1024 -ConvertToKB
    
    This convert the numeric value 1024 bytes to kilobytes and returns the value

.EXAMPLE
    Convert-Byte 1024 -CKB
    
    This uses the alias parameter to convert the numeric value 1024 bytes to kilobytes 
    and returns the value

.EXAMPLE
    Convert-Byte 1024 -MB -CKB
    
    This convert the numeric value 1024 from megabytes to kilobytes and returns the 
    value

.EXAMPLE
    Convert-Byte 1048576 -GB -CPB
    
    This convert the numeric value 1048576 from gigabytes to petabytes and returns the 
    value
    
.EXAMPLE
    Convert-Byte 1048576 -TB -CGB -Verbose
    VERBOSE: 1048576 TB = 1073741824 GB
    
    This convert the numeric value 1048576 from terabytes to gigabytes and returns a 
    verbose output
                        
.EXAMPLE
    Get-ChildItem C:\Windows\Logs -Recurse | Measure-Object -Property Length -Sum | Select -ExpandProperty Sum | Convert-Byte -CMB -Verbose
    VERBOSE: 5578431 Byte = 5.62 MB
    
    This convert the total length sum of the C:\Windows\Logs folder size to megabyte. By 
    default, the returned result will be in 2 decimal places

.EXAMPLE
    Get-ChildItem C:\Windows\Logs -Recurse | Measure-Object -Property Length -Sum | Select -ExpandProperty Sum | Convert-Byte -CMB -R -Verbose
    VERBOSE: 5.62 MB = 6 MB
    
    This convert the total length sum of the C:\Windows\Logs folder size to megabyte and 
    will round up any decimal places
     
 .EXAMPLE
    Get-ChildItem C:\Windows\Logs -Recurse | Measure-Object -Property Length -Sum | Select -ExpandProperty Sum | Convert-Byte -CMB -T -Verbose
    VERBOSE: 5578431 Byte = 5 MB
    
    This convert the total length sum of the C:\Windows\Logs folder size to megabyte and 
    will truncate any decimal places
    
 .EXAMPLE
    Convert-Byte A1234 -CKB -Verbose
    VERBOSE: A1234 = A1234
    
    Because this input value is non-numeric value, the Convert-Byte will not attempt to 
    convert the value
    
    Convert-Byte 1234 -CKB -Verbose
    VERBOSE: 1234 Byte = 1.21 KB
    
    This convert the numeric value into kilobyte and returns in verbose with the value 
    in their representative data type unit

.NOTES   
    Author  : Ryen Kia Zhi Tang
    Date    : 16/07/2012
    Blog    : ryentang.wordpress.com
    Version : 1.0
    
    Update  : Added IsNumeric check to verify input value is numeric data type or not.
    Date    : 19/07/2012
    Version : 1.1

#>

[CmdletBinding(
    SupportsShouldProcess=$True,
    ConfirmImpact='High')]

param (

[Parameter(
    Mandatory=$True,
    ValueFromPipeline=$True,
    ValueFromPipelineByPropertyName=$True)]
    
    $Value,

[Parameter(
    Mandatory=$False,
    ValueFromPipeline=$True,
    ValueFromPipelineByPropertyName=$True)]
    [alias("KB")]
    [switch] $ValueIsKB,

[Parameter(
    Mandatory=$False,
    ValueFromPipeline=$True,
    ValueFromPipelineByPropertyName=$True)]
    [alias("MB")]
    [switch] $ValueIsMB,

[Parameter(
    Mandatory=$False,
    ValueFromPipeline=$True,
    ValueFromPipelineByPropertyName=$True)]
    [alias("GB")]
    [switch] $ValueIsGB,

[Parameter(
    Mandatory=$False,
    ValueFromPipeline=$True,
    ValueFromPipelineByPropertyName=$True)]
    [alias("TB")]
    [switch] $ValueIsTB,

[Parameter(
    Mandatory=$False,
    ValueFromPipeline=$True,
    ValueFromPipelineByPropertyName=$True)]
    [alias("PB")]
    [switch] $ValueIsPB,
        
[Parameter(
    Mandatory=$False,
    ValueFromPipeline=$True,
    ValueFromPipelineByPropertyName=$True)]
    [alias("CKB")]
    [switch] $ConvertToKB,

[Parameter(
    Mandatory=$False,
    ValueFromPipeline=$True,
    ValueFromPipelineByPropertyName=$True)]
    [alias("CMB")]
    [switch] $ConvertToMB,

[Parameter(
    Mandatory=$False,
    ValueFromPipeline=$True,
    ValueFromPipelineByPropertyName=$True)]
    [alias("CGB")]
    [switch] $ConvertToGB,
    
[Parameter(
    Mandatory=$False,
    ValueFromPipeline=$True,
    ValueFromPipelineByPropertyName=$True)]
    [alias("CTB")]
    [switch] $ConvertToTB,
    
[Parameter(
    Mandatory=$False,
    ValueFromPipeline=$True,
    ValueFromPipelineByPropertyName=$True)]
    [alias("CPB")]
    [switch] $ConvertToPB,

[Parameter(
    Mandatory=$False,
    ValueFromPipeline=$True,
    ValueFromPipelineByPropertyName=$True)]
    [alias("T")]
    [switch] $Truncate,

[Parameter(
    Mandatory=$False,
    ValueFromPipeline=$True,
    ValueFromPipelineByPropertyName=$True)]
    [alias("R")]
    [switch] $RoundUp

)

BEGIN {
    #clear variables
    $IsNumeric = 0
    $InputValue = ""
}

PROCESS {

    #verify input value is numeric data type
    try { 0 + $Value | Out-Null
    $IsNumeric = 1 }catch{ $IsNumeric = 0 }
    
    #store the input value
    $InputValue = $Value
    
    #if -KB parameter is used, convert KB to Byte
    if($ValueIsKB -and $IsNumeric) { $Value = $Value*1KB 
    $InputUnit = "KB" }
    
    #if -MB parameter is used, convert MB to Byte
    elseif($ValueIsMB -and $IsNumeric) { $Value = $Value*1MB 
    $InputUnit = "MB" }
    
    #if -GB parameter is used, convert GB to Byte
    elseif($ValueIsGB -and $IsNumeric) { $Value = $Value*1GB 
    $InputUnit = "GB" }
    
    #if -TB parameter is used, convert TB to Byte
    elseif($ValueIsTB -and $IsNumeric) { $Value = $Value*1024GB 
    $InputUnit = "TB" }
    
    #if -PB parameter is used, convert PB to Byte
    elseif($ValueIsPB -and $IsNumeric) { $Value = $Value*1048576GB 
    $OutputUnit = "PB" }
    
    #if no parameter is used, default is used. it will assume input $value is in byte.
    else{ $InputUnit = "Byte" }
    
        
    
    #if -CKB parameter is used, convert Byte to KB
    if($ConvertToKB -and $IsNumeric) { $Value = $Value/1KB 
    $OutputUnit = "KB" }
        
    #if -CMB parameter is used, convert Byte to MB    
    elseif($ConvertToMB -and $IsNumeric) {$Value = $Value/1MB 
    $OutputUnit = "MB" }
        
    #if -CGB parameter is used, convert Byte to GB
    elseif($ConvertToGB -and $IsNumeric) { $Value = $Value/1GB 
    $OutputUnit = "GB" }
    
    #if -CTB parameter is used, convert Byte to TB
    elseif($ConvertToTB -and $IsNumeric) { $Value = $Value/1024GB 
    $OutputUnit = "TB" }
    
    #if -CPB parameter is used, convert Byte to PB
    elseif($ConvertToPB -and $IsNumeric) { $Value = $Value/1048576GB 
    $OutputUnit = "PB" }
    
    #if no parameter is used, default is used. it will assume to return $value in byte.
    else { $OutputUnit = "Byte" }
    
    
    
    #if -T parameter is used, truncate all decimal places on the numeric value
    if($Truncate){ $Value = [math]::Truncate($Value) }
    
    #if -R parameter is used, round up the decimal place on the numeric value
    elseif($RoundUp) { $Value = [math]::Round($Value) }
    
    #if no parameter is used, default is used. it will round up to 2 decimal places on the numeric value
    elseif($IsNumeric) { $Value = [math]::Round($Value, 2) }
    
}

END {

    #return result
    if($PSBoundParameters['Verbose'] -and $IsNumeric){ Write-Verbose "$InputValue $InputUnit = $Value $OutputUnit" }
    elseif($PSBoundParameters['Verbose'] -and !$IsNumeric){ Write-Verbose "$InputValue = $Value" }else{ return $Value }

}

} #end of #function Convert-Byte
Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s