Windows "Monad" Shell Beta 3 Drop (for .NET Framework 2.0 RTM) Release Notes

Copyright (c)2006 Microsoft Corporation. All rights reserved.

THIS INFORMATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A PARTICULAR PURPOSE.

The "Getting Started Guide" is now available with the Windows "Monad" Shell Beta 3 Documentation Pack on http://www.microsoft.com/downloads/details.aspx?FamilyId=6387C46B-4753-4EAF-8D8B-368074F39CCC&displaylang=en. This guide answers your basic questions about Monad and helps you get started with Monad.

# Changes from Windows "Monad" Shell Beta 2 (for .NET Framework 2.0 Beta RC/RTM)

Although this release is essentially the same code base as the previous Beta 2 release (except moved to the RTM version of .NET Framework 2.0), a few changes were made:

"Single Shell" Changes:

This release incorporates the "Single Shell" changes to the Windows "Monad" Shell.

The user-visible operation of Monad at startup is the same, however Monad now groups cmdlets assemblies into "MshSnapins" and dynamically loads MshSnapins at startup based on registry settings. To learn more about the Monad MshSnapins simply type: get-help about_MshSnapins. This help topic also talks about how to create and save console files.

Monad added cmdlets to control MshSnapins:

add-mshsnapin [-Name] String[] [-PassThru]

get-mshsnapin [[-Name] String[]] [-Registered]

remove-mshsnapin [-Name] String[] [-PassThru]

export-Console [[-Name] String] [-Force]

More details are available by running get-help on each one of these cmdlets.

Note: the new MshSnapins cmdlets are not available in a custom shell.

To learn more about how to create a MshSnapin, refer to the GettingStarted.rtf documentation and look up: Appendix D - Creating a SnapIn.

Literal numbers Cmdlet parameters:

Cmdlet parameters that are literal numbers will now get treated as numbers, whereas previously they used to be treated as strings. This may affect a script if the type of the parameter can be converted from a string but not from an integer. The user fix is to enclose the literal number in quotes. This change was in the earlier Monad Beta 2 but was not well communicated before.

The remaining notes are unchanged from the ones included with the prior Windows "Monad" Shell Beta 2 (for .NET Framework 2.0 Beta 2) release.

MAML Cmdlet help schema

Cmdlet help now adhere to the Microsoft MAML schema. All Cmdlet help content are in the *help.xml files in the Monad application folder under the correct culture folder:

> System.Management.Automation.Commands.Management.dll-Help.xml
> System.Management.Automation.Commands.Utility.dll-Help.xml
> System.Management.Automation.ConsoleHost.dll-Help.xml
> System.Management.Automation.dll-Help.xml
> System.Management.Automation.Security.dll-Help.xml

New add-member Cmdlet

We have introduced a new add-member cmdlet. To learn more about this Cmdlet, please check its usage by simply typing get-help add-member.

Monad assemblies are now NGEN'ed/GAC'ed

All Monad assemblies are installed using the Native Image Generator Ngen.exe and are installed in the Global Assembly Cash folder "GAC" by the Monad MSI installer. This allows the assemblies to load and execute faster, because it restores code and data structures from the native image cache rather than generating them dynamically.

Preference variables interaction changes

The effective settings which govern the behavior of ShouldProcess, ShouldContinue etc. emerges from the following:
- Command-line options: -WhatIf, -Confirm, -ErrorAction, -Debug, -Verbose
- Preference variables: $WhatIfPreference, $ConfirmPreference, $ErrorActionPreference, $DebugPreference, $VerbosePreference, $WarningPreference, $ProgressPreference

> The following are the algorithms for determining the effective setting. In priority order:
> WhatIf (true/false)
> -WhatIf (or –WhatIf:$false)
> $WhatIfPreference
> default: false
> Confirm (ActionPreference)
> -Confirm:$true => Inquire
> -Debug –Confirm:$false => Continue
> -Debug => Inquire
> -Confirm:$false => SilentlyContinue
> $ConfirmPreference
> default: SilentlyContinue
> ErrorAction (ActionPreference) (note that –ErrorAction is of type ActionPreference)
> -ErrorAction <preferencesetting> => <preferencesetting>
> -Debug => Inquire
> $ErrorActionPreference
> default: Continue
> Debug (ActionPreference)
> -Debug:$true => Inquire
> -Debug:$false => SilentlyContinue
> $DebugPreference
> default: SilentlyContinue
> Verbose (ActionPreference)
> -Verbose:$true => Continue
> -Verbose:$false => SilentlyContinue
> -Debug => Inquire
> $VerbosePreference
> default: SilentlyContinue
> Warning (ActionPreference) (note that there is no –Warning flag)
> -Debug => Inquire
> -Verbose => Continue
> $WarningPreference
> default: Continue
> Progress (ActionPreference) (note that there is no –Progress flag)
> $ProgressPreference
> default: Continue

