NGWS SDK Tools

The NGWS SDK contains a number of tools that were designed to make it easier for you to create, deploy, and manage applications. This section contains detailed information about the tools.

Tool | Description
Assembly Generation Utility (al.exe) | Accepts as input one or more files that are either MSIL format or resource files and outputs a file with an assembly manifest.
Assembly Registration Tool (RegAsm.exe) | Enables classic COM clients to call managed classes. RegAsm reads the metadata within an assembly, then adds the necessary entries to the registry so classic COM clients can create the managed classes transparently.
Services Registration Tool (RegSvcs.exe) | Adds managed classes to Windows 2000 Component Services by performing several tasks within a single utility. These tasks include loading and registering the assembly, and generating, registering, and installing the type library into an existing COM+ 1.0 application.
Assembly Cache Viewer (shfusion.dll) | Windows shell extension for viewing and manipulating the contents of the global assembly cache using the Windows Explorer.
Isolated Storage Utility (storeadm.exe) | Used to manage isolated storage for the currently logged in user.
Type Library Exporter (TlbExp.exe) | Using a managed assembly as input, generates a type library containing COM definitions of the public types defined in that assembly.
Type Library Importer (Tlbimp.exe) | Converts the type definitions found within a COM type library into equivalent definition in managed metadata format.
Web Service Utility (WebServiceUtil.exe) | Installs and uninstalls managed code Web Services.
NGWS Runtime XML Schema Definition Tool (xsd.exe) | Used for working with XML Schemas that follow the XML Schema Definition (XSD) language proposed by the W3C.
Win Forms ActiveX Control Importer (aximp.exe) | Using an ActiveX control's type library as input, generates a wrapper control that allows the ActiveX control to be hosted by a Win Forms form.
License Compiler (lc.exe) | Using text files containing licensing information as input, produces a binary .licenses file that can be embedded in a managed binary executable.
Resource File Generator Utility (ResGen.exe) | Reads text files containing name/value pairs and produces a managed binary .resources file.
ResX Resource Compiler (ResXToResources.exe) | Using .ResX (XML based resource format) files as input, produces a managed binary .resources file that can be embedded in a managed binary executable.
Win Forms Designer Test Container (windes.exe) | Used for testing the design time behaviour of Win Forms controls.
Code Access Security Policy Utility (caspol.exe) | Used to examine and modify machine and user code access security policies.
Software Publisher Certificate Test Utility (cert2spc.exe) | Creates, for test purposes only, a Software Publisher's Certificate (SPC) from one or more X.509 certificates.
Certificate Manager Utility (certmgr.exe) | Use to manage certificates, certificate trust lists (CTLs), and certificate revocation lists (CRLs).
Certificate Verification Utility (chktrust.exe) | Checks the validity of a signed file.
Certificate Creation Utility (makecert.exe) | Creates, for test purposes only, a Software Publisher's Certificate (SPC) from one or more X.509 certificates.
Permissions View Utility (permview.exe) | Use to view the code requests in an assembly.
Secutil Utility (SecUtil.exe) | Extracts Strong Name public key information or Authenticode™ publisher certificates from an assembly, in a format that can be incorporated directly into code.
Set Registry Utility (setreg.exe) | Changes registry settings related to test certificates.
File Signing Utility (signcode.exe) | Signs a PE file with requested permissions to give developers more detailed control over the security restrictions placed on their component.
Strong Name Utility (Sn.exe) | Creates and verifies assemblies with strong names.
NGWS Runtime Debugger (cordbg.exe) | A command-line utility that can help tools vendors and application developers find and fix bugs in programs that target the NGWS runtime.
NGWS Runtime IL Assembler (ilasm.exe) | Using IL as input, generates a PE file containing the IL and the required metadata. The resulting executable can be run to determine whether the IL performs as expected.
NGWS IL Disassembler (ildasm.exe) | Used to disassemble and inspect the IL code in a PE file.
Jit Manager Utility (jitman.exe) | Controls various options in the NGWS Runtime, related primarily to JIT compilation and garbage collection.
PEVerify Utility (peverify.exe) | Assists in validating the type safety of code prior to release. Also assists in generating IL, and in determining if IL code and associated metadata meets type safety verification requirements.
Win Forms Class Viewer (wincv.exe) | Finds the managed classes matching a specified search pattern, then uses the reflection API to display information about those classes.

© 2000 Microsoft Corporation. All rights reserved.


Assembly Generation Utility (al.exe)

al.exe takes as its input one or more files that are either in MSIL format or are resource files and outputs a file with an assembly manifest.

All Visual Studio compilers produce assemblies. However, if you have one or more modules (metadata without a manifest) you can use al.exe to create an assembly, although, the manifest will be in a separate file.

Syntax

