c# pdf viewer free : Reordering pages in pdf Library software component asp.net wpf html mvc Windows%20Powershell%20in%20Action%202nd%20Edition34-part1488

310
CHAPTER 8
A
DVANCED
FUNCTIONS
AND
SCRIPTS
Validation attribute: ValidateSet 
The 
ValidateSet
attribute ensures that the argument is a member of the specific set 
of values passed to the  attribute. In the following example, the argument  to the 
$color
parameter can contain only the values 
red
blue
, or 
green
:
PS (5) > function validateSetExample 
>> { 
>>   param ( 
>>     [ValidateSet("red", "blue", "green")] 
>>     [ConsoleColor] $color 
>>   ) 
>>   $color 
>> } 
>>
Try it with a valid argument
PS (6) > validateSetExample red
Red
and an invalid argument:
PS (7) > validateSetExample cyan 
validateSetExample : Cannot validate argument on parameter 
'color'. The argument "Cyan" does not belong to the set "re 
d,blue,green" specified by the ValidateSet attribute. Suppl 
y an argument that is in the set and then try the command a 
gain.
At line:1 char:19 
+ validateSetExample <<<<  cyan
+ CategoryInfo          : InvalidData: (:) [validateSe
tExample], ParameterBindingValidationException
+ FullyQualifiedErrorId : ParameterArgumentValidationE
rror,validateSetExample) 
Note that the error message contains the list of valid values. Notice that you passed an 
array of arguments to the parameter, but the type of the parameter is 
[Console-
Color]
, not 
[ConsoleColor[]]
—that is, it’s not an array parameter. This works 
because 
[ConsoleColor]
is a .
NET
enum type where multiple values can be com-
bined to produce a new value in the set. The PowerShell runtime understands that 
this and combines the arguments to produce a single result.
Validation attribute: ValidateScript
And now for the final validation attribute. As promised, we’ve saved the best (or at 
least the most powerful) for last. The 
ValidateScript
attribute allows you to spec-
ify a chunk of PowerShell script to use to validate the argument. This means that it 
can do anything. The argument to test is passed in as 
$_
to the code fragment, which 
should return 
$true
or 
$false
. In the following example, the attribute is used to 
verify that the argument is an even number:
PS (8) > function validateScriptExample 
>> {
Reordering pages in pdf - re-order PDF pages in C#.net, ASP.NET, MVC, Ajax, WinForms, WPF
Support Customizing Page Order of PDF Document in C# Project
pdf move pages; reorder pages in pdf file
Reordering pages in pdf - VB.NET PDF Page Move Library: re-order PDF pages in vb.net, ASP.NET, MVC, Ajax, WinForms, WPF
Sort PDF Document Pages Using VB.NET Demo Code
how to rearrange pdf pages online; how to change page order in pdf acrobat
D
YNAMIC
PARAMETERS
AND
DYNAMIC
P
ARAM
311
>>   param ( 
>>    [int] [ValidateScript({$_ % 2 -eq 0})] $number 
>>   ) 
>>   $number 
>> } 
>>
This succeeds for 2
PS (9) > validateScriptExample 2 
2
and fails for 3: 
PS (10) > validateScriptExample 3 
validateScriptExample : Cannot validate argument on paramet 
er 'number'. The "$_ % 2 -eq 0" validation script for the a 
rgument with value "3" did not return true. Determine why t 
he validation script failed and then try the command again. 
At line:1 char:22 
+ validateScriptExample <<<<  3
+ CategoryInfo          : InvalidData: (:) [validateSc
riptExample], ParameterBindingValidationException
+ FullyQualifiedErrorId : ParameterArgumentValidationE
rror,validateScriptExample
As with the 
ValidatePattern
attribute, the error message doesn’t provide the best 
user experience, limiting the value of this attribute for validation. On the other hand, 
it can also be used for things like logging and tracing, counting the number of times 
the parameter was used, and so on simply by taking the appropriate action and then 
returning 
$true
.
Now that we’ve covered all the things you can do with explicit parameters, we’re 
going to investigate an alternate mechanism for parameter specification. This alter-
nate mechanism allows you to do something that isn’t possible with explicit parame-
ter  specification:  write  scripts  and  functions  that  can  dynamically  adapt  their 
parameter signatures to the environment. We’ll cover this topic in the next section.
8.3
D
YNAMIC
PARAMETERS
AND
DYNAMIC
P
ARAM
Explicit or static parameters are defined as part of the source code for a script or func-
tion and are fixed when that script or function is compiled. But a script or function 
can also define parameters at runtime. These new parameters are added dynamically 
based on runtime conditions instead of statically at parse time. This allows you to 
write functions to specialize their interface (i.e., their parameters) based on ambient 
conditions. The best example of this is  a  cmdlet like 
Set-Content
. When 
Set-
Content
is used in a file system drive, it lets you specify file-specific parameters like 
-Encoding
. In other providers where this parameter doesn’t make sense, it isn’t pres-
ent in the cmdlet signature. Because these parameters are defined dynamically, they’re 
called (no surprise, I’m sure) dynamic parameters. Cmdlets have always had this capa-
bility, but PowerShell v2 makes the facility available for scripts and functions as well.
C# PDF Page Delete Library: remove PDF pages in C#.net, ASP.NET
rotating function, PDF page inserting function, PDF page reordering function and single page, a series of pages, and random pages to be removed from PDF file
move pages in pdf document; how to reorder pages in pdf online
VB.NET TIFF: VB.NET Sample Codes to Sort TIFF File with .NET
& manipulating multi-page TIFF (Tagged Image File), PDF, Microsoft Office it with our RasterEdge TIFF decoder, and then start reordering the pages for the
reorder pdf pages reader; how to rearrange pdf pages
312
CHAPTER 8
A
DVANCED
FUNCTIONS
AND
SCRIPTS
If you want your scripts and functions to have dynamic parameters, you have to 
use the 
dynamicParam
keyword. The syntax for this keyword is 
dynamicParam { <statement-list> } 
Let’s work through the steps needed to implement dynamic parameters. Warning: 
this isn’t for the faint of heart, but it’s a powerful technique that, when needed, allows 
you to deliver the best experience for the users of your scripts.
8.3.1
Steps for adding a dynamic parameter 
In this section, we’ll walk you through the steps necessary to define dynamic parame-
ters in a function. First, you’ll specify a 
dynamicParam
block in your function. Then, 
in the body of the 
dynamicParam
block, you’ll use an 
if
statement to specify the 
conditions under which the parameter is to be available. To define the actual parame-
ters you want to expose, you need to use the 
New-Object
cmdlet to create a instance 
of the type
System.Management.Automation.RuntimeDefinedParameter
You’ll use this object to define your dynamic parameter and, at a minimum, you’ll 
have to specify its name. If you need to apply some additional attributes, you’ll have 
to use the 
New-Object
command to create an instance of the type
System.Management.Automation.ParameterAttribute
which is used to include the 
Mandatory
Position
, or 
ValueFromPipeline
attri-
butes you saw earlier in this chapter.
In the following example, you define a function with two static parameters—
Name 
and 
Path
—and  an  optional dynamic parameter  named 
dp1
dp1
is in the 
set1 
parameter set and has a type: 
[int]
. The dynamic parameter is available only when 
the value of the 
Path
parameter begins with 
HKLM:
, indicating that it’s being used in 
the Registry drive. The complete function is shown in figure 8.8.
This function will return the bound parameters in the end block of the function.
NOTE
The variable 
$PSBoundParameters
is a new automatic vari-
able introduced in PowerShell v2. This variable contains a hashtable 
with  all  the  parameters  that  were  bound  when  the  command  was 
invoked. You’ll learn more about this variable when we cover proxy 
commands in chapter 11. 
The presence of the 
dynamicParam
block forces you to explicitly use the 
end
key-
word just like using the 
begin
and 
process
keywords would. Now run the function. 
Try the function in the 
C
: drive:
PS (2) > dynamicParameterExample -dp1 13 -Path c:\ 
dynamicParameterExample : A parameter cannot be found that 
matches parameter name 'dp1'.
At line:1 char:29
C# Excel - Sort Excel Pages Order in C#.NET
C#.NET Excel document page reordering control SDK (XDoc.Excel) is a thread-safe .NET library that can be used to adjust the Excel document pages order.
change pdf page order; rearrange pdf pages
C# TIFF: C#.NET TIFF Document Viewer, View & Display TIFF Using C#
Support most common TIFF file page processing, like adding, deleting and reordering pages; Free to convert TIFF document to PDF document for management purpose;
reorder pages in pdf online; how to move pages in a pdf document
D
YNAMIC
PARAMETERS
AND
DYNAMIC
P
ARAM
313
+ dynamicParameterExample -dp1 <<<<  13 -Path c:\
+ CategoryInfo          : InvalidArgument: (:) [dynami
cParameterExample], ParameterBindingException
+ FullyQualifiedErrorId : NamedParameterNotFound,dynam
icParameterExample
You get an error saying that no 
-dp1
parameter was found. Now try it with 
HKLM:
PS (3) > dynamicParameterExample -dp1 13 -Path HKLM:\
Key                           Value 
---                           -----
Path                          HKLM:\ 
dp1                           13
This  time, the function executes without error and  shows  you  that  the  dynamic 
parameter was bound as desired. 
function dynamicParameterExample
{
[cmdletbinding()]
param (
[String]$name,
[String]$path
)
dynamicparam
{
if ($path -match "^HKLM:")
{
$attributes = New-Object ` 
System.Management.Automation.ParameterAttribute `
-Property @{
ParameterSetName = "set1"
Mandatory = $false
}
$attributeCollection = New-Object `
System.Collections.ObjectModel.Collection[System.Attribute]
$attributeCollection.Add($attributes)
$dynParam1 = New-Object ` 
System.Management.Automation.RuntimeDefinedParameter `
dp1,int, $attributeCollection
$paramDictionary = New-Object `
Management.Automation.RuntimeDefinedParameterDictionary
$paramDictionary.Add("dp1", $dynParam1)
$paramDictionary
}
}
end {  $psboundparameters }
}
Static parameter definitions
Creates object that will provide
parameter attributes
Creates parameter
object and parameter 
dictionary to hold it
Returns parameter dictionary
so runtime can use it for 
binding parameters
Returns bound parameters
Figure 8.8 A function that defines dynamic parameters. If the 
-Path
parameter is set to some-
thing that starts with 
HKML:
an additional parameter, 
dp1
, will be defined for the function.
C# PDF File Merge Library: Merge, append PDF files in C#.net, ASP.
online C#.NET source code for combining multiple PDF pages together in insertion, PDF page deleting, PDF document splitting, PDF page reordering and PDF
how to move pages in pdf reader; reverse page order pdf
VB.NET Word: Change Word Page Order & Sort Word Document Pages
in following VB.NET Word page reordering API is Apart from this VB.NET Word pages sorting function powerful & profession imaging controls, PDF document, image
how to move pages within a pdf; moving pages in pdf
314
CHAPTER 8
A
DVANCED
FUNCTIONS
AND
SCRIPTS
As you can see, using dynamic parameters is a fairly complex task. The task is basi-
cally the same in script or in a compiled language like 
C
#. If you can follow this 
example, you’re well on your way to understanding dynamic parameters in 
C
#.
8.3.2
When should dynamic parameters be used?
So when would you use this technique? The most common case is something like the 
namespace providers mentioned earlier where most of the parameters are the same 
but certain parameters may only be present based on the path. This allows you to 
have one command to deal with many similar but slightly different scenarios. This 
reduces the number of commands a user has to learn. The other place where dynamic 
parameters might be used is when you want to base the parameters on some type of 
dynamic configuration, like the set of columns in a database table. You could write a 
single cmdlet, called something like 
Update-DatabaseTable
, that uses the names 
and types of the columns to add dynamic parameters for the cmdlet.
This concludes our discussion of dynamic parameters and also completes the over-
all discussion of parameterization of scripts and functions. You now have all the nec-
essary tools to define optimal interfaces or signatures for your scripts and functions. 
But knowing how to define the signature for a script is only half the battle—at least if 
you want someone other than yourself to use these scripts. No matter how good the 
interface is, production scripting still requires documentation for the scripts you’re 
producing. In the next section, I’ll explain how this is accomplished.
8.4
D
OCUMENTING
FUNCTIONS
AND
SCRIPTS
In this section, we’ll look at the various mechanisms you can use to provide docu-
mentation for your scripts. Unfortunately, in PowerShell v1, there was no good way 
to document functions and scripts. This was fixed in v2 by adding three new features:
• Automatic help information generated from the function or script definition
• A special way of processing comments to extract help information from them
• A mechanism for associating external help files with a function or script
The first of these mechanisms is the automatic generation of help text from a func-
tion or script definition. When you define a function, the PowerShell help system can 
generate some amount of help information for that function. To illustrate, define a 
simple function:
PS (1) > function abc ([int] $x, $y) { }
Now you can call 
Get-Help
on this function
PS (2) > Get-Help abc 
abc [[-x] <Int32>] [[-y] <Object>]
and you get the synopsis for the function. As you can see, the help subsystem tries to 
do as much work for you as it can automatically. In the next section we’ll look at the 
fields that can be automatically generated.
C# Word - Delete Word Document Page in C#.NET
page rotating function, Word page inserting function, Word page reordering function and options, including setting a single page, a series of pages, and random
how to reorder pdf pages in; how to rearrange pages in a pdf reader
C# PowerPoint - Delete PowerPoint Document Page in C#.NET
page rotating function, PowerPoint page insert function, PowerPoint page reordering function and including setting a single page, a series of pages, and random
move pages in pdf reader; pdf rearrange pages online
D
OCUMENTING
FUNCTIONS
AND
SCRIPTS
315
8.4.1
Automatically generated help fields
A certain number of the help fields are generated automatically: name, syntax, param-
eter list, parameter attribute table, common parameters, and remarks. These elements 
are described in table 8.1. 
The automatically generated help is minimal. You’ll deliver a much better result by 
adding your own help content.
8.4.2
Creating manual help content
Although it’s handy to know the command’s syntax, knowing what the command 
does is more useful. This is where the manual documentation mechanisms come in. 
PowerShell provides two ways for documenting scripts and functions: in line with 
special documentation comments or externally in a help file.
Documentation comments (or doc comments) are a convention for using com-
ments when writing scripts such that these comments can be automatically used to 
fill in help information. These comments must be placed in particular locations in 
scripts  for them to be processed as doc comments and can contain a number of 
markup tags for structuring the help information. We’ll cover these details in the next 
section. The final mechanism for providing function/script help uses external files.
Table 8.1 Automatically generated help fields
Help element
Description
Name
The Name section of the help topic for a function is taken from the 
name of the function. For a script, it’s taken from the name of the 
script file.
Syntax
The Syntax section of the help topic is generated from the function or 
script syntax (in other words, the parameter definitions). If a parameter 
has a type attribute associated with it, that type will be displayed as part 
of the syntax. If you don’t specify a parameter type, Object is inserted 
as the default value.
Parameter list
The Parameter list in the help topic is generated from the function or 
script syntax and from the descriptions that you add to the parameters. 
The function parameters appear in the “Parameters” section in the 
same order in which they appear in the function or script definition. The 
spelling and capitalization of parameter names is also taken from the 
definition.
Common parameters
The common parameters are added to the syntax and parameter list of 
the help topic, even if they have no effect.
Parameter attribute table
Get-Help generates the table of parameter attributes that appears 
when you use the -Full or -Parameter parameter of Get-Help. 
The value of the Required, Position, and Default properties is 
taken from the function or script definition. 
Remarks
The Remarks section of the help topic is automatically generated from 
the function or script name.
C# TIFF: How to Insert & Add Page(s) to TIFF Document Using C#
SDK still empowers developers and end users to do Tiff image rotating, deleting, reordering, extracting, etc. C# Tiff processing application - sort Tiff pages.
switch page order pdf; rearrange pages in pdf file
316
CHAPTER 8
A
DVANCED
FUNCTIONS
AND
SCRIPTS
External help files are 
XML
files written in the Microsoft Assistance Markup Lan-
guage 
(MAML)
format. In PowerShell v1, this mechanism was available only for cmd-
lets. In v2, the help file facility can be used with functions and scripts as well. So why 
have these external files? Because they allow for the help content to be translated 
(localized) into many different languages whereas doc comments only allow help to 
be written in a single language. Doc comments also require the script file itself to be 
changed just to change a typo in the help documentation. 
As you can see, the help mechanism scales from simple but incomplete up to a 
full production-level, localizable help system—one of the themes of PowerShell v2. 
We didn’t need to say much about the automatic help facility (obviously), but the 
other two mechanisms require more explanation. We’ll start with the doc comment 
mechanism.
8.4.3
Comment-based help
Comment-based help is the easiest way to add help for functions and scripts. It works 
by using special help comment tags in comments associated with a function defini-
tion or script. These comments are parsed by the PowerShell interpreter and used to 
create  the help topics.  Once  this  information  is  available,  the 
Get-Help
cmdlet 
returns help objects just like you get from the help files associated with cmdlets. 
When you specify the correct tags, doc comments can specify all the help views pro-
vided by 
Get-Help
, such as 
Detailed
Full
Example
, and 
Online
, to display func-
tion and script help.
Comment-based help is written as a series of comments. These comments can 
either be single-line comments where there is a 
#
before each line, or you can use the 
new block comment feature in PowerShell v2, where the comments are enclosed in 
<#
and 
#>
sequences. All of the lines in a doc comment topic must be contiguous. If 
a doc comment follows a comment that’s not part of the help topic, there must be at 
least one blank line between the last non-help comment line and the beginning of the 
comment-based help.
For functions, the doc comments can be placed in one of three places:
• At the beginning of the function body, after the open brace.
• At the end of the function body.
• Before the function keyword. In this case, if the comment is to be processed as a 
doc comment, there can’t be more than one blank line between the last line of 
the comment and the 
function
keyword. 
For scripts, the doc comments must be either at the beginning or the end of the script 
file. If they’re at the beginning, there can only be non-doc comments or blank lines 
before the first doc comment. There’s also one other little issue to consider: if the doc 
comments for a script are at the beginning of a script and the first thing a script con-
tains is a function definition, then should the doc comment apply to the script or the
D
OCUMENTING
FUNCTIONS
AND
SCRIPTS
317
function? This ambiguity is resolved by requiring that there be at least two blank lines 
between the end of the doc comment for the script and the beginning of the function.
Let’s look at a basic example; you’ll use single-line comments and the 
.SYNOPSIS 
tag to add a definition for the 
abc
function you defined earlier. The definition now 
looks like
PS (1) > function abc ([int] $x, $y) 
>> { 
>> #.SYNOPSIS 
>> #This is my abc function 
>> } 
>>
Run the 
Get-Help
command again. The last time, you got a very basic synopsis. Let’s 
see what you get this time:
PS (2) > Get-Help abc
NAME
abc
SYNOPSIS
This is my abc function
SYNTAX
abc [[-x] <Int32>] [[-y] <Object>] [<CommonParameters>]
DESCRIPTION
RELATED LINKS
REMARKS
To see the examples, type: "get-help abc -examples".
For more information, type: "get-help abc -detailed".
For technical information, type: "get-help abc -full".
Now you get much more output. Of course, much of it’s empty—you haven’t speci-
fied all the sections yet. You can guess pretty easily what some of the sections should 
be. Let’s add a description for the function. This time you’ll use the block comments 
notation—it’s much easier to work with.
NOTE
PowerShell added block comments to make it easier to write 
doc comments. The sequences 
<#
and 
#>
were chosen in part because 
they look somewhat like XML, which is used for external help files.
Here’s what the new function definition looks like:
PS (3) > function abc ([int] $x, $y) 
>> { 
>> <# 
>> .SYNOPSIS 
>> This is my abc function
318
CHAPTER 8
A
DVANCED
FUNCTIONS
AND
SCRIPTS
>> .DESCRIPTION 
>> This function is used to demonstrate writing doc 
>> comments for a function. 
>> #> 
>> } 
>>
When you run 
Get-Help
, you see
PS (4) > Get-Help abc
NAME
abc
SYNOPSIS
This is my abc function
SYNTAX
abc [[-x] <Int32>] [[-y] <Object>] [<CommonParameters>]
DESCRIPTION
This function is used to demonstrate writing doc
comments for a function.
RELATED LINKS
REMARKS
To see the examples, type: "get-help abc -examples".
For more information, type: "get-help abc -detailed".
For technical information, type: "get-help abc -full".
with the description text in its proper place.
The basic pattern should be obvious by now. Each help section begins with a spe-
cial tag of the form 
.TAGNAME
, followed by the content for that section. The tag must 
appear on a line by itself to be recognized as a tag but can be preceded or followed by 
whitespace. The order in which tags appear doesn’t matter. Tags are not case sensitive 
but by convention they’re always written in uppercase. (This makes the structure of 
the comment easier to follow.)
For a comment block to be processed as a doc comment, it must contain at least 
one section tag. Most tags can be specified only once per function definition, but 
there are some exceptions. For instance, 
.EXAMPLE
can appear many times in the 
same comment block. The help content for each tag begins on the line after the tag 
and can span multiple lines. 
8.4.4
Tags used in documentation comments
A fairly large number of tags can be used when creating doc comments. These tags are 
shown in table 8.2. They’re listed in the order in which they typically appear in out-
put of 
Get-Help
D
OCUMENTING
FUNCTIONS
AND
SCRIPTS
319
Some of these tags require a bit more explanation. This is addressed in the following 
sections.
.PARAMETER <Parameter-Name> help tag
This is where you add the description for a parameter. The parameter must be named 
in the argument to the tag. You can include a 
.PARAMETER
tag for each parameter in 
the function or script, and the 
.PARAMETER
tags can appear in any order in the com-
ment block. The order in which things are presented is controlled by the parameter 
definition order, not the help tag order. If you want to change the display order, you 
have to change the order in which the parameters are defined.
Alternatively, you can specify a parameter description simply by placing a com-
ment before the parameter definition on the body of the function or script. If you use 
both a syntax comment and a 
.PARAMETER
tag, the description associated with the 
.PARAMETER
tag is used, and the syntax comment is ignored.
Table 8.2 Tags that can be used in doc comments
Tag name
Tag content
.SYNOPSIS  
A brief description of the function or script. This tag can be 
used only once in each help topic.
.DESCRIPTION
A detailed description of the function or script.
.PARAMETER 
The description of a parameter.
.EXAMPLE
An example showing how to use a command.
.INPUTS
The type of object that can be piped into a command.
.OUTPUTS
The types of objects that the command returns.
.NOTES
Additional information about the function or script.
.LINK
The name of a related topic.
.COMPONENT
The technology or feature that the command is 
associated with.
.ROLE
The user role for this command.
.FUNCTIONALITY
The intended use of the function.
.FORWARDHELPTARGETNAME
Redirects to the help topic for the specified command.
.FORWARDHELPCATEGORY  
Specifies the help category of the item in the 
.FORWARDHELPTARGETNAME tag.
.REMOTEHELPRUNSPACE
Specifies the name of a variable containing the PSSession to 
use when looking up help for this function. This keyword is 
used by the Export-PSSession cmdlet to find the Help top-
ics for the exported commands. (See section 12.4.2.)
.EXTERNALHELP
Specifies the path to an external help file for the command.
Documents you may be interested
Documents you may be interested