Monad refactoring work:

In this release, the Cmdlet base class has been factored into two separate classes. If your cmdlets do not require any of the Monad engine core services (access to session state or providers) or use any of the engine intrinsic APIs, then you should continue to derive from Cmdlet. If you do require any of these services, then you should change your code to derive from MshCmdlet. In migrating to this new release, the best approach is to compile any existing cmdlets while still deriving from Cmdlet and only change the derivation for those cmdlets that have errors.
This change was made to reduce unnecessary dependencies on Monad core data structures for cmdlets that do not require those services. A positive consequence of this change is that if your cmdlets which derive only from Cmdlet can be directly invoked as standalone objects. For example, the get-process cmdlet only derives from Cmdlet and can therefore be used directly as shown in the following code:

> using System;
> using System.Collections;
> using System.Diagnostics;
> using System.Management.Automation;
> using System.Management.Automation.Commands;
> public class process

> {
> public static void Main()
> {
> GetProcessCommand g = new GetProcessCommand();
> g.ProcessName = new string[] {"[a-t]*"};
> foreach (Process p in g.Invoke<Process>())
> {
> System.Console.WriteLine(p.ProcessName);
> }
> }
> }

IMPORTANT NOTE: As always, our developer guidance is to develop your service as a proper API, then write cmdlets to surface that API to Monad. It is strongly recommended that little or no business logic be contained in the cmdlet code itself. Although this refactoring does allow cmdlets to be used directly as an API, it should not be construed as a replacement for proper API design
Misc. bug fixes
- Match-string: match-string -list used to write the match object before closing the file which used to cause an exception. This issue is now fixed. The following example should now work as expected:

> ls -rec -filter *.cs | match-string "cmdlet" | foreach { (cat $_) -replace "cmdlet","MshCmdlet" > $_ }

- Constants expressions after a variable were not being handled properly. The following example describes the new fixed behavior:

> MSH:\> $a = "this is a test"
> MSH:\> 80 - 8 - $a.length
> 58

- Credential parameter of remove-item is now correctly passed to the provider.

- write-progress now uses "ooo.." instead of "%%%"