al file[,targetfile]
   /embedresource:file[,name[,Y | N]]
   /linkresource:file[,name[,targetfile]
   options

where:

file[,targetfile]
An MSIL file that does not contain an assembly manifest. targetfile, lets you specify a path and filename into which al.exe will copy file and then begin the compilation.
/embedresource:file[,name[,Y | N]]
Embeds the resource specified by file in the image containing the assembly manifest; the contents of file are copied into the PE image.

name is an internal ID for the resource. By specifying Y, you allow the resource to be visible to other assemblies. The default is N, not visible to other assemblies.

If the only files passed to al.exe are resource files, the output file is a satellite resource assembly.

/linkresource:file[,name[,targetfile][,Y | N]]
Links a resource file to the assembly. The file reference is part of the assembly; the file is not copied.

name is an internal ID for the resource. targetfile, lets you specify a path and filename into which al.exe will copy file and then begin the compilation. By specifying Y, you allow the resource to be visible to other assemblies. The default is N, not visible to other assemblies.

If the only files passed to al.exe are resource files, the output file is a satellite resource assembly.

options
See the following table of al.exe options.
al.exe Option | Description
/algid:id Specifies an algorithm to use to hash all files in a multifile assembly, other than the file containing the assembly manifest. By default, CALG_SHA1 is used. See wincrypt.h for other predefined algorithms.

The hash values are stored in the file table of the assembly manifest. At installation and load time, the files will be checked against their hashes.

This option can also be specified as a custom attribute (System.Runtime.CompilerServices.AssemblyAlgIDAttribute) in the source code for any MSIL module.
/baseaddress:addr Specifies the address at which a DLL will be loaded on the user's computer at run time. If an application loads several DLLs, the application can load faster if you specify the base address of DLLs rather than let the operating system relocate the DLLs in the process space.

The short form of this option is /base:addr.
/bugreport:filename | Create a file (filename) that contains information that makes it easy to report a bug.
/company:text Specifies a string for the Company field in the assembly. Place the string in double quotation marks if text contains a space. This string is a custom attribute on the assembly and is available for viewing with Reflection.

If /win32res is not specified, text will appear in Windows Explorer as the Company property for the file. If /win32res is specified, the company information in the specified resource file is what will display as the Company property in Windows Explorer.

This option can also be specified as a custom attribute (System.Reflection.AssemblyCompanyAttribute) in the source code for any MSIL module.

The short form of this option is /comp:"text".
/configuration:text Specifies a string for the Configuration field in the assembly. Place the string in double quotation marks if text contains a space. This string is a custom attribute on the assembly and is available for viewing with Reflection.

This option can also be specified as a custom attribute (System.Reflection.AssemblyConfigurationAttribute) in the source code for any MSIL module.

The short form of this option is /config:text.
/copyright:text Specifies a string for the Copyright field in the assembly. Place the string in double quotation marks if text contains a space. This string is a custom attribute on the assembly and is available for viewing with Reflection.

If /win32res is not specified, text will appear in Windows Explorer as the Copyright property for the file. If /win32res is specified, the company information in the specified resource file is what will display as the Copyright property in Windows Explorer.

This option can also be specified as a custom attribute (System.Reflection.AssemblyCopyrightAttribute) in the source code for any MSIL module.

The short form of this option is /copy:text.
/culture:text Specifies the culture string to associate with the assembly. Valid values for cultures are those defined by RFC1766.

Place the string in double quotation marks if text contains a space. There is no default culture string. This string is available for viewing with Reflection.

For information on valid text strings, see CultureInfo class.

This option can also be specified as a custom attribute (System.Runtime.CompilerServices.AssemblyCultureAttribute) in the source code for any MSIL module.

The short form of this option is /c:text.
/delaysign[+|-] Specifies whether the assembly will be fully or partially signed. Use /delaysign- if you want a fully signed assembly, which contains both public and private keys. Use /delaysign+ if you only want the public key placed in the assembly.

The default is /delaysign-.

/delaysign has no effect unless used with /keyfile or /keyname.

If you use /delaysign+, it will, for example, allow a tester to put the assembly into the global cache. After testing, you can then fully sign the assembly (place the private key into the assembly).

This option can also be specified as a custom attribute (System.Runtime.CompilerServices.AssemblyDelaySignAttribute) in the source code for any MSIL module.

The short form of this option is /delay[+|-].
/description:text Specifies a string for the Description field in the assembly. Place the string in double quotation marks if text contains a space. This string is a custom attribute on the assembly and is available for viewing with Reflection.

If /win32res is not specified, text will appear in Windows Explorer as the Description property for the file. If /win32res is specified, the company information in the specified resource file is what will display as the Description property in Windows Explorer.

This option can also be specified as a custom attribute (System.Reflection.AssemblyDescriptionAttribute) in the source code for any MSIL module.

The short form of this option is /descr:text.
/flags:flags (This feature is not implemented for the PDC release.)

Specifies a value for the Flags field in the assembly. Possible values for flags are:

0x0000
The assembly is side-by-side compatible.
0x0010
The assembly cannot execute with other versions if they are executing in the same application domain.
0x0020
The assembly cannot execute with other versions if they are executing in the same process.
0x0030
The assembly cannot execute with other versions if they are executing on the same computer.

This option can also be specified as a custom attribute (System.Runtime.CompilerServices.AssemblyFlagsAttribute) in the source code for any MSIL module.
/fullpaths | Causes al.exe to specify the absolute path for any files that are reported in an error message.
/help Displays the available command line options.

The short form of this option is /?.
/install[:filename] Installs the assembly into the global assembly cache. Use /install if you will not install the application with Microsoft Installer (MSI).

If you are not using MSI, you can use /install to test a program.

To use /install, /keyfile or /keyname must also be specified. If /out is also specified, do not specify filename.

The short form of this option is /i[:filename].
/keyfile:filename Specifies a file (filename) containing a key pair to make a shareable component. The compiler inserts the public key into the assembly manifest and then signs the final assembly with the private key. Use sn -k file (at the command line) to generate a key file. Then, use sn -i to install the key pair into the key container

If you are delay signing, this file will likely just have the public key and not the private key.

The key information appears in the Originator Blob field of the assembly.

This option can also be specified as a custom attribute (System.Runtime.CompilerServices.AssemblyKeyFileAttribute) in the source code for any MSIL module.

The short form of this option is /keyf:filename.
/keyname:text Specifies a container containing a key pair to make a shareable component by inserting a public key into the assembly manifest and then signs the final assembly with the private key. Use sn -k file (at the command line) to generate a key file.

Place the string in double quotation marks if text contains a space.

The key information appears in the Originator Blob field of the assembly.

Place text in double quotation marks (" ") if there is an embedded space.

This option can also be specified as a custom attribute (System.Runtime.CompilerServices.AssemblyKeyNameAttribute) in the source code for any MSIL module.

The short form of this option is /keyn:text.
/main:method | Specifies the fully-qualified name (class.method) of the method to use as an entry point when converting a module to an executable file.
/nologo | Suppresses the banner.
/os:os.maj.min Specifies an operating system and its major version and minor version. This information could represent an operating system on which the file is supported. Currently, the runtime does not use this information.

It is possible to specify more than one /os option in a single compilation. This could indicate that more than one operating system supports the file.

The operating system, major version, and minor version should be specified in hexadecimal. Values for operating system should come from the // dwPlatformId defines: section in winnt.h.

This option can also be specified as a custom attribute (System.Runtime.CompilerServices.AssemblyOperatingSystemAttribute) in the source code for any MSIL module.
/out:filename | Specifies the name of the file output by al.exe.
/processor:proc Specifies the processor(s) supporting this file. proc is the hexadecimal value for a processor. See the PROCESSOR_* entries in winnt.h for a list of processor types.

Currently, the runtime does not use this information.

It is possible to specify more than one /processor option in a single compilation. This could indicate that more than one processor supports the file.

This option can also be specified as a custom attribute (System.Runtime.CompilerServices.AssemblyProcessorAttribute) in the source code for any MSIL module.

The short form of this option is /proc: proc.
/product:text Specifies a string for the Product field in the assembly. Place the string in double quotation marks if text contains a space. This string is a custom attribute on the assembly and is available for viewing with Reflection.

If /win32res is not specified, text will appear in Windows Explorer as the Product property for the file. If /win32res is specified, the company information in the specified resource file is what will display as the Product property in Windows Explorer.

This option can also be specified as a custom attribute (System.Reflection.AssemblyProductAttribute) in the source code for any MSIL module.

The short form of this option is /prod:text.
/productversion:text Specifies a string for the Product Version field in the assembly. Place the string in double quotation marks if text contains a space. This string is a custom attribute on the assembly and is available for viewing with Reflection.

If /productversion is not specified, /version:version will appear in Windows Explorer as the Product Version property for the file.

This option can also be specified as a custom attribute (System.Reflection.AssemblyInformationalVersionAttribute) in the source code for any MSIL module.

The short form of this option is /productv:text.
/type:lib|exe|win Specifies the file format of the output file: lib (code library), exe (console application), or win (Windows application). The default is lib.

The short form of this option is /t:lib|exe|win.
/title:text Specifies a string for the Title field in the assembly. Place the string in double quotation marks if text contains a space. This string is a custom attribute on the assembly and is available for viewing with Reflection.

If /win32res is not specified, text will appear in Windows Explorer as the Title property for the file. If /win32res is specified, the company information in the specified resource file is what will display as the Title property in Windows Explorer.

This option can also be specified as a custom attribute (System.Reflection.AssemblyTitleAttribute) in the source code for any MSIL module.
/trademark:text Specifies a string for the Trademark field in the assembly. Place the string in double quotation marks if text contains a space. This string is a custom attribute on the assembly and is available for viewing with Reflection.

If /win32res is not specified, text will appear in Windows Explorer as the Trademark property for the file. If /win32res is specified, the company information in the specified resource file is what will display as the Trademark property in Windows Explorer.

This option can also be specified as a custom attribute (System.Reflection.AssemblyTrademarkAttribute) in the source code for any MSIL module.

The short form of this option is /trade:text.
/version:version Specifies version information for this assembly. The format of the version string is major.minor.revision.build. The default value is 0.

If you do specify /version, you have to at least specify major. If you specify major and minor, you can specify an asterisk (*)for revision. This will cause revision to be equal to the number of days since January 1, 2000, local time and for build to be equal to the number of seconds since midnight, local time, modulo 2.

If you specify major, minor, and revision, you can specify an asterisk for build. This will cause build to be equal to the number of seconds since midnight, local time, modulo 2.

This option can also be specified as a custom attribute (System.Runtime.CompilerServices.AssemblyVersionAttribute) in the source code for any MSIL module.

The short form of this option is /v:version.
/win32icon:filename | Inserts a .ico file, which gives the output file the desired appearance in the Windows Explorer, into the assembly.
/win32res:filename | Inserts a Win32 resource (.res file) in the output file. A Win32 resource file can be created with the Resource Compiler. The Resource Compiler is invoked when you compile a Visual C++ program; a .res file is created from the .rc file.
@filename Specifies a response file. A response file contains al.exe commands.

Commands in filename can appear one per line or on the same line separated by one or more spaces.

Example

Create an executable file t2a.exe with an assembly from the t2.dll module. The entry point is the Main method in MyClass.

al t2.dll /type:exe /out:t2a.exe /main:MyClass.Main


alink Utility Errors and Warnings

The following are the errors that al.exe can generate.

Error Description
al1001 Internal compiler error

Try to determine if al.exe is failing because of its inability to parse unexpected syntax. Then, contact Microsoft Technical Support.
al1002 Out of memory

al.exe ran out of memory and halted. Increase the amount of available memory.
al1003 Compiler option 'option' must be followed by an argument

al.exe expected an argument to be passed to a command-line option. For example, if you specify /algid:, you have to pass an ID for an algorithm.
al1004 Unexpected NGWS runtime initialization error -- 'reason'

al.exe reported an error with the Visual Studio or NGWS installation.
al1005 File 'file' too big to open

All files opened by al.exe must be smaller than 4 GB.
al1006 Response file 'file' was already included

The same response file was specified (@file) more than once on the command line. The response file can only be included once.
al1007 Error opening response file 'file' -- 'reason'

al.exe could not open the specified response file for the specified reason.
al1008 Missing file specification for 'option' command-line option

al.exe expected a file to be passed to a command-line option. For example, if you specify the /out option, then you have to specify a file.
al1009 Can't open 'file' for writing

al.exe was unable to write to a file, such as the output assembly file. The disk may be full, the file may be read-only, or you may not have access rights to the file.
al1010 Command-line syntax error: Missing ':text' for 'option' option

al.exe expected an argument to be passed to a command-line option. For example, if you specify the /title option, you have to pass a string.
al1011 File 'file' is an executable file and cannot be opened as a text file

A binary file was specified where a text file was expected. For example, this error will occur if a binary file is passed on the command line as a response file.
al1012 'value' is not a valid setting for option 'option'

A value was passed to a command-line option that was not expected. For example, this error will occur if you specify an invalid value to the /type option.
al1013 Unrecognized command-line option: 'option'

An invalid command-line option was specified.
al1014 Unexpected initialization error -- 'reason'

al.exe detected a COM initialization failure. This might be caused by a lack of memory, but a more likely cause is your system DLLs. In this case, you would get a similar error when you ran any OLE/COM-aware program, such as Visual Studio. Reinstall your operating system.
al1015 "Unable to find messages file 'alinkui.dll'"

al.exe requires alinkui.dll. Make sure that this file is on your path. If necessary, copy it from the product CD.
al1016 No input files were specified

al.exe requires as input one or more files that do not have assembly information.
al1017 No target filename was specified

A command-line option was specified but no file was specified. For example, this error will occur if you specify /keyname:.
al1018 Required file 'file' could not be loaded

Certain DLLs cannot be loaded. Reinstall Visual Studio or NGWS.
al1019 Metadata failure while creating assembly -- 'reason'

Generation of the assembly was interrupted for the specified reason. For example, this error will occur if you specify a file that is not found to the /win32res option.
al1020 Ignoring included assembly 'file'

An input file to al.exe had an assembly. al.exe takes as input files that do not have assemblies.
al1021 'setting' : overriding previous setting

A module (MSIL file format but no assembly) had a value for a particular setting, perhaps via custom attributes, and that value was overridden with a value passed via an al.exe command-line option.
al1022 Error reading embedded resource 'file' -- 'reason'

al.exe could not read the file passed to the /embedresource option for the specified reason.
al1023 Error embedding resource 'file' -- 'reason'

The operating system could not embed the resource file in the assembly. See reason for the specific problem.
al1024 File 'file' is not in the same directory as the assembly file 'assembly file'

The input files to an assembly have to be in the same directory in which the assembly will be created, or a subdirectory of that directory.
al1025 ComType record 'record' points to an invalid file record 'record'

Metadata in the input module is invalid. The tool that produced the module needs to be fixed.
al1026 The version specified 'version' is invalid

See information on the /version option for valid formats.
al1027 The operating system specified 'os' is invalid

See information on the /os option for valid formats.
al1028 Key file 'file' is missing the private key needed for signing

A key file that only contained the public key was passed to the /keyfile option. The following command line generates a file with a public and private key: sn -k keypair.snk.
al1029 The key container name 'container' does not exist

The value passed to the /keyname option is not a valid container. Use the sn.exe utility to create a container.
al1030 The cryptographic service is not installed properly or does not have a suitable key provider

You may need to either reinstall your operating system or install some cryptographic utility that was used in the creation of the key.
al1031 Error reading icon 'file' -- 'reason'

al.exe could not read the file that was passed to the /win32icon option.
al1032 Error generating resources for 'file' -- 'reason'

Your compilation either used the /win32icon option or did not use the /win32res option, which causes al.exe to generate a file that contains resource information. However, al.exe was unable to create the file due to insufficient disk space or some other error.

If you are unable to resolve the file-generation problem, you could use /win32res, which does not generate a file that contains resource information.
al1033 Assembly custom attribute 'attribute' was specified multiple times with different values

Different values were passed to two custom attributes in source modules that are input to al.exe.
al1034 Assembly 'file' cannot be copied or renamed.

While using the al.exe syntax that allows you to both specify an input file and copy it, a name conflict arose such that the compiler could not continue. For example, this error will occur if you specify something like input.dll,somename.dll /out:somename.dll.

al1035 Libraries cannot have a main method specified

When using the /type:lib option, which is the default, you cannot also specify the /main option.
al1036 Main method required for console and windows apps

When using the /type:exe or /type:win option, you must also specify the /main option.
al1037 Unable to find main method 'main'

al.exe was unable to find a Main method at the location specified by the /main option.
al1038 '/install' and '/out' cannot both specify a filename

If the /out option is specified, the assembly will be installed (/install) in the global cache with the name passed to /out.
al1039 Initialization of global assembly cache manager failed -- 'reason'

Reinstall Visual Studio or NGWS.
al1040 Failed to install assembly into cache -- 'reason'

Only signed assemblies can be installed into the cache. If an assembly is not signed, and you specify the /install option, you will get this error. There are other reasons why installing into the cache might fail; see the Global Assembly Cache help topics for more information.
al1041 'method': main method does not have proper signature

A method was specified with the /main option, but that method either was not static, did not return int or void, or has invalid arguments.

al1042 'exe': EXEs cannot be added modules

An .exe that did not have an assembly was specified as an input file to al.exe. al.exe can only take .dll files as input files without assemblies.
al1043 Manifest filename 'name' cannot be the same as any modules

The name specified to the /out option cannot be the same as any of the files that are specified as input to al.exe.
al1044 Error reading key file 'file' -- 'reason'

An error occurred while opening or reading from a file specified with /keyfile or KeyFileAttribute.

See Also

© 2000 Microsoft Corporation. All rights reserved.


Win Forms ActiveX Control Importer (aximp.exe)

The ActiveX Control importer is responsible for converting the type definitions found within the COM type library for an ActiveX Control into a Win Forms Control.

Win Forms can only host Win Forms Controls - that is classes that are derived from System.WinForms.Control. In order to host an ActiveX Control on a form it must appear to be a Win Forms Control. Conversely an ActiveX Control expects to be hosted in an ActiveX Control Container.

In order to achieve hosting there is a base class System.WinForms.AxHost that derives from System.WinForms.RichControl. This control is a Win Forms control “on the outside” and an ActiveX Control Container “on the inside”.

In order to host the ActiveX Control you need to generate a “wrapper” control that derives from System.WinForms.AxHost. This generated control hosts the ActiveX Control and exposes its properties methods and events (PMEs) as PMEs of the generated control.

Conversions are done for an entire ActiveX Control type library at one time. You cannot use aximp to generate type information for a subset of the types defined within a single type library. The output of aximp is a set of binary files that contain the NGWS runtime metadata and control implementation for the types defined within the original type library. The generated files are named according to the following pattern:

NGWS runtime proxy for COM types: <progid>.dll

Win Forms proxy for ActiveX Control: <progid>WFC.dll

(where WFC signifies Win Forms Control)

You can examine these files with tools such as Ildasm.exe.

PDC Tech Preview Warning: If the name of the COM type library progid has the same name as the output proxy name – for instance SHDOCVW.DLL – then the original type library may be overwritten. Do not use aximp in the directory that contains your type library.

Syntax

aximp TlbFile

Example

The following example generates shdocvw.dll and shdocvwwfc.dll for the Web Browser control:

aximp c:\winnt\system32\shdocvw.dll

In C# you would use this code:

Namespace MyControls {
    using System;
    using System.WinForms;
    using SHDocVwWFC;
    public class MyControl: System.WinForms.Form {
        private System.ComponentModel.Container components;
        private SHDocVwWFC.AxWebBrowser AxWebBrowser1;

        public MyControl () : base() {
            InitializeComponent();
AxWebBrowser1.Offline = true ;
      }
…
      }
…
}

and compile it as follows:

csc /debug+ /r:System.DLL /r:System.WinForms.DLL  /r:Microsoft.Win32.InterOp.DLL /r:ShDocVwWFC.DLL /out:MDIBrowser.exe *.cs.c

See Also

NGWS Runtime IL Disassembler


Code Access Security Policy Utility (caspol.exe)

Summary of the security model as exposed through caspol

Security policy is designed as a hierarchical structure of code groups. Each code group has a membership condition that determines membership of some code to that code group. Also, associated with each code group is a named permission set that specifies the permissions the runtime allows code satisfying the membership condition to have. A code group hierarchy, along with its associated named permission sets, is used to define and maintain each level of security policy.

There are three policy levels: machine policy, user policy, and application domain policy. The set of permissions that an assembly receives is determined by the intersection of the permission sets allowed by these three policy levels. Unlike machine policy and user policy, application domain policy is optional and it is dynamically created. Because application domain policy is not stored statically, it cannot be modified directly by caspol.

For more information about security policy and how the runtime determines which permissions to grant to code, see Security Policy Management.

Referencing security objects

To facilitate references to code groups in a hierarchy, the command line -list function will show indented objects with labels (1, 1.1, 1.1.1, etc.) for reference purposes. Subsequent command line operations targeting code groups use these labels to refer to specific code groups.

Named permission sets are referenced by their name. The –list option will show the list of code groups followed by a list of named permission sets available in that policy.

Caspol users can switch between the user and machine policies using the –machine and –user options.

Default Behavior

By default all options of caspol refer to the runtime version caspol has been installed with.

If a user without admin rights calls caspol, by default all caspol options refer to the user level policy, unless –machine is used.

If an admin calls caspol, by default all caspol options refer to the machine’s policy, unless the admin uses –user.

Syntax

caspol
   [-machine]
   [-user]
   [-all]
   [-list]
   [-listgroups]
   [-listpset]
   [-addgroup parent_label mship pset_name ([-exclusive {on|off}][-
         levelfinal {on|off}])]
   [-chggroup label {mship | pset_name |[[ -exclusive{on|off}]| [-
   levelfinal {on|off}]]}]
   [-remgroup label]
   [-addpset { named_psfile | psfile pset_name} ]
   [-chgpset psfile pset_name]
   [-rempset pset_name]
   [-resolvegroup [-all] assembly_file]
   [-resolvegroup [-user] assembly_file]
   [-resolvegroup [-machine] assembly_file]
   [-resolveperm [-all] assembly_file]
   [-resolveperm [-user] assembly_file]
   [-resolveperm [-machine] assembly_file]
   [-security { on | off }]
   [-execution { on | off }]
   [-polchgprompt { on | off }]
   [-recover]
   [-reset]
   [-force]
   [-help]

Argument: -list

Description: Lists code groups and permission sets. The code group hierarchy and permission sets of machine policy, user policy, or all policy levels are shown. The general output format is:

Microsoft (R) COM+ CasPol [version]  - the policy manipulation tool
Copyright (c) Microsoft Corp 1999-1999. All rights reserved.
Security is [ON|OFF]
Execution Checking is [ON|OFF]
Policy Change Prompt is [ON|OFF]
Level = [Machine|User]
Code Groups:
1.  [(PickFirst)] MemberShipConditionName [– Value] : PermSetName
1.1  [(PickFirst)] MemberShipConditionName [– Value] : PermSetName
1.2  ……
1.2.1  …..
Named Permission Sets:
1. Permission Set:Pset_name,(Description)
<Pset Xml>
2. Permission Set:Pset name,(Description)
<Pset Xml>
…

Example:

Caspol –list
Microsoft (R) COM+ CASPol [version] - the policy manipulation tool
Copyright (c) Microsoft Corp 1999-1999. All rights reserved.
Security is ON
Execution Checking is [ON|OFF]
Policy Change Prompt is [ON|OFF]
Level = Machine
Code Groups:
1  All Code : Nothing
   1.1  Zone Internet: Internet
   1.2  Zone Intranet: Intranet_permission_set
        1.2.1  Site “www.microsoft.com” : Internet
Named Permission Sets:
1. Permission Set:Nothing,(grants no permissions)
<PermissionSet ….>
…
</PermissionSet>
2. Permission Set:Internet, (Permissions suitable for apps from the internet)
<PermissionSet….>
…
</PermissionSet>

Argument:-listgroups

Description: This option lists the code groups of one policy level or all policy levels.

Example:

Caspol –listgroups
Microsoft (R) COM+ Caspol [version] - the policy manipulation tool
Copyright (c) Microsoft Corp 1999-1999. All rights reserved.
Security is ON
Execution Checking is [ON|OFF]
Policy Change Prompt is [ON|OFF]
Level = Machine
Code Groups:
1  All Code : Nothing
   1.1  Zone Internet: Internet
   1.2  Zone Intranet: Intranet_permission_set
        1.2.1  Site “www.microsoft.com” : Internet

Argument: -listpset

Description: This option lists the permission set of one policy level or all policy levels.

Example:

Caspol –listpset
Microsoft (R) COM+ Caspol [version] - the policy manipulation tool
Copyright (c) Microsoft Corp 1999-1999. All rights reserved.
Security is ON
Execution Checking is [ON|OFF]
Policy Change Prompt is [ON|OFF]
Level = Machine
Named Permission Sets:
1. Permission Set:Nothing,(grants no permissions)
<PermissionSet ….>
…
</PermissionSet>
2. Permission Set:Internet, (Permissions suitable for apps from the internet)
<PermissionSet….>
…
</PermissionSet>

Argument: -machine

Description: This option forces all options following it to apply to the machine policy. Note: Users that are not administrators do not have sufficient rights to modify the machine policy, although they may view it. -machine is the default for administrators.

Example:

Caspol –machine –list
Microsoft (R) COM+ Caspol [version] - the policy manipulation tool
Copyright (c) Microsoft Corp 1999-1999. All rights reserved.
Security is ON
Execution Checking is [ON|OFF]
Policy Change Prompt is [ON|OFF]
Level = Machine
Code Groups
1. All Code : Execution
Permission Set:Execution,(grants execution permission to code)
<PermissionSet ….>
…
</PermissionSet>

Argument: -user

Description: This option forces all options that follow it to apply to the user policy of the user on whose behalf caspol is running. -user is the default for non-admin users of caspol.

Example:

Caspol –user –list

Argument: -all

Description: This option forces all options that follow it to apply to the machine and user policies. This option can be applied to only the -list, -listpset, -listgroups, -resolvegroups, and -resolveperm options.

Example:

Caspol -all -list

Argument: -addgroup parent_label mship pset_name [-exclusive {on|off}][-levelfinal {on|off}]

Description: This option is used to add a new code group to the code group hierarchy. Parent_label designates the label (viz. 1. or 1.1.) of the code group from which the new code group should hang as child code group. Mship defines the membership condition for the new code group (see table below). pset_name is the name of the permission set that is to be associated with the new code group. It is also possible to set a couple of exclusive flags (see below).

mship is defined in terms of one of the following options:

Argument | Description
-all | All Code group; all code is a member of this code group.
-pub { -cert cert_file_name | -file signed_file_name | -hex hex_string } | Software publisher denoted by certificate file, the signature on a file.
-strong {-file file_name} {name | -noname} {version | -noversion} | Strong name as designated by a file, name and version.
-zone zonename | Zone of origin of code. Zonename can be one of the following values: "MyComputer", "Intranet", "Trusted", "Internet", or "Untrusted".
-site website | Site of origin.
-hash hashAlg {-hex hashValue | -file assembly_file } | An assembly’s hash can be used as a code group membership condition. Either the hash value or the assembly file needs to be specified.
-appdir | If –appdir is specified as membership condition the URL evidence of code is compared with the AppDir evidence of that code. If both evidence values are the same, this membership condition succeeds.
-skipverif | This membership condition tests whether code requests to skip verification.
-urlURL | url of origin

When adding a new code group, it is also possible to set a couple of exclusive flags:

Argument | Description
-exclusive {on|off} | When this flag is set only the permission set of the added code group applies when some code fits the membership condition of the added code group.
-levelfinal {on|off} | When this flag is set (typically at the machine policy level) then no policy level below the level in which the added code group occurs is considered. For instance if this flag is set for some code group at the machine level and some code matches this code group’s membership condition, then the user level policy for this code is not calculated and applied.

Example:

Caspol  -machine –addgroup 1.  –zone Internet Execution

This command adds a child code group to the root of the machine policy code group hierarchy. The new code group has a zone membership with value Internet, and has the Execution Permission set associated with it.

Argument: -chggroup parent_label {mship |pset_name | [-exclusive {on|off}][-levelfinal {on|off}] }

Description: This option is used to change a code group’s membership condition, permission set or exclusive flags. Mship, pset_name, -exclusive and –levelfinal have the same purpose and syntax as defined for –addgroup.

Example:

Caspol –user –chggroup 1.2. Execution

The above command changes the permission set of the user policy code group with label 1.2. to the “Execution” permission set.

Caspol –chggroup 1.2.1. –zone Internet –exclusive on

This command changes the zone and group exclusive flag of the code group with label 1.2.1. at the default policy level (see Default Behavior). Zone is set to Internet and the –exclusive flag is switched on.

Argument: -remgroup label

Description: This option is used to remove code groups and their child code groups. If a code group at label has child code groups, all these child code groups will be removed as well.

Example:

Caspol –remgroup 1.1.

This removes the code group at 1.1. If this code group had any child code groups then those are deleted as well.

Argument: -addpset {named_psfile | psfile pset_name}

Description: This option is used to add a new named permission set The permission set needs to be pre-authored in XML and stored in an xml file. If the permission set name is not specified in the specified xml file, the permission set name needs to be explicitly specified in pset_name. If the name of the permission set is already contained in the xml file, pset_name does not need to be specified, but only named_psfile, which contains the permission set along with the permission set name.

Example:

Caspol  -user –addpset Mypset.xml Mypset

Adds the Mypset permission set to the user policy.

Argument:-chgpset psfile pset_name

Description: Changes a named permission set, the permission set will henceforth be defined in terms of the content of psfile. The psfile is a serialized permission set file in XML format.

Example:

Caspol –chgpset Mypset newpset.xml

Changes the permission set with name Mypset to the permission set contained in newpset.xml. Note that the current release does not support changing permission sets that are in use by the code group hierarchy.

Argument:-rempset pset_name

Description: The permission set with name pset_name is removed from a policy. As defined in the Default Behavior section, if no –user or –machine option is used then this option refers to the default policy level (user policy for non-admin users and machine policy for administrators).

Note: the permission set is only removed if it is not associated with any code group. Default permission sets cannot be removed.

Example:

Caspol –user –rempset Execution

Removes the permission set with name Execution from the user policy.

Caspol –rempset MyPset

Removes Mypset from the default policy level.

Argument: [-all | -machine | -user] -resolvegroup assembly_file

Description: With this option it is possible to discover which code groups a specific assembly (assembly_file) belongs to. By default this option applies only to one policy level. If all code groups of both the machine and user policy that the assembly belongs to should be shown, the –all option is used.

Example:

Caspol –machine –resolvegroup myassembly

This command shows all code groups of the machine policy that myassembly belongs to.

In general the output format for this option is:

Microsoft (R) COM+ Caspol [version] - the policy manipulation tool
Copyright (c) Microsoft Corp 1999-1999. All rights reserved.
Level = Machine
Code Groups:
1. MemberShipConditionName [– Value] : PermSetName [Intersection Merge]
1.1 MemberShipCondName [– Value] : PermSetName [Intersection Merge]
……

Argument: [-all | machine | user] -resolveperm assembly_file

Description: With this option it is possible to discover all the effective permissions that an assembly would be granted were it to run. By default this option only applies to one (the default) policy level. The –all option is used to indicate that the permissions applying to assembly_file should be calculated based both on the user and machine policy.

Example:

Caspol –all resolveperm testassembly

The effective permissions for testassembly are calculated based on the machine and user policy.

The general output format for this option is:

Microsoft (R) COM+ Caspol [version] - the policy manipulation tool
Copyright (c) Microsoft Corp 1999-1999. All rights reserved.
Resolving Permissions for Level = Machine
Grant=
<PermissionSet>
XML for individual permissions
</PermissionSet>

Argument: -security { on | off }

Description: This option turns code access security on or off.

Note:This option should be used with extreme caution.

Argument:-execution { on | off }

Description: This option turns on/off checking for "right to run" on code execution start-up.

Argument:-polchgprompt { on | off }

Description: This option enables or disables the prompt that is displayed whenever caspol is called using an option that would cause policy changes.

Argument:-recover

Description: Whenever a policy change is made, caspol stores the old policy in a backup file. If the policy from the backup file should be recovered, use –recover

Example:

Caspol –machine –recover

Recovers the most recently saved machine policy.

Argument:-reset

Description: This option turns a policy back to its default state. This is useful whenever a changed policy seems beyond repair and it is easier to start with the installation defaults. This option will also automatically persist the default policy to disk. (see Manually Editing the Security Configuration below.)

Example:

Caspol –user –reset

Resets the user policy to the installation default.

Argument:-force

Description: Caspol checks whether any policy changes would result in granting caspol itself insufficient permissions to run properly. If that is the case, the policy change is not saved and an error message is printed. If the caspol user wants to force caspol to admit policy changes even if that means that caspol may not run anymore, the –force option can be used. This option surpresses the “self-destruct” test and commits the policy change as dictated by the caspol user.

Example:

Caspol –force –user –chggroup 1 Nothing

Argument:-help

Description: Displays the help screen

Abbreviations

Most options have one to three character abbreviations that can be used in place of the full-length option name. Below is a table of valid abbreviations:

Option | Valid abbreviation
-all | -a
-machine | -m
-user | -u
-list | -l
-listgroups | -lg
-listpset | -lp
-addpset | -ap
-chgpset | -cp
-rempset | -rp
-remgroup | -rg
-chggroup | -cg
-addgroup | -ag
-resolvegroup | -rsg
-resolveperm | -rsp
-security | -s
-execution | -e
-help | -h (or -? or /?)
-polchgprompt | -pp
-recover | -r
-reset | -rs
-force | -f

Caspol’s self protection

The caspol utility needs policy to grant itself the equivalent of the Everything permission set in order to function. There is built-in protection to prevent the creation of policy that fails to give it the necessary permissions – if this happens caspol will notify the user that the requested policy change will break caspol. Such policy changes will be rejected unless –force is used.

Manually editing the security configuration files

We do not recommend editing the security configuration files manually. However, there may be scenarios in which this might become necessary (such as when an administrator wants to edit the security configuration for a particular user – this capability will become part of a not yet implemented security administrative tool).

Corresponding to the two policy levels supported by caspol, there are two security configuration files - one for the machine policy and one for a particular user’s policy.

The machine policy resides at :

Machine policy configuration
Windows 2000 | %WINDIR%\complus\vxx.xx\security.cfg
Windows NT | %WINDIR%\complus\vxx.xx\security.cfg
Windows 9x | %WINDIR%\complus\vxx.xx\security.cfg
User policy configuration
Windows 2000 | %USERPROFILE%\complus\vxx.xx\security.cfg
Windows NT | %USERPROFILE%\complus\vxx.xx\security.cfg
Windows 9x | %WINDIR%\username\complus\vxx.xx\security.cfg

These files are only created on disk when the caspol user changes the machine or user policy using caspol (otherwise the hardwired defaults are used). If the default security policy should be written to disk nevertheless then simply call –reset, which automatically persists the default policy to disk. This might be convenient when the default policy is used as a starting point for further hand–edits to the security policy.

See Also

Security Policy Management


Software Publisher Certificate Test Utility (Cert2spc.exe)

The Software Publisher Certificate test utility (Cert2spc.exe) creates a Software Publisher's Certificate (SPC) from one or more X.509 certificates. This utility, like the Makecert utility, is for test purposes only. A valid SPC is obtained from a Certification Authority (CA) such as VeriSign or Thawte.

Syntax

cert2spc cert1.cer cert2.cer … certN.cer outputSPCfile.spc
Argument | Description
certN.cer | Specifies the name of an X.509 certificate to include in the SPC file. You may include multiple entries separated by spaces.
outputSPCfile.spc | Specifies the name of the PKCS #7 object that will contain the specified X.509 certificates. The SPC file can be used as input to the signcode tool.

Examples

The following example creates an SPC from myCertificate.cer and places it in mySPCFile.spc.

cert2spc myCertificate.cer mySPCFile.spc

The following example creates an SPC from oneCertificate.cer and twoCertificate.cer and places it in mySPCFile.spc.

cert2spc oneCertificate.cer twoCertificate.cer mySPCFile.spc

See Also

Certificate Creation Utility (makecert.exe)


Certificate Manager Utility (certmgr.exe)

Certmgr (the Certificate Manager utility) manages certificates, certificate trust lists (CTLs), and certificate revocation lists (CRLs). It performs the following basic functions:

  • Displays certificates, CTLs, and CRLs to the console.
  • Adds certificates, CTLs, and CRLs, from one certificate store to another.
  • Deletes certificates, CTLs, and CRLs, from a certificate store.

Certmgr works with two kinds of certificate stores: StoreFile and system store. It is not necessary to specify the type of store file; certmgr can identify the StoreFile type and perform the appropriate operations. Running this utility without any options launches a wizard that helps with certificate management.

Syntax

certmgr [/add | /del | /put] [arguments] [/s[/r RegistryLocation]] Storename

Arguments

Argument | Description
/add | Adds certificates from one certificate store to another.
/delete | Deletes certificates.
/put | Saves an X.509-encoded certificate, CTL, or CRL to a file.
/c | Adds certificates when used with /add; deletes certificates when used with /del. Displays certificates when used without the /add or the /delete option.
/all | Adds all the entries if used with /add; deletes all the entries if used with /del.
/7 | Saves the destination store as a PKCS#7 object.
/n commonName String | Specifies the common name of the certificate to add or delete. This option can only be used with certificates; it cannot be used with CTLs or CRLs.
/sha1 sha1Hash | The SHA1 hash of the certificate, CTL, or CRL to add or delete.
/CTL | Adds or deletes certificate trust lists (CTLs). Displays certificate trust lists when used without the /add or the /delete option.
/CRL | Adds or deletes certificate revocation lists (CRLs). Displays certificate revocation lists when used without the /add or the /delete option.
/s | Indicates the store is a system store. If this option is not specified, the store is a StoreFile.
/r RegistryLocation | Identifies the registry location of the system certificate store. This option is considered only if the /s option is specified. Registry location must be either currentUser (indicating that the certificate store is under the HKEY_CURRENT_USER key [the default]) or localMachine (indicating that the store is under HKEY_LOCAL_MACHINE).
/? | Displays Help for the utility.
/v | Verbose mode. Displays detailed information about certificates (CTLs and CRLs). This option cannot be used with the /add or the /delete options.
/y storeProviderType | Specifies the store provider type.
/f dwFlags | Specifies the store open flag. This is the dwFlags parameter passed to CertOpenStore. The default value is CERT_SYSTEM_STORE_CURRENT_USER. This option is considered only if the /y option is used.
/e encodingType | Specifies the certificate encoding type.

Examples

The following examples show some of the certmgr utility's functions. Each sample command line is followed by a description.

Use the following example to view a system store called my.

certmgr /s my

Use the following example to add all the certificates in a file called myfile.ext to a new file called newFile.ext.

certmgr /add /all /c myFile.ext newFile.ext

Use the following example to move a certificate with a common name myCert in my system store to a file called newCert.cer.

certmgr /add /c /n myCert /s my newCert.cer

Use the following example to delete all the CTLs in my system store and save the resulting store to a file called newStore.str.

certmgr /del /all /ctl /s my newStore.str


Certificate Verification Utility (chktrust.exe)

The ChkTrust utility checks the validity of an Authenticode™-signed file. If the hashes agree, ChkTrust verifies the signing certificate.

Syntax

ChkTrust [options] signedFile
Argument | Description
signedFile | Named of the signed filed containing the signature to be verified.
Option | Description
-q | ChkTrust will not display user interface.
-v | Verbose mode. Displays detailed information about the validity of a signed file. The default is to display brief information.

Example

The following command demonstrates the use of ChkTrust with Internet Explorer 4.0 or later.

ChkTrust MyProgram.exe

A successful response from the above command would be:

MyProgram.exe: Succeeded

This result indicates that the file checked has a valid digital signature.


Runtime Debugger (cordbg.exe)

cordbg is a command-line utility that can help tools vendors and application developers find and fix bugs in programs that target the NGWS runtime. This utility uses the Runtime Debugging Services API . Currently, cordbg can only be used for debugging managed code — there is no support for debugging unmanaged code.

For more information about the runtime's debugging services, see the following specifications:

  • Runtime Debugging Services
  • Enabling Debugging and Profiling in the NGWS Runtime
  • Runtime Debug Reference

Using cordbg

To use cordbg, you start a debugging session and then use commands (with appropriate arguments) to invoke the required functionality. This section explains how you start debugging and then lists each command along with its arguments.

Note that several commands have "synonyms," which means that you can use any one of several commands to produce a particular result. For example, either the break or the stop command can be used to set breakpoints.

Starting a Debugging Session

The application to be debugged must be compiled using compiler-specific flags to cause debugging symbols to be generated. For more information about these flags, see the compiler documentation.

After the application is compiled, you can start a debugging session in the following way:

D:\Factorial>cordbg
Microsoft (R) NGWS Runtime Test Debugger Shell.  Version 1999.14.1703.0
Copyright (c) Microsoft Corp. 1998-1999
(cordbg)

The (cordbg) prompt indicates that you are in the Debugger.

cordbg Commands

In the command line syntax shown below, brackets enclose optional characters in the command name and indicate optional arguments. Note that cordbg commands are case-sensitive.

The cordbg commands are as follows:

ap[pdomainenum] [<option>]
Enumerates all application domains, assemblies, and modules in the current process.

The option argument can be one of the following:

0 Lists the application domains and prompts the user

1 Lists only the application domains

2 Lists the application domains and assemblies

If the option argument is omitted, the command lists all the application domains, assemblies, and modules in the current process.

as[sociatesource] [s | [b <breakpoint number>] <file name>
Associates the given file name with the specified breakpoint (option b) or the current stack frame pointer (option s).
a[ttach] <pid>
Attaches the debugger to an existing process. The program currently being debugged (if there is one) is killed, and an attempt is made to attach to the process specified by the pid argument. The process identification number pid can be in decimal or hexadecimal. If no argument is specified, enables unmanaged debugging on the current process.

To attach to a NGWS application, set the environment variable CORDBG_ENABLE = 1 before launching the application. This will allow cordbg to attach to the process.

b[reak] [ [<file>:]<line number> [if <expression>] [thread <tid>] ] | [ [<class>::]<function>[:offset]]
Sets or displays breakpoints. If no arguments are passed, a list of current breakpoints is displayed; otherwise, a breakpoint is set at the specified location. A breakpoint can be set at a line number in the current source file, a line number in a fully qualified source file, or in a method qualified by a class and optional offset. You can use the stop command the same way you use break.

Breakpoints will be displayed as “unbound” if the breakpoint location you specified cannot be bound to code. When a breakpoint is unbound, it means that the underlying code for the breakpoint location has not been loaded yet. This can happen for a number of valid reasons, such as misspelling the file or class name (they are case-sensitive). Also, breakpoints will be unbound if they are set before running an application. Breakpoints become bound when the real code is loaded. The debugger tries to automatically rebind every unbound breakpoint when each module is loaded.

ca[tch] [<event>]
Displays a list of event types or causes the specified event type to stop the debugger. If no argument is passed, a list of event types is displayed, where event types that stop the debugger are marked "On," and event types that are ignored are marked "Off." If an event argument is provided, the debugger will stop when events of the specified type occur. By default, the debugger only stops on unhandled exception events (i.e., second chance exceptions). Stop events persist across runs in a session. To cause the debugger to ignore a particular type of event, use the ignore command.

The event argument can be one of the following:

e[xception] | All exceptions
u[nhandled] | Unhandled exceptions
c[lass] | Class load events
m[odule] | Module load events
t[hread] | Thread start events
c[lear]
Clears a managed exception on the current thread.
c[ont] [<count>]
Continues the program. If no argument is passed, the program is continued once. If a count argument is provided, the program is continued the specified number of times. This command is useful for continuing a program when the class load event stops the debugger. You can use the go command the same way you use cont.
del[ete] [<breakpoint number>,…]
Deletes breakpoints. If no arguments are passed, all current breakpoints are deleted. If one or more breakpoint number arguments is provided, the specified breakpoint(s) are deleted. Breakpoint identifiers can be obtained using the break or stop command. You can use the remove command the same way you use delete.
de[tach]
Detachs cordbg from the currently running process.
dis[assemble] [<line count>]
Displays a disassembly of instructions around the current executable instruction. If no argument is passed, the five (5) instructions before and after the current instruction are displayed. If a line count argument is provided, the specified number of extra instructions will be shown before and after the current one. The last line count used becomes the default for the current session.
d[own] [<frame count>]
Moves the stack frame pointer down the stack toward frames called by the current frame. If no argument is passed, the stack frame pointer moves down one. If a frame count argument is provided, the stack frame pointer moves down by the specified number of frames. If source level information is available, the source line for the frame is displayed. This command is used after the up command has been used.
du[mp] <address> [<count>]
Dump a block of memory with the output in hexadecimal or decimal depending on which mode (see mode) the debugger is in. The address argument is the address of the block of memory. The count argument is the number of bytes to dump. If either argument begins with the prefix 0x, the argument is assumed to be in hexadecimal format. Otherwise, the argument is assumed to be in decimal format.
ex[it]
Stops the current program and quits the debugger. You can use the quit command in the same way you use exit.
f[unceval] [<classname>::] <function name> [<arg0> <arg1>…]
Evaluates the specified function on the current thread. Arguments should be specified in order, and for non-static methods ‘this’ should be the first argument.
g[o] [<count>]
See cont.
h[elp] [<command>…]
Displays command descriptions. If no arguments are passed, a list of debugger commands is displayed. If one or more command arguments is provided, descriptions are displayed for the specified commands. You can use the ? command the same way you use help.
ig[nore] [<event>]
Displays a list of event types or causes the specified event type to be ignored by the debugger. If no event argument is passed, a list of event types is displayed, where event types that are ignored are marked "Off" and event types that stop the debugger are marked "On." If an event argument is provided, the debugger will ignore events of the specified type. To set an event type to stop the debugger, use the catch command.

The event argument can be one of the following event types:

exception | All exceptions
unhandled | Unhandled exceptions
class | Class load events
module | Module load events
thread | Thread start events
i[n] [<count>]
See step.
k[ill]
Stops the program. The debugger remains active to process further commands.
list <option>
Displays the requested list.

The option argument can be one of the following:

mod | Lists the loaded modules in the process
cl | Lists the loaded classes in the process
m[ode] [ [<mode name> 0] | [<mode name> 1] ]
Sets and queries modes for other debugger features. To set a value, specify the mode name argument and a 1 for on and 0 for off. If no argument is passed, lists all the current mode settings. Currently, the mode argument can be one of the following:
AppDomainLoads | Specifies if application domain and assembly load events are displayed
ClassLoads | Specifies if class load events are displayed
EditAndContinue | Specifies if Edit and Continue is enabled
HexDisplay | Controls whether numbers are shown in hexadecimal or decimal
JitOptimizations | Specifies if JIT compilation generates debuggable code
ModuleLoads | Specifies if module load events are displayed
ILNatPrint | Specifies if frame, thread, instruction offsets should be printed IL relative, native relative, or both
ISAll | Specifies if cordbg should step through all interceptors or over prologs while stepping through code
ISClinit | Specifies if cordbg should step through or over class initialization while stepping through code
ISExceptF | Specifies if cordbg should step through or over exception filters while stepping through code
ISInt | Specifies if cordbg should step through or over user interceptors while stepping through code
ISPolicy | Specifies if cordbg should step through or over context policies while stepping through code
ISSec | Specifies if cordbg should step through or over security interceptors while stepping through code
ShowArgs | Specifies if arguments should be shown in stack trace
SeparateConsole | Specifies if debuggees get their own console
USAll | Specifies if cordbg should step through native assembly unmanaged stop locations, i.e., prolog, epilog, unmapped, and no mapping locations, while stepping through code
USEpi | Specifies if cordbg should step through native assembly epilogs or over native assembly epilogs while stepping through code
USPro | Specifies if cordbg should step through native assembly prologs or over native assembly prologs while stepping through code
USUnmanaged | Specifies if cordbg should step through native assembly unmanaged code while stepping through code
newo[bj] <class name>
Creates a new object of the given class using Function Evaluation.
newobjnc <class name>
Creates a new object of the given class using Function Evaluation, but without running a constructor on the new object.
news[tr] <string>
Creates a new string with the given value using Function Evaluation.
n[ext] [<count>]
Steps the program to the next line(s), stepping over function calls. If no argument is passed, one source line is stepped over. If a count argument is provided, the specified number of lines will be stepped. You can use the so command the same way you use next.
ns[ingle] [<count>]
Steps the program one or more instructions, skipping over function calls. If no argument is passed, the program is stepped one instruction. If a count argument is provided, the program is stepped the specified number of instructions.
o[ut] [<count>]
Steps the program out of the current function. If no argument is passed, a step out is performed once for the current function. If a count argument is provided, then a step out is performed the specified number of times.
pa[th] [<new path>]
Displays the path used to search for source files or sets the path. If no argument is passed, the current source file path is displayed. If a path argument is specified, it becomes the new path used to search for source files. This path is persisted between sessions in the Windows registry.
p[rint] [<variable name>]
Displays one or more local variables along with their values. If no argument is passed, all local variables and their values are displayed. If a variable name argument is provided, the value of only the specified local variable is displayed.

Variables within objects can be specified using dot notation, as follows:

print obj.var1
print obj1.obj2.var1

If a class extends another class, the print command will show both the specified class’s fields and the super class’s fields. For example, if class m1 has fields a, b, and c and class m2 extends m1 and has fields d, e, and f, then an instance foo of m2 will print as follows:

foo = <addr> <m2>
      a = 1
      b = 2
      c = 3
      m2::d = 4
      m2::e = 5
      m2::f = 6

Class static variables can be specified by prefixing the variable name with the class name, as follows:

print MyClass::StaticVar1

Array indices must be simple expressions. Thus, the following array indices are valid for use with the print command:

print arr[1]
print arr[i]
print arr1[arr2[1]]
print md[1][5][foo.a]

However, the following array indices cannot be used with the print command:

print arr[i + 1]
print arr[i + 2]
pro[cessenum]
Enumerates all managed processes and the application domains in each process.
q[uit]
See exit.
ref[reshsource] [<source file>]
Refreshes the source code for a given source file. The source file to be refreshed must be part of the currently executing program. After setting a source file path with the path command, the refreshsource command can be used to bring in missing source code.
regd[efault] [force]
Sets the default managed JIT debugger to cordbg. The command does nothing if another debugger is already registered. Use the force argument to overwrite the registered managed JIT debugger.
reg[isters]
Displays the registers.
rem[ove] [<breakpoint number>,…]
See delete.
resume [ [<tid>] | [~<tid>] ]
Resumes the thread specified by the tid argument when the debugger continues. If the ~ syntax is used, resumes all threads except the specified thread. If no argument is passed, the command has no effect.
r[un] [<executable> [<args>]]
Stops the current program (if there is one) and starts a new one. If no executable argument is passed, this command runs the program that was previously executed with the run command. If the executable argument is provided, the specified program is run using the optionally supplied args. If class load, module load, and thread start events are being ignored (as they are by default), then the program will stop on the first executable instruction of the main thread.
setip <line number>
Sets the next statement to be executed to the specified line number.
set <variable specifier> <value>
Sets the value of the specified variable to the specified value. The value can be a literal or another variable. Thus, the following are valid uses of the set command:
set int1 0x2a
set float1 3.1415
set char1 ‘a’
set bool1 true
set obj1 0x12345678
set obj1 obj2
set obj1.m_foo[obj1.m_bar] obj3.m_foo[2]
sh[ow] [<line count>]
Displays source code line(s). If no argument is passed, the five source code lines before and after the current source code line are displayed. If a line count argument is provided, the specified number of lines before and after the current line is displayed. The last line count specified becomes the default for the current session.
si [<count>]
See step.
so [<count>]
See next.
ss[ingle] [<count>]
Steps the program one or more instructions, stepping into function calls. If no argument is passed, only one instruction is stepped into. If a count argument is provided, the specified number of steps is performed.
s[tep] [<count>]
Steps the program, stepping into function calls. If no argument is passed, the program is stepped to the next line. If a count argument is provided, the specified number of lines will be stepped. You can use the si command or the in command the same way you use step.
stop [ [<file>:]<line number>] | [ [<class>::]<function>[:offset]]
See break.
suspend [ [<tid>] | [~<tid>] ]
Suspends the thread specified by the tid argument when the debugger continues. If the ~ syntax is used, suspends all threads except the specified thread. If no argument is passed, the command has no effect.
t[hreads] [<thread id>]
Displays a list of threads or sets the current thread. If no argument is passed, the list of all threads that are still alive and that have run managed code is displayed. If a thread id argument is provided, then the current thread is set to the specified thread.
up [<frame count>]
Moves the stack frame pointer up the stack toward frames that called the current stack frame. If no argument is passed, the stack frame pointer moves up one frame. If a frame count argument is provided, the stack frame pointer moves up the specified number of stack frames. If source level information is available, the source line for the frame is displayed.
w[here] [<frame count>]
Displays a stack trace for the current thread. If no argument is passed, a complete stack trace is displayed. If a frame count argument is provided, the specified number of stack frames is displayed.
wr[itememory] <address> <count> <byte>,…
Writes the specified bytes to the target process. The address argument, formatted as per wcstol, specifies the location to which the bytes should be written. The count argument specifies the number of bytes to be written. The byte arguments, formatted as per wcstol, specifies what is to be written to the process. If the number of bytes in the list is less than the count argument, the byte list will be wrapped and copied again. If the number of bytes in the list is more than the count argument, the extra bytes will be ignored.
wt
The command, starting from the current instruction, steps the application by native instructions printing the call tree as it goes. The number of native instructions executed in each function is printed with the call trace. Tracing stops when the return instruction is reached for the function that the command was originally executed in. At the end of the trace, the total number of instructions executed is printed. The command mimics the wt command found in NTSD, and can be used for basic performance analysis. Only managed code is counted for now.
? [<command>…]
See help.


NGWS Runtime IL Assembler (ilasm.exe)

IL is the intermediate language that is converted to machine language by the NGWS runtime's JIT compilers. Tools that generate IL can benefit from the common infrastructure provided by the runtime, the IL support for early and late binding, and the fact that code compiled to IL will run on any platform supported by the runtime. The ease with which IL can be generated is advantageous in RAD (rapid application development) environments, where fast compilation and easy debugging are of primary importance. The runtime manages source code that is compiled to IL during execution so that it benefits from features such as cross-language inheritance, code access security, garbage-collection, and simplified COM programming.

To assist tools vendors with the task of designing and implementing IL generators, the runtime provides the IL Assembler, ilasm. This tool takes IL as input and generates a portable executable (PE) file containing the IL and the required metadata. The resulting executable can be run to determine whether the IL performs as expected. The IL Assembler allows tools developers to concentrate on IL generation without being concerned with emitting IL in the PE file format. This tool is intended primarily for testing the performance of small sequences of IL and to test IL generation strategies.

Although the IL Assembler is helpful in the early stages of generating IL, it has some limitations: it does not emit all possible runtime PE file features, and it cannot produce a PE file that can be statically linked with other files (an .obj file). Therefore, the IL Assembler is not intended to provide a long-term solution. Compilers and other tools that generate IL must eventually emit the PE file format expected by the runtime.

There is a companion tool, ildasm, that takes a PE file containing IL code and creates a text file suitable as input to the IL Assembler. This ability to round trip code can be useful, for example, when compiling code in a programming language that doesn't support all of the runtime metadata attributes. The code can be compiled, then the output run through ildasm, and the resulting IL text file can be hand edited to add the missing attributes. This can then be run through the IL Assembler to produce a final, runnable file.

In order to make this round tripping possible, the assembler does not perform some simple optimizations that are provided by other assemblers: it does not deduce whether to use short or long forms of instructions. For example, the tool does not try to determine if it could substitute a short encoding for the long one you may have written in your IL sources; if you want the short encoding, you must explicitly write that form.

The assembler does, however, check for out-of-range conditions where this is possible.

Note At the present time, PE files produced by Visual C++ can't be round-tripped using ilasm.

Syntax

ilasm [options] filename [options]

In the following list, boldface means the argument is assumed by default.

Option | Description
/DEBUG | Includes debug info (local variable and argument names, line numbers).
/DLL | Produces a .dll file rather than an .exe file as output.
/EXE | Produces an .exe file rather than a .dll file as output.
filename | Name of the .il file. The file consists of IL surrounded by assembler directives at the class, method, and field level.
/LISTING | Produces a listing file on the standard output.
/NOLISTING | Doesn't produce a listing file.
/OUTPUT=<file.ext> | Set the output file name and extension. By default, the output file name is the same as input (source) file name, and extension is .exe or .dll (if /DLL option is specified). The file extension must be specified (unless it is intentionally omitted). Warning: specifying /OUTPUT=myfile.dll will not set the /DLL option; if /DLL option is not specified, the result will be an .exe file named myfile.dll.
/OWNER=<OwnersName> | Sets the owner’s name or password (no spaces allowed), so future disassembly with ildasm tool would be possible only if this name is provided. If <OwnersName> is omitted, the ildasm tool will not disassemble the generated .exe or .dll file.
/QUIET | Don't report assembly progress.
/RESOURCE=<file.res> | Include the resource file in *.res format (no more than one) into resulting .exe or .dll file.

All ILASM and ILDASM options are recognized by first three letters, so /NOL equals /NOLISTING, /RES=myresfile.res equals /RESOURCE=myresfile.res, etc. The options are case-insensitive.

See Also

NGWS Runtime IL Disassembler


NGWS Runtime IL Disassembler (ildasm.exe)

Ildasm is a companion tool to the NGWS Runtime IL Assembler (ilasm.exe). Ildasm takes a portable executable (PE) file containing IL code and creates a text file suitable as input to the IL Assembler. This ability to round trip code can be useful, for example, when compiling code in a programming language that doesn’t support all of the runtime metadata attributes. The code can be compiled, then the output run through ildasm, and the resulting IL text file can be hand edited to add the missing attributes. This can then be run through the IL Assembler to produce a final runnable file.

Note Note that at the present time, PE files produced by Visual C++ can't be round-tripped using ildasm.

Syntax

ildasm [options] PEfilename [options]

Options for .exe, .dll, .obj, and .lib files:

Option | Description
/OUT=filename | Creates a file (with the specified filename) for output, rather than simply presenting the output results in a dialog box.
/TEXT | Presents the output results in a console window, rather than a file or a dialog box.

Additional options for .exe and .dll files:

Option | Description
/OWNER=ownername | Sets the owner's name to disassemble a protected file. The owner's name is required if the name was set when the file was assembled (using the Ilasm tool).
/BYTES | Show actual bytes, in hex, as instruction comments.
/RAWEH | Show exception handling clauses in raw form.
/TOKENS | Show metadata tokens of classes and members.
/SOURCE | Show original source lines as comments.
/LINENUM | Include references to original source lines.
/VISIBILITY=vis [+vis …] | Only disassembles types or members with the specified visibility. Valid values for vis are: PUB, PRI, FAM, ASM, FAA, FOA, and PSC.
/PUBONLY | Only disassembles public types and members. Equivalent to /VISIBILITY=PUB.
/QUOTEALLNAMES | Include all names in single quotes.
/NOBAR | Suppress disassembly progress bar pop-up.

For .exe and .dll files, console output only (if /OUT is specified):

Option | Description
/NOIL | Suppress IL assembly code output.
/HEADER | Include file header information in the output.
/ALL | Combination of /HEADER, /BYTES, /TOKENS.

For .exe, dll, .obj, and .lib files, console output only (if /OUT is specified):

Option | Description
/ITEM=class [::method sig] | Disassembles the specified item only.

For .lib files, console output only (if /OUT is specified):

Option | Description
/OBJECTFILE=filename | Show metadata of a specific object file in a library.

Option key is '-' or '/'.

All ILASM and ILDASM options are recognized by first three letters, so /NOL equals /NOLISTING, /RES=myresfile.res equals /RESOURCE=myresfile.res, etc. The options are case-insensitive.

See Also

NGWS Runtime IL Assembler


Jit Manager Utility (jitman.exe)

Jitman is a utility that allows SDK users to control various options in the NGWS runtime related primarily to JIT compilation and garbage collection. The utility presents a simple dialog-based UI that allows the user to set these options. When launched, Jitman places an icon in the tray so the utility can be easily accessed. The following picture shows the UI:

UI Options

Option | Description
Use EconoJIT only If this option is checked, NGWS runtime will only use the EconoJIT when compiling code. If this option is not checked, the regular JIT compiler is used.

These two compilers offer administrators tradeoffs related to the speed at which the compiler runs, the amount of memory the compiler uses and the quality of code produced by the compiler. The characteristics of EconoJit are:

  • The compiler itself runs very fast
  • The amount of memory used by the compiler is bounded and can be controlled by the administrator.
  • The quality of the code produced by the compiler is not as high as the quality of the code produced by the regular JIT.

In contrast, the regular JIT compiler produces higher quality code, but the compiler itself doesn’t run as fast as the EconoJIT. In addition, the amount of memory used by the compiler is variable and cannot be controlled.

The default value for this setting is “off”. That is, use the regular JIT compiler.
Max Code Pitch Overhead If EconoJIT is being used, this setting controls the ratio of time spent jitting code vs. running code. If this ratio begins to exceed what is specified (i.e too much time is spent jitting), the EconoJIT expands the code cache to bring the ratio down.

The default value for this setting is 10%.
Limit Size of Code Cache | When this box is checked, the “Max Code Cache” field is enabled. If this box is not checked, the maximum size of the code cache is all the memory on the machine.
Max Code Cache If EconoJIT is being used, this setting controls the maximum size of the buffer used to hold the jitted code. If the buffer overflows, code is pitched out to make room for the newly compiled code. Jit compilation will fail on any method for which the jitted code size exceeds the total size of the buffer (i.e. the MaxCodeCache should be large enough to accommodate the largest method). The buffer size is given in bytes.

The default value for this setting is “unlimited” – the code cache will use all available memory on the machine.
Optimize for Size Causes the JIT compiler to optimize for small code size rather that speed.

The default value for this setting is “off”.
Enable Concurrent GC When concurrent GC is enabled, collections happen on separate threads so the threads running user code aren’t stopped during the collection. Concurrent GC is generally slower than normal GC, but results in smaller pauses. As a result, concurrent GC is useful for apps requiring a high degree of user interaction, like client UI apps. Concurrent GC requires write-watch support from the OS. This support is currently available on Windows2000 and the upcoming refresh of Windows98. This check box is disabled if the OS doesn’t have the necessary support.

The default value for this setting is “off”.


License Compiler (lc.exe)

lc.exe is a resource file generator utility that reads text files containing licensing information and produces a NGWS runtime binary .licenses file that can be embedded in a NGWS runtime binary executable.

Syntax

lc /TARGET:TargetPE /COMPLIST:filename [/OUTDIR:path] /I:modules
Argument | Description
/TARGET:TargetPE | The executable for which the .licenses file is being generated
/COMPLIST:filename | The name of a file that contains the list of licensed components to include in the .licenses file. Each component is referenced using its full name. One component per line
/I:modules | The list of modules containing the components listed in the complist file.
/OUTDIR:path | The directory in which to place to the output .licenses file

Example

If you are using a licensed control MyCompany.Samples.LicControl1 contained in Samples.DLL in an application called HostApp.exe, you create a HostAppLic.txt that contains the following:

MyCompany.Samples.LicControl1, Samples.DLL

You then create the .licenses file using the following command:

Lc /target:HostApp.exe /complist:hostapplic.txt /I:Samples.DLL /outdir:c:\bindir

This will produce a .licenses file called HostApp.exe.licenses.

You then build HostApp.exe including the .licenses file as a resource. For instance if you were building a C# application you would use the following command to build your application:

csc /res:HostApp.exe.licenses /out:HostApp.exe *.cs

See Also

NGWS Frameworks and Runtime Resources


Certificate Creation Utility (makecert.exe)

Makecert (the X.509 Certificate Creation utility) generates a X.509 certificate, which can be used for testing purposes only. It creates a public and private key pair for digital signatures and associates it with a name that you specify. This utility also associates the key pair with a specified publisher's name and creates a X.509 certificate that binds your name to the public part of the key pair.

Syntax

makecert [optional arguments] OutputCertificateFile

Basic Arguments

Argument | Description
-sk | Subject's key container name (will be created if not present).
-# | Serial Number from 1 to 2^31-1. Default to be unique.
-$ | The signing authority of the certificate: either individual or commercial.
-n | Certificate subject X500 name (e.g.,: CN=Fred Dews).
-? | Returns a list of basic arguments.
-ss | Subject's certificate store name that stores the output certificate.
-sr | Subject's certificate store location. <CurrentUser|LocalMachine>. Defaults to CurrentUser.
-! | Returns a list of extended options.

Extended Arguments

Argument | Description
-ik | Issuer's key container name.
-sc | Subject's certificate file.
-sv | Subject's PVK file (will be created if not present).
-sp | Subject's CryptoAPI provider's name.
-sy | Subject's CryptoAPI provider's type.
-ic | Issuer's certificate file.
-iv | Issuer's PVK file.
-is | Issuer's certificate store name.
-ir | Location of issuer's certificate store, either CurrentUser or LocalMachine. The default is CurrentUser.
-ip | Issuer's CryptoAPI provider's name.
-iy | Issuer's CryptoAPI provider's type.
-a | The signature algorithm, either md5, or sha (defaults to md5).
-d | Display name for the subject.
-l | Link to the policy information (such as URL).
-cy | Certificate types: either end, authority, or both.
-b | Start of the validity period in mm/dd/yyyy format (defaults to now).
-m | The number of months for the certificate validity period.
-e | End of validity period in mm/dd/yyyy format (defaults to 12/31/2039 11:59:59 GMT).
-h | Max height of the tree below this certificate.
-r | Create a self-signed certificate.
-nscp | Include Netscape client-authorization extension.
-iky | Issue key type <signature|exchange|<integer>>.
-sky | Subject key type <signature|exchange|<integer>>.
-in | Issuer's certificate common name.
-eku | Comma-separated OIDs for enhanced key usage.
OutputCertificateFile | The test X.509 certificate (.cer) file.

Examples

The following creates a test certificate and outputs it to testCert.cer.

makecert testCert.cer

The following creates a test certificate and outputs it to textXYZ.cer, using the subject's key container and the certificate subject's X500 name.

makecert -sk XYZ -n "CN=XYZ Company" testXYZ.cer

See Also

Software Publisher Certificate Test Utility (Cert2spc.exe)


Permissions View Utility (permview.exe)

Use the PermView command line utility to view the permissions requested for an assembly. This utility displays only the permission sets requested at the assembly level, not permission sets requested at the class or method level. By default, permission requests are dumped to the console.

Syntax

PermView [/OUTPUT filename] manifestfile
Option | Description
/OUTPUT filename | Output will be dumped to a file.


PEVerify Utility (peverify.exe)

The NGWS runtime relies on type-safe execution of application code to ensure that its security and isolation mechanisms are enforced. Code that is not verifiably type-safe is normally not allowed to run, although one can set policy to allow trusted, but unverifiable code, to execute.

The PEVerify utility is provided to assist developers generating IL (i.e., compiler writers, script engine developers, etc.) in determining whether their IL code and associated metadata meets type-safety verification requirements. PEVerify might also benefit application developers in validating the type-safety of their code prior to release if they are using tools that generate type-safe IL only if certain language constructs are avoided.

Syntax

peverify Filename [options]
Option | Description
/IL | Perform IL type safety verification checks for methods implemented in the assembly denoted by Filename. Detailed descriptions for each problem found are returned unless the “-quiet” option is specified. (See Notes for current limitations.)
/MD | Perform metadata validation checks on the file Filename. This walks the full metadata structure within the file, automatically enumerating all module components. It will report all validation problems encountered. (See Notes for current limitations.)
/CLS | Perform CLS-compliance checks. (See Notes for current limitations.)
/NOCLS | Do not perform CLS-compliance checks.
/UNIQUE | Disregard repeating error codes.
/HRESULT | Display error codes in hex format.
/IGNORE=hex.code [, hex.code] | Ignore specified error codes.
/IGNORE=@filename | Ignore error codes in specified file.
/BREAK=maxErrorCount | Abort verification after maxErrorCount errors.
/quiet | Suppress output of the verification problem reports. PEVerify will still report whether or not the file is type safe, but not information on problems preventing type safe verification.
/CLOCK | Measure and report verification times.

If neither /IL nor /MD are specified, peverify defaults to assuming both types of checks are desired. That is, peverify [Filename] is equivalent to peverify [Filename] /IL /MD.

Notes

peverify performs comprehensive IL verification checks based on dataflow analysis. Known limitations of verification include:
  • Delegate usage is only partially verified
  • toproxy/fromproxy instructions used in remote calls aren’t verified
Metadata validation checks are only partially implemented for this release. The following is a list of conditions currently being checked:
// Metadata problems reported
RID is out of range.
Coded token type is out of range.
Coded RID is out of range.
String offset is invalid.
GUID offset is invalid.
Blob offset if invalid.
Multiple module records found.
Module has null MVID.
TypeRef name is NULL.
TypeRef has a duplicate.
TypeDef name is NULL.
TypeDef has a duplicate based on name+namespace.
TypeDef has a duplicate based on GUID.
TypeDef that's not an Interface and not System.Object extends NIL parent.
System.Object extends a non-NIL parent.
TypeDef extends sealed class.
TypeDef is Deleted but not marked with RTSpecialName.
TypeDef is marked RTSpecialName, but is not a Deleted record.
TypeDef is an Enum but not a ValueType.
TypeDef is marked both Abstract and Sealed.
TypeDef is marked both Unmanaged and Nested.
TypeDef is marked both Interface and Nested.
TypeDef is marked Interface but is not Abstract.
TypeDef is marked Interface but its parent is not NIL.
TypeDef is marked Interface but GUID is NULL.
TypeDef is marked ValueType but extends a non-class TypeDef.
TypeDef is marked ValueType but is not marked Sealed.
TypeDef is marked Class but extends a non-class TypeDef.
InterfaceImpl has a duplicate.
MemberRef name is NULL.
MemberRef has invalid name, _VtblGap*.
MemberRef has invalid name, _Deleted*.
MemberRef parent is NIL in a PE file.
MemberRef has invalid calling convention.
MemberRef has Method parent but calling convention is not VARARG.
MemberRef name different from parent MethodDef.
MemberRef signature different from parent MethodDef.
MemberRef has a duplicate.
ClassLayout parent TypeDef is marked AutoLayout.
ClassLayout has bad PackingSize.
ClassLayout has a duplicate.
FieldLayout2 has bad offset.
FieldLayout2 has field with nil parent.
FieldLayout2 has no ClassLayout record.
FieldLayout2 parent TypeDef is not marked with ExplicitLayout.
FieldLayout2 has field marked Static.
FieldLayout2 has a duplicate.
ModuleRef name is NULL.
ModuleRef has a duplicate.
Mulitple ModuleRefs in a Module with OrdinalMap table.
Unexpected MetaData in OrdinalMap module.
TypeDef extends a TypeRef which resolves to a TypeDef in the same module.
Signature specified is zero-sized.
Signature does not have enough data at specified byte.
Method signature has invalid calling convention.
Method is marked static but has HASTHIS/EXPLICITTHIS set on the calling convention.
Method is not marked static but is not HASTHIS/EXPLICITTHIS.
Method signature is missing the argument count.
Signature missing element type.
Signature missing token.
Signature has bad token.
Signature is missing function pointer.
Signature has function pointer missing argument count.
Signature is missing rank specification.
Signature is missing count of sized dimensions.
Signature is missing size of dimension.
Signature is missing count of lower bounds.
Signature is missing a lower bound.
Signature has bad element type.
Signature has value array missing size.
Field signature has invalid calling convention.
Method name is NULL.
Method has parent NIL.
Method has duplicate.
Field name is NULL.
Field parent is NIL.
Field has duplicate.
// General error conditions reported
Validator has been interrupted by the VEHandler.
Validator failed to initialize correctly.

As of this release, the following are not checked:

Assembly Manifest information
CLS compliance
Debugging Symbols


Assembly Registration Tool (RegAsm.exe)

RegAsm reads the metadata within an assembly and adds the necessary entries to the registry so classic COM clients can create the NGWS runtime classes transparently. Once a class is registered, any classic COM client can use it as though the class were a COM class. The registration process is only done one time when the assembly is installed. The classes within the assembly are not COM creatable until they are actually registered.

RegAsm can also be used to generate a .reg file with the needed entries instead of actually making the changes to the registry.

Syntax

RegAsm AssemblyFile [options]
Option | Description
/reg: RegFile | Generates a .reg file named RegFile for the assembly, containing the registry entries that would have been added if this option had not been provided. The registry is not changed when this option is specified.
/u | Causes RegAsm to unregister the public classes found in AssemblyFile. Omitting this option causes the public classes in the assembly to be registered.
/s | Suppresses all console output.

Remarks

If the /reg option is specified and RegAsm generates a .reg file, the .reg file can be used to update the registry on a machine by importing the file with the RegEdit tool. Note, however, that the .reg file does not contain any registry updates that may be made by any user defined register functions.

Using the /tlb option has the same effect as running TlbExp then RegAsm.

Examples

This example registers all public classes contained in mytest.dll.

RegAsm mytest.dll

This example generates the file MyReg.reg that contains all the entries that would have been made to the registry if the /reg option had not been supplied. The registry is not updated.

RegAsm mytest.dll /reg: mytest.reg

This example registers all public classes contained in mytest.dll. Generates and registers the type library mytest.tlb that contains definitions of all the public types defined in mytest.dll.

RegAsm mytest.dll /tlb: mytest.tlb

This example generates the type library mytest.tlb that contains definitions of all the public types defined in mytest.dll. It also generates the file MyReg.reg that contains all the entries that would have been made to the registry if the /reg option had not been supplied. The registry is not updated.

RegAsm mytest.dll /tlb: mytest.tlb /reg mytest.reg


Services Registration Tool (RegSvcs.exe)

RegSvcs makes it easy to add managed classes to Windows 2000 Component Services by combining several activities into a single utility. Specifically, RegSvcs performs the following actions:

  • Loads and registers an assembly.
  • Generates, registers, and installs the type library into an existing COM+ 1.0 application.
  • Configures services that you have added programmatically to your class.

Syntax

RegSvcs AssemblyFile.dll ApplicationName [tlbName.tlb]

Remarks

This tool requires an NGWS runtime source assembly file and the name of the destination application in Component Services. If you plan to install your class into a new COM+ 1.0 application, create the application first before running the RegsSvcs utility. Optionally, you can specify a type library name or allow the utility to use the assembly name as the default.

Examples

This example adds all public classes contained in mytest.dll to mytestapp, an existing COM+ 1.0 application, and produces the mytest.tlb type library.

RegSvcs mytest.dll mytestapp

This example adds all public classes contained in mytest.dll to mytestapp, an existing COM+ 1.0 application, and produces the newtest.tlb type library.

RegSvcs mytest.dll mytestapp newtest.tlb


Resource File Generator Utility (ResGen.exe)

ResGen is a resource file generator utility that reads text files containing name/value pairs and produces a NGWS runtime binary “.resources” file.

Lines that begin with the character ‘#’ are assumed to be comments. Each name/value pair should be specified on a separate line as follows:

name=value

ResGen checks the text file for duplicate resource names.

Syntax

ResGen filename [OutputFilename]
Argument | Description
filename | Name of the text file containing the name/value pairs of the resources. If Filename does not have the extension .txt, ResGen looks for a file name obtained by appending the string .txt to filename.
OutputFilename | Name of the resource file to be created. If no name is given, resgen uses the name of the text file given in filename, appends a .resources extension, and writes the file to the directory containing filename.

Remarks

ResGen generates a binary “.resources” file that contains simple, name/value pairs that are read from a text file. To create more complex “.resource” files (containing, for example, bitmaps, windows, and icons) use the ResourceWriter class.

Examples

The following displays a description of the command and exits.

ResGen

The following reads the name/value pairs in myResources.txt and writes a binary resources file named myResources.resources.

ResGen myResources.txt

The following reads the name/value pairs in myResources.txt and writes a binary resources file named myResources.resources.

ResGen myResources

See Also

ResX Resource Compiler (ResXToResources.exe)


ResX Resource Compiler (ResXToResources.exe)

ResXToResources.exe is a resource file generator utility that reads .ResX (XML-based resource format) files and produces a NGWS runtime binary .resources file that can be embedded in a NGWS runtime binary executable.

Syntax

ResXtoResources [/compile input.resX output.resources] [/decompile input.resources output.resX]
Argument | Description
/compile input.resX output.resources | Create a .resources file based on the contents of the .resX file
/decompile input.resources output.resX | Create a .resX based on the contents of the .resource file

Example

If you are creating a Win Forms C# application MyCompany.App1 that uses a bitmap as the background for a Button, you would start by creating a App1.resX file as follows:

<root>
<schema id="root" targetNamespace="" xmlns="http://www.w3.org/1999/XMLSchema" xmlns:xdo="urn:schemas-microsoft-com:xml-xdo" xdo:DataSetName="root">
    <element name="data">
        <complexType content="textOnly">
            <attribute name="name" minOccurs="1" type="string"></attribute>
            <attribute name="type" type="string"></attribute>
            <attribute name="mimetype" type="string"></attribute>
            <element name="value" minOccurs="0" type="string"></element>
        </complexType>
    </element>
    <element name="resheader">
        <complexType content="textOnly">
            <attribute name="name" minOccurs="1" type="string"></attribute>
            <element name="value" minOccurs="0" type="string"></element>
        </complexType>
    </element>
</schema>
<root>
    <resheader name="ResMimeType">
        <value>text/microsoft-resx</value>
    </resheader>
    <resheader name="Version">
        <value>1.0.0.0</value>
    </resheader>
    <resheader name="Reader">
        <value>System.Resources.ResXResourceReader</value>
    </resheader>
    <resheader name="Writer">
        <value>System.Resources.ResXResourceWriter</value>
    </resheader>
    <data name="button1.BackgroundImage" mimetype="text/microsoft-urt/psuedoml-serialized/base64">
        <value> THE ACTUAL BITMAP RENDERED AS A BASE64 STRING</value>
    </data>
</root>
</root>

You then create a .resources file as follows:

ResXToResource /compile App1.resX App1.resources

Since the utility is case sensitive, the /compile and /decompile flags should be written in lowercase. Also, the utility does not provide automatic filename extensions, so you should make sure to add them yourself.

Having created the .resources file you can refer to it in your application (assuming C#) as follows:

System.Resources.ResourceManager resources
= new System.Resources.ResourceManager("App1",
typeof(App1), null, true);

button1.BackgroundImage = (System.Drawing.Image)resources.GetObject("button1.BackgroundImage");

You then build App1.exe including the .resources file as a resource:

csc /res:App1.resources, Win32Form1Namespace.App1.resources /out:App1.exe *.cs

The /res flag takes two parameters: the name of the physical file and the namespace in which that file will exist. Both parameters are case sensitive. In this example, App1.resource represents the resource file that will be compiled into the assembly, while Win32Form1Namespace.App1.resources informs the compiler that the resource file belongs to the form namespace.

See Also

Resource File Generator Utility


Secutil Utility

The NGWS runtime security system provides mechanisms for restricting the actions of code based on its associated evidence. Two types of evidence, strong names (also called shared names) and Authenticode™ publishers, are based on cryptographic keys and digital signature technology. As a result, we have high assurance concerning this evidence for a given assembly.

Using these forms of evidence in imperative identity permission checks is complicated by the fact that one must reference a fairly long sequence of binary data: a public key value in the case of a strong name and an X.509 Certificate in the case of Authenticode publishers. The secutil utility makes it easy to extract this information from an assembly and convert it into a format that can be incorporated into code.

Developers can run secutil specifying the assembly filename containing the evidence that they want to check in the code being developed. The output can then be pasted into the code in the form of a constant definition. This constant value is then used to construct the correct identity permission to check. See System.Security.Permissions.PublisherIdentityPermission and System.Security.Permissions.StrongNameIdentityPermission for information on how to construct these permissions.

Syntax

secutil [options] Filename
Option | Description
-s or -strongname | Extract the strong name (also referred to as the shared name) public key information from the referenced file. The assembly developer defined name and version number are also returned. By default, the public key information is returned in an array format suitable for using in a C#/managed extensions to C++ byte array definition (-a and –c switches). Only files containing assembly manifests will have strong name information. References other types of files, or private named Assemblies, will return an error.
-x or -x509certificate | Extract the Authenticode™ publisher certificate from the file Filename. By default, the public key information is returned in an array format suitable for using in a C#/managed extensions to C++ byte array definition (-a and –c switches). Only files that have been Authenticode signed will contain an X.509 Authenticode publisher certificate. References to other types of files will return an error.
-hex | Return the Strong Name public key or x509certificate as a hex- encoded string. This overrides formatting as a byte array. The –c and –v switches have no effect if this switch is specified.
-a or -array | Return the Strong Name public key or x509certificate as a byte array. This is the default format.
-c or -cmode | Return the Strong Name public key or x509certificate as a byte array formatted for use in a C#/managed extensions to C++ byte array definition. This is the default format.
-v or -vbmode | Return the Strong Name public key or x509certificate as a byte array formatted for use in VB byte array definition.
-h, help, -? or /? | Displays help information.

If no command line arguments are supplied, secutil will print help information on available switches and argument order.


Set Registry Utility (setreg.exe)

Setreg (the Set Registry utility) changes registry settings for public key cryptography.

Syntax

setreg [-q] {[Choice# [TRUE|FALSE]}
Argument | Description
-q | Quiet mode. The registry is set, but key values are not displayed.
Choice# | 1– Trust the test root. 2 – Use expiration date on certificates. 3 – Check the revocation list. 4 – Offline revocation server OK (individual). 5 – Offline revocation server OK (commercial). 8 – Invalidate version 1 signed objects. 9 – Check the revocation list on Time Stamp Signer. 10 - Only trust items found in the Trust database.

Examples

The following sets the registry to trust the test root (the root of all test certificates created with makecert) and displays key values.

setreg 1 TRUE

The following sets the registry to not check the revocation list, and not display key values.

setreg -q 3 FALSE


Assembly Cache Viewer (shfusion.dll)

The assembly cache viewer is a Windows shell extension that allows you to view and manipulate the contents of the global assembly cache using the Windows Explorer. The cache viewer allows you to look at the contents of the cache, add or delete assemblies from the cache and view an individual assembly’s properties.

To view the contents of the assembly cache, navigate to the “assembly” subdirectory of the Windows directory (typically c:\winnt\assembly) with the Windows Explorer:

Options

Delete an assembly. To delete an assembly from the cache, right click on that assembly in the viewer and select “Delete” from the context menu:

Or, you can use the following command line syntax to delete an assembly:

rundll32 fusion.dll, RemoveAssemblyFromCache assemblyname

For example:

rundll32 fusion.dll RemoveAssemblyFromCache calcr

View assembly properties. To view an assembly’s properties, right click on the assembly in the viewer and select properties. A property sheet is displayed which shows the assembly’s name, version, culture and originator as well as the codebase from which the assembly came and the last modified date of the assembly:

Add an assembly to the cache. To add an assembly to the assembly cache, simply drag and drop the file containing the manifest into the assembly cache directory using the Windows Explorer. Only assemblies with shared names may be added to the cache.

Or, you can add assemblies to the cache using the following command line syntax:

rundll32 fusion.dll, AddAssemblyToCache -m filepath

where filepath is the path to the file containing the manifest.

For example:

c:\mydir\myasm.dll


File Signing Utility (signcode.exe)

Signcode (the File Signing utility) signs a portable executable (PE) file with requested permissions to give developers more detailed control over the security restrictions placed on their component. You can sign a component or an assembly. If you are distributing an assembly rather than individual components (i.e., .dlls or .exes), you should sign the assembly, not the individual components. If signcode is run without any options, it launches a wizard to help with signing.

For more information on permissions granted through code access security, see Permissions.

signcode [options] filename
Argument | Description
filename | The name of the assembly or component to be signed.
Option | Description
-$ authority | Signing authority of the certificate, either individual or commercial. The default is using the certificate's highest permission.
-a algorithm | Hashing algorithm for signing, either md5 or sha1 (the default is md5).
-c file | Software publishing certificate file.
-cn name | The common name of the certificate.
-i info | Place to get more information on content (usually a URL).
-j dllName | Name of a DLL that returns an array of authenticated attributes for signing files. The user can specify more than one DLL by repeating the -j option.
-jp param | Parameter to be passed for the preceding DLL (specified using the /j option).
-k keyname | Key container name.
-ky keytype | Key type (signature | exchange | integer).
-n name | Text name representing content of the file to be signed.
-p provider | Name of the cryptographic provider on the system.
-r location | Location of the certificate store in the registry, either localMachine.or currentUser. The default is currentUser.
-s store | Certificate store containing signing certificates.
-sha1 thumbprint | The thumbprint is the sha1 hash of the signing certificate included in the certificate store.
-sp policy | Add all the certificates in the chain or add only to SPC store (the default is chain).
-spc file | SPC file containing software publishing certificates.
-t URL | Timestamp server's http address.
-tr number | The number of timestamp trials until success; defaults to 1.
-tw number | The delay (in number of seconds) between each timestamp. Defaults to 0.
-v pvkFile | PVK filename containing the private key.
-x | Do not sign the file. Only timestamp the file.
-y type | Cryptographic provider type to use.
-? | Displays command-line help.

Remarks

To sign with a software publisher certificate (SPC) file, the required options are /spc and /v if your private key is in a PVK file. If your private key in is a registry key container, /spc and /k are the required options. If you sign with an SPC file, you should create the SPC file using makecert and cert2spc.

Examples

The following signs XYZ.exe using the XYZ.spc Software Publisher Certificate.

signcode /spc XYZ.spc /k XYZ XYZ.exe

The following signs an assembly using the certificate in myCertificate.spc and the private key in myKey.pvk.

signcode /spc myCertificate.spc /v myKey.pvk  myAssembly

See Also

Permissions


Shared Name Utility (Sn.exe)

SN is a utility that helps create assemblies with shared names (also known as strong names). SN provides options for key management, signature generation and signature verification. Shared names are designed to satisfy the following requirements:

  1. Guarantee name uniqueness.
  2. Prevent others from "using your name." Because only you have your private key, no one can generate the same name that you can. For example, the 401k assembly generated with my key pair would have a different name than the 401k assembly generated with your key pair. Shared names help ensure that no one can release a version of an assembly with the same name as one created by you. This allows users of a given assembly to know that all subsequent versions of the assembly came from the same publisher.
  3. Provide some notion of integrity. If the runtime crypto checks pass, you can be guaranteed that the contents of the assembly hasn't been altered since the time the assembly was built.

Syntax

sn [-q(uiet)][options]
Option | Description
-c [csp] | Sets the default CSP that will be used for shared name signing. This setting applies to the entire machine. If no CSP name is provided, the current setting is cleared.
-d container | Deletes the key container named container from the shared name CSP.
-D assembly1 assembly2 | Verifies that two assemblies differ only by signature. This is often used as a sanity check after an assembly has been resigned with a different key-pair.
-e assembly outfile | Extracts the public key from assembly and stores it in outfile.
-i infile container | Installs the key pair given in infile in the key container named container. The key container resides in the shared name CSP.
-k outfile | Generates a new key pair and writes it to the file given by outfile.
-m [y|n] | Used to specify whether key containers are machine wide, or per-user. If y is specified, key containers are machine wide. If n is specified, key containers are per-user. If neither y or n are specified, this option displays the current setting.
-o infile [outfile] | Extracts the public key from the infile and stores it in a .csv file. Each byte of the public key is separated by a comma. This format is useful for hard coding references to keys as initialized arrays in source code. Places output on the clipboard if outfile is not supplied.
-p infile outfile | Extracts the public key from the key pair in infile and stores it in outfile. This public key can be used to set the originator using the /keyfile option on the AL utility. This is useful for the scenario where the assembly is signed with a different key pair than the one stored as the originator. This scenario is important during development when the author of the assembly doesn't have access to the private key that will be used for the final signing.
-R[c] [infile] | Allows SN to re-sign a previously signed assembly with a new key pair (provided in a file). The -Rc option allows the key pair to be read from a named key container instead. These options are useful in scenarios where assemblies that have shared names are signed with a test key pair, but re-signed with the correct, shared key pair just prior to shipping.
-t[p] infile | Displays the public key token for the public key stored in infile. The contents of infile were previously generated using -p. The token is computed using a hash function from the public key. Public key tokens are stored as part of the AssemblyRef in the manifest when recording a dependency to a sharedly named assembly. -t displays the token instead of the full public key to save space. -tp causes the public key to be displayed in addition to the token.
-T[p] assembly | Displays the public key token for assembly, which is the name of a file containing an assembly manifest. The token is computed using a hash function from the public key. Public key tokens are stored as part of the AssemblyRef in the manifest when recording a dependency to an assembly that has a shared name. -T displays the token instead of the full public key to save space. -Tp causes the public key to be displayed in addition to the token.
-v assembly | Verifies the shared name in assembly. assembly is the name of a file containing an assembly manifest.
-vf assembly | Verifies the shared name in assembly, as in the -v option; verification is forced, even if disable by registry.
-Vl | List current settings for shared name verification on this machine.
-Vr assembly [userlist] [infile] | Register assembly for verification skipping (with an optional comma separated list of usernames). If infile is provided, verification remains enabled, but the public key in infile is used in verification operations. Both assembly and userlist can be specified as * to indicate all assemblies and all users respectively.
-Vu assembly | Unregister assembly for verification skipping.
-Vx | Remove all verification skipping entries.
/? | Displays command-line help.

Examples

Sn -k mykey.snk
Creates a new, random key pair and stores it in mykey.snk
Sn - I mykey.snk mycontainer
Stores the key contained in mykey.snk in the container mycontainer in the shared name CSP.
Sn -v myasm.dll
Verifies the assembly myasm.dll
Sn -V n
Toggles verification off. Calls to SharedNameSignatureVerification will always pass.
Sn -d mycontainer
Delete mycontainer from the default CSP


Isolated Storage Utility (storeadm.exe)

Use the StoreAdm command line tool to managed isolated storage for the currently logged in user. The tool provides three simple functions that are typically used one at a time, however if two or more are specified they will be performed in the order they appear on the command line.

Syntax

StoreAdm [options]
Option | Description
/LIST | Displays the existing isolated storage for the current logged in user.
/QUIET | Suppresses informational output so that only error messages may appear.
/REMOVE | Removes (permanently) all existing isolated storage for the current logged in user.


Type Library Exporter (TlbExp.exe)

TlbExp is a command line tool that uses the API described in the following section to export a type library generated from a NGWS runtime assembly. The TlbExp utility generates a type library containing definitions of the public types defined in the NGWS runtime assembly named in AssemblyName.

Syntax

TlbExp AssemblyName [/out: TlbFile]
Option | Description
/out: file | Specifies the name of the type library file to be generated. If the option is omitted, the type library is generated with the same name as the assembly (the actual assembly name, not the name of the file containing the assembly), with the .tlb extension.
/silent | Prevents TlbExp from displaying a success message.
/verbose | Displays extra information.
/? or /help | Displays help for the tool.

Examples

The following example generates a type library with the name same name as the assembly found in mytest.dll.

TlbExp mytest.dll

This example generates the type library with the name clipper.tlb.

TlbExp mytest.dll /out clipper.tlb


Type Library Importer (TlbImp.exe)

The type library importer is responsible for converting the type definitions found within a COM type library into equivalent definition in NGWS runtime metadata format. Conversions are done for an entire type library at one time. You cannot use TlbImp to generate type information for a subset of the types defined within a single type library. The output of TlbImp is a binary file that contains NGWS runtime metadata for the types defined within the original type library. You can examine this file with tools such as Ildasm.exe.

Syntax

TlbImp TlbFile [/out: file] [/originator: file] [/keyfile: file][/keycontainer: name] [/unsafe] [/silent]
Option | Description
/out: file | Specifies the name of the output file that the metadata definitions will be written to. If the option is omitted, the metadata is written to a file with the same name as the type library (not the file but the actual library name within the file) defined within the input file with the .dll extension. If the output file is the same name as the input file and error is generated to prevent overwriting the type library.
/originator: file | Uses the originator key found in file to identity the resulting assembly. The originator key is generated from the public/private key pair supplied with the /keyfile or /keycontainer options if this option is not supplied. This allows an alternate originator key to be supplied to support developer key pair scenarios. The file is in the format generated by SN, a utility also available with the NGWS SDK.
/keyfile: file | Signs the resulting assembly with a strong name using the public/private key pair found in file. The key file should be in the formatted generated by the SN utility.
/keycontainer: name | Signs the resulting assembly with a strong name using the public/private key pair found in the key container specified by name.
/unsafe | Produces interfaces without runtime security checks.
/nologo | Prevents TlbImp from displaying a logo.
/silent | Prevents TlbImp from displaying a success message.
/verbose | Displays extra information.
/? or /help | Displays help for the tool.

Remarks

The /keyfile and /keycontainer options both allow assemblies to be strongly named. It only makes sense to supply one of them at a time.

Examples

The following example generates a metadata DLL with the same name as the type library found in mytest.dll and with the .dll extension.

TlbImp mytest.tlb

The following example generates an NGWS runtime metadata DLL with the name Mytest.dll.

TlbImp  mytest.tlb  /out: Mytest.dll

A resource ID can optionally be appended to the TlbFile when importing a type library from a module containing multiple type libraries.

TlbImp MyModule.dll\1

See Also

Generating NGWS Runtime Metadata | Exposing Unmanaged COM objects to the NGWS Runtime


Web Service Utility (WebServiceUtil.exe)

WebServiceUtil helps create ASP+ web services and web service clients.

Syntax

WebServiceUtil /command:proxy /path: [/language:] [/namespace:] [/out:] [/xsd: [...]]
WebServiceUtil /command:template /path: [/language:] [/namespace:] [/out:] [/xsd: [...]]
WebServiceUtil /command:makeSDL /baseurl: /assembly: [/out:]
WebServiceUtil /command:getSDL /url: [/out:]
Option | Description
getSDL | Get a service description file from a URL and saves it to a local directory.
makeSDL | Create static service description files for web services in an assembly.
proxy | Create source code for a proxy (web service client) class from a Service Description Language (SDL) file or assembly. The Service Description Language (SDL) is an XML grammar that developers and development tools can use to represent the capabilities of a Web Service.
template | Create source code for a template (web service server) class from an SDL file.
/assembly:<file> Short form: /a:<file> | The name of an assembly containing web services.
/baseurl:<base> Short form: /b:<base> | The base URL to the web service.
/command:<command> Short form: /c:<command> | The command to perform upon the specified path, XSD, or URI.
/language:<language> Short form: /l:<language> | The language to use for the generated proxy class. Choose from C#, Visual Basic, JScript, or any language with a supplied CodeGenerator. The default language is C#.
/namespace:<namespace> Short form: /n:<namespace> | The namespace for the generated proxy or template. The default namespace is the global namespace.
/out:<location> Short form: /o:<location> | The location at which to create files. The default output location is the current directory.
/path:<path> Short form: /pa:<path> | A local path to a service description file, or a URI that the service description file was retrieved from.
/url:<url> Short form: /u:<url> | A URL to a specific file.
/xsd:<xsd>,<...> Short form: /x:<xsd>,<...> | One or more local XML schema files. Filenames must end in .xsd.


Win Forms Class Viewer (wincv.exe)

The Win Forms class viewer allows you to quickly look up information about a class or series of classes based on a search pattern. The class viewer displays information by reflecting on the type using the NGWS runtime reflection API.

Start wincv.exe from the command line and type part of all of a type name into the text box at the top of the form. The listbox one the left hand side of the form will then display a list of all the types that wincv finds based on the name you entered. When you select a type in the type definition is displayed in the area on the right.

The Options button allows you to copy the contents of the display to the clipboard.

Syntax

wincv

Example

Start wincv.exe from the command line

Type “Button” into the text box at the top of the form

Select “System.WinForms.ButtonBase” from the list of types in the list box on the left hand side of the form.

The definition of System.WinForms.ButtonBase is shown in the area on the right.

See Also

NGWS Runtime IL Disassembler


Win Forms Designer Test Container (windes.exe)

The Win Forms Designer Test Container (WinDes) allows you to test the design time behavior of Win Forms controls that you have authored.

It hosts the Win Forms Form Designer and Property Browser. It allows you to add your control to a Form and view its properties in the property browser. This includes hosting any custom designers and custom UI Type Editors you have defined. This allows you to quickly and easily test the design-time behavior of your controls.

PDC Tech Preview Only: Refer to the WinForms QuickStart documentation for more information on using windes to test your controls.

Syntax

windes

See Also

© 2000 Microsoft Corporation. All rights reserved.


NGWS Runtime XML Schema Definition Tool (xsd.exe)

XSD is a tool that is useful when working with XML Schemas that follow the XML Schema Definition (XSD) language proposed by the W3C. XSD can perform the following operations:

  • XDR to XSD. Generate XML Schema from an XML-Data -Reduced schema file. XDR was an early XML-based schema format.
  • XML to XSD. Generate XML Schema from an XML file. This operation requires “inferring” a schema from the contents of the file.
  • XSD to DataSet. Generate NGWS runtime DataSet classes from an XSD schema file. The generated classes provide a rich object model for regular XML data.
  • XSD to Classes. Generate NGWS runtime classes from an XSD schema file. The generated classes can be used in conjunction with System.XML.Serialization.XMLSerializer to read and write XML that follows the schema.
  • Classes to XSD. Generate XML Schema files from a type in a NGWS runtime assembly file. The schema generated defines the XML format used by System.XML.Serialization.XMLSerializer.

For more information on XML Schema Definition proposal or the XML standard, see http://w3.org.

Syntax

Generic arguments to xsd.

Argument | Description
/? or /H[ELP] | Print help for the tool.
/O[UTPUTDIR]:directory | Specify the directory in which to place output files. This argument can appear only once.
xsd [options] file.xdr

If you specify an XDR Schema file (.xdr extension), XDR will convert the XDR schema to be an XSD schema. The output file will have the same name as the XDR schema, but will have an the extension .xsd.

xsd [options] file.XML

If you specify an XML file (.XML extension), XDR will “infer” a schema from the data in the file an produce an XSD schema. The output file will have the same name as the XML file, but will have an the extension .xsd.

xsd [options] file.xsd

If you specify an XML Schema file (.xsd extension), XSD will generate source code for NGWS runtime objects that correspond to the XML schema.

One (and only one) of the following options must be specified for .xsd files:

Argument | Description
/D[ATASET] | Generate a subclass of DataSet which corresponds to the specified schema. To read XML data into the subclass, use the System.Data.DataSet.ReadXMLData method.
/C[LASSES] | Generate classes corresponding to the specified schema. To read XML data into the object, use the System.XML.Serialization.XMLSerializer.Deserializer method.

The following options are optional:

Argument | Description
/E[LEMENT]:element | Specify the element in the schema to generate code for. By default all elements are typed. This argument can appear more than once.
/L[ANGUAGE]:language | Specify the programming language to use. Choose from C# or VB. This argument can appear only once.
/N[AMESPACE]:namespace | Specify the NGWS runtime namespace for the generated types. This argument can appear only once.
/U[RI]:uri | Specify the uri for the elements in the schema to generate code for. This uri, if present, applies to all elements passed in. This argument can appear only once.

The default language is VB. The default namespace is “Schemas”.

xsd [options] file.dll

If you specify a NGWS Runtime Assembly file (.exe, or .dll extension), XSD will generate schema(s) for one or more types in that assembly. The /TYPE option can used to specify which type(s) to generate schemas for. If /TYPE is not specified, then schema(s) will be generated for all types in the assembly. The output schema(s) are named schema0.xsd, schema1.xsd, etc. There will only be more than one schema output if the types specified have specified a namespace using the XMLRoot custom attribute.

Argument | Description
/T[YPE]:typename | Specifies the name of the type in the assembly that a schema should be created for. If the typename does not specify a namespace, which will match all types in the assembly with that type name. If the typename does specify a namespace, then only that type will match. If the typename ends with a * character, then all types that start with the string preceeding the * will be matched. This argument can appear more than once.

See Also

WebServiceUtil


Topic Not Found

No matching topic was found. The link may be out of date, incorrectly authored, or the topic may not be available in this release.

You may be able to find the topic by using the index or search tab instead.


Copyright

NGWS SDK Documentation

This is a preliminary document and may be changed substantially prior to final commercial release. This document is provided for informational purposes only and Microsoft makes no warranties, either express or implied, in this document. Information in this document, including URL and other Internet Web site references, is subject to change without notice. The entire risk of the use or the results of the use of this document remains with the user. Unless otherwise noted, the example companies, organizations, products, people and events depicted herein are fictitious and no association with any real company, organization, product, person or event is intended or should be inferred. Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Microsoft Corporation.

Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.

Unpublished work. © 1999 - 2000 Microsoft Corporation. All rights reserved.

Microsoft, MS-DOS, Windows, Windows NT, Active Directory, ActiveX, Authenticode, FrontPage, IntelliSense, JScript , Outlook, Visual Basic, Visual Basic Scripting Edition (VBScript), Visual C++, Visual Studio, and Win32 are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.

The names of actual companies and products mentioned herein may be the trademarks of their respective owners.