- We improved the “type finding” by looking in the loaded assemblies instead of using the overload of Activator.CreateInstance that takes an assembly name. With this fix SimpleGenericsTypeConverter was created so that conversions like String to Microsoft.Exchange.Data.Unlimited`1[Microsoft.Exchange.Data.ByteQuantifiedSize] should work. Before this fix we failed to find Microsoft.Exchange.Data.SimpleGenericsTypeConverter (which was in a loaded assembly) and got an exception that was unhandled.

- Pipeline input fails to bind to pipeline enabled parameter:

> Create a cmdlet that has 2 parameter sets with 3 parameters.
> One parameter must take pipeline input
> One parameter should take provider input: MshPath
> One parameter must be shared or used in a parameter set with each of the first two parameters.
> Run the cmdlet with the shared parameter and pipeline input.
> RESULT:
> The pipeline input parameter fails to bind

Changes from Windows "Monad" Shell Beta 2 (for .NET Framework 2.0 Beta 2)

MSH execution policy changes

Monad's ExecutionPolicy is now configured to "Restricted" by default. This is a new value for ExecutionPolicy. In Restricted mode, scripts (.msh files) cannot be run and .mshxml files (types.mshxml and *.format.mshxml files) can only be run if they are signed by a trusted publisher (.mshxml files are treated the same as they are by the "AllSigned" policy). For msh.exe, this value is controlled via the registry setting "HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\MSH\1\ShellIds\Microsoft.Management.Automation.msh\ExecutionPolicy". The earlier Beta 2 release defaulted to an ExecutionPolicy of "RemoteSigned".

For other shells, the ExecutionPolicy is controlled via the registry setting "HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\MSH\1\ShellIds\<YourShellId>\ExecutionPolicy" where "<YourShellId>" can be obtained from the $shellid variable inside the shell.

When Monad first starts up it may ask a question "Do you want to run software from this untrusted publisher?" for the file "types.mshxml", published by Microsoft. You can choose to not load the file, but the file (and the *.format.mshxml files, which Monad will also prompt for if you do not select [A] for "Always run" for types.mshxml) controls the display and formatting of Monad and the experience in Monad will be degraded if it is not loaded. To avoid this prompt in the future, either select [A] for "Always run", or change the ExecutionPolicy from "Restricted" to "RemoteSigned".

The error text for certain execution errors references the "about_signing" help file. Simply type get-help about-siging to learn more about the new changes in Monad's ExecutionPolicy.

If you see an error at startup "The file "C:\Documents and Settings\All users\Documents\msh\profile.msh cannot be loaded. The execution of scripts is disabled on this machine" then either change the ExecutionPolicy from "Restricted" to "RemoteSigned", or sign the files using the set-authenticodesignature cmdlet (the error message is misleading; execution of .mshxml files is not entirely disabled when ExecutionPolicy is "Restricted", but they must be signed by a trusted publisher). The "about_signing" help file has more details. You can also delete the file; in the initial configuration, the profile.msh file does not add any functionality to Monad.

Profile.msh possible errors:

If you load the profile.msh file, and you have previously installed an earlier version of Monad, then on startup you may see a series of errors like:
set-alias : The AllScope option cannot be removed from the alias 'cat'.
At C:\Documents and Settings\All Users\Documents\msh\profile.msh:9 char:10
+ set-alias <<<< cat get-content
To fix this, either delete the file named ("C:\Documents and Settings\All Users\Documents\msh\profile.msh" in this example), or remove all the "set-alias" lines from it. Aliases defined in profile.msh in earlier versions of Monad are now defined internally by Monad before the profile is run, therefore the definitions in profile.msh generate an error attempting to redefine the alias.

# Known Issues with Monad Beta 2

MSH crashes while get-content –wait is running on a file that is updated frequently.

UTF7 file encoding is not supported.

Set-item on an existing alias returns an error instead of writing a new value if –option ReadOnly is specified. Set-alias should be used instead.

Regardless of the file extension, the following reserved device names should not be used as the name of a file. If used, unpredictable behavior and data loss may occur.

`CON, PRN, AUX, NUL, COM1, COM2, COM3, COM4, COM5, COM6, COM7, COM8, COM9, LPT1, LPT2, LPT3, LPT4, LPT5, LPT6, LPT7, LPT8, LPT9`

Help content for write-warning and script-signing are missing.

Help content for new-object is incorrect.

# Important Changes in Monad Beta 2

COM interop feature has been added in this release. Documentation on how to use this feature is included in the "Getting Started Guide."

The concept of separate shells has been introduced in this version of MSH. If you are developing Cmdlets, review the information about Shells in the "Getting Started Guide."

When you run setup, it will automatically register an MSHSIP.dll to support script signing. To learn how to sign a script type:

`MSH> Set-AuthenticodeSignature -?`

and follow the instructions.

The following cmdlets have been added:

`compare-object, convert-HTML, export-clixml, import-clixml, start-transcript, stop-transcript, update-FormatData, update-typeData, write-warning`

Script block delegates feature is enabled in this release. However, currently it only works when the delegates are called on the same thread.

# Changes from the Beta 1 release

A system-wide profile is installed at "All Users\Documents\MSH\profile.msh". User specific profile should go in at "users\My Document\MSH\profile.msh"

The registry entry for Monad now has shellId - `HKLM:\SOFTWARE\Microsoft\msh\1\ShellIds`

The format.mshxml file allows the user to define what properties will be displayed and in what format for any type. Setup will install a read only format.mshxml file. You can add additional format data in a separate file with .mshxml extension for your formatting requirements. Documentation on how to use this file is included in the "Getting Started Guide."

The types.mshxml file allows the static extension of types with added properties (which can be used by format.mshxml). Setup will install a read only types.mshxml file. You can add additional types data in a separate file with .mshxml extension for your formatting requirements. Documentation on how to use this file is included in the "Getting Started Guide."

Now there are 3 execution policy - AllSigned, RemoteSigned, Unrestricted. The default execution policy is RemoteSigned. For more details on execution policy, refer to "Getting Started Guide."