Shared Source C# 2.0 Compiler (csc.exe)

The @ option lets you specify a file that contains compiler options and source code files to compile. These compiler options and source code files will be processed by the compiler just as if they had been specified on the command line.

To specify more than one response file in a compilation, specify multiple response file options.

For example:

@file1.rsp @file2.rsp

In a response file, multiple compiler options and source code files can appear on one line. A single compiler option specification must appear on one line (it cannot span multiple lines). Response files can have comments that begin with the # symbol.

Specifying compiler options from within a response file is just like issuing those commands on the command line.

The compiler processes the command options as they are encountered. Therefore, command-line arguments can override previously listed options in response files. Conversely, options in a response file will override options listed previously on the command line or in other response files.

This option sends a listing of compiler options, and a brief description of each option, to stdout. If this option is included in a compilation, no output file will be created and no compilation will take place.

All modules added with /addmodule must be in the same directory as the output file at run time. That is, you can specify a module in any directory at compile time but the module must be in the application directory at run time. If the module is not in the application directory at run time, you will get a System.TypeLoadException.

file cannot contain an assembly. For example, if the output file was created with /target:module, its metadata can be imported with /addmodule.

If the output file was created with a /target option other than /target:module, its metadata cannot be imported with /addmodule but can be imported with /reference.

The loading base address is only relevant if the file is going to be run on the .NET Framework on Windows.  Differences in loading behavior can occur in the .NET Framework on Windows depending on the version of the Windows operating system.

The SSCLI implementation ignores base address information stored in the PE assembly file. 

For information on the PE format of files loaded by ECMA CLI implementations see the ECMA-335 Common Language Infrastructure specification, Partition II, section 24.

For more information on DLL base addresses in Windows, go to msdn.microsoft.com and search for "dll base address". The Microsoft Windows Platform SDK tool Rebase.exe documentation and the Microsoft Visual Studio Linker.exe documentation also provide detailed information.

The /checked option specifies whether an integer arithmetic statement that is not in the scope of the checked or unchecked keywords and that results in a value outside the range of the data type shall cause a run-time exception.

An integer arithmetic statement that is in the scope of the checked or unchecked keywords is not subject to the effect of the /checked option.

If an integer arithmetic statement that is not in the scope of the checked or unchecked keywords results in a value outside the range of the data type, and /checked+ (the default if an option is not specified) is used in the compilation, then that statement will cause an exception at run time. If /checked- is used in the compilation, then that statement will not cause an exception at run time.

If you compile one or more source code files that were not created to use the default code page on your computer, you can use the -codepage option to specify which code page should be used.

If the source code files were created with the same codepage that is in effect on your computer or if the source code files were created with UNICODE or UTF-8, you need not use /codepage.

The /debug option causes the compiler to generate debugging information and place it in the output file. Use this option to create debug builds. If /debug, /debug+, or /debug:full is not specified, you will not be able to debug the output assembly at the source code level.

Options values:

+ | -

Specifying +, or just /debug, causes the compiler to generate debugging information and place it in a program database (.ildb file). Specifying -, which is in effect if you do not specify /debug, prevents debug information from being created.

full | pdbonly

These arguments specify the type of debugging information generated by the compiler. The full argument, which is in effect if you do not specify /debug:pdbonly, enables attaching a debugger to the running program. Specifying pdbonly allows source code debugging when the program is started in the debugger, but will display CIL only when the running program is attached to the debugger.

The /define option defines name as a symbol in your program. It has the same effect as using a #define preprocessor directive in your source file. A symbol remains defined until an #undef directive in the source file removes the definition or the compiler reaches the end of the file.

You can use symbols created by this option with #if, #else, #elif, and #endif to compile source files conditionally. 

The short form of /define is /d.

You can define multiple symbols with /define by using a semicolon or comma to separate symbol names.

For example:

/define:DEBUG;TUESDAY

The information stored in the PE file as the result of using this option is not used on the SSCLI implementation of the CLI assembly loader.

By default, errors and warnings that result from compilation specify the name of the file in which an error was found. The /fullpaths option causes the compiler to specify the full path to the file.

This option sends a list of compiler options, and a brief description of each option, to stdout. If this option is included in a compilation, no output file will be created and no compilation will take place.

The /incremental compiler option enables the incremental compiler, which compiles only those methods that have changed since the last compilation. Information about the state of the previous compilation is stored in the following file, which is created by the compiler:

output_file_name.dbg

When compiling with /debug, the status of debug information is stored in the program database (.ildb file).

Information about the status of the compilation, other than debug information, is stored in an .incr file. For example:

output_file_name.extension.incr

The first time you use /incremental, the .incr and .ildb files are fully updated and all subsequent compilations will be incremental. Changing the compiler options from the previous /incremental compilation will cause a full rebuild of the .incr and .ildb files.

If the compiler detects many changes since the last incremental build, it might perform a full build, as a full build would be at least as efficient as an incremental build. If the compiler cannot find the project's .ildb or .incr files, a full rebuild will occur.

By default, /incremental- is in effect. Specifying /incremental is the same as specifying /incremental+.

Output files created with the /incremental option might be larger than those created with incremental compilation disabled. Because the output files can be larger, you should use /incremental- in the final build of your output file.

This option will speed compilation on projects with many, smaller files, and will have little or no speed improvement on projects with a few large files.

Separate additional directory names with a comma.

The /lib option specifies the location of assemblies referenced through the /reference option.

The compiler searches for assembly references that are not fully qualified in the following order:

1. The current working directory. This is the directory from which the compiler is invoked.
2. The common language runtime system directory.
3. Directories specified by /lib.
4. Directories specified by the LIB environment variable.

Use /reference to specify an assembly reference.

/lib is additive; specifying it more than once appends to any prior values.

An alternative to using /lib is to copy into the working directory any required assemblies; this will allow you to simply pass the assembly name to /reference. After compilation you can delete the assemblies from the working directory. Since the assembly references store only the assembly name and do not specify a path, the application can be started on the target computer and will find and use the assembly in the global assembly cache.

The default identifier is the file name.

The /linkresource option creates a link to a resource in the output file; the resource file is not placed in the output file. The /resource option embeds a resource file in the output file.

Linked resources are public in the assembly when created with the C# compiler.

/linkresource requires one of the /target options other than /target:module.

If filename is a .resource file created by resgen.exe or in the development environment, for example, it can be accessed with members in the System.Resources namespace. For all other resources, use the GetManifestResource* methods in the System.Reflection.Assembly class to access the resource at run time.

/linkres is the short form of /linkresource.

The /nologo option suppresses the display of the sign-on banner when the compiler starts up and suppresses the display of informational messages during compiling.

The /nostdlib option prevents the import of mscorlib.dll, which defines the entire System namespace. Use this option if you want to define or create your own System namespace and objects.

This option is used by the SSCLI build system in order to bootstrap the build of the base class libraries in mscorlib.dll.

If you do not specify /nostdlib, mscorlib.dll will be imported into your program just as when you specify /nostdlib-. If you specify /nostdlib, it is the same as specifying /nostdlib+.

The /noconfig option tells the compiler not to compile with the global or local versions of csc.rsp.

By default, the C# compiler looks in the compiler directory and then in the directory from which the compiler was invoked for files called csc.rsp.

The csc.rsp file that is supplied in the compiler directory references the .NET Framework assemblies that would be included in a C# project created in the Visual Studio .NET development environment. You can modify this global csc.rsp file to contain any other compiler options that you want to include in a compilation from the command line with csc.exe.

The compiler will then look for a csc.rsp file in the directory from which the compiler was invoked. The commands in the local csc.rsp file will be combined with the global csc.rsp file for the compilation. Because the global csc.rsp is processed first, any command that is also in the local csc.rsp file will override the setting of the same command in the global csc.rsp file.

Finally, the compiler will read the options passed to the csc command. Because these are processed last, any option on the command line will override a setting of the same option in either of the csc.rsp files.

If you do not want the compiler to look for and use the settings in the global and local csc.rsp files, specify /noconfig.

The /nowarn option lets you suppress the compiler's ability to generate one or more warnings. Separate multiple warning numbers with a comma.

You need to specify only the numeric part of the warning identifier. For example, if you want to suppress CS0028, you could specify /nowarn:28.

The /optimize option enables or disables optimizations performed by the compiler to make your output file smaller, faster, and more efficient. /optimize also tells the common language runtime to optimize code at runtime.

By default, /optimize is in effect. Specifying /optimize is the equivalent to specifying /optimize+.

All references (see /reference) in an assembly must have the same optimization settings.

To prevent the compiler from generating an optimized output file, specify /optimize-.

/o is the short form of /optimize.

It is possible to combine the /optimize and /debug options.

The /out option specifies the name of the output file. The compiler expects to find one or more source code files following the /out option.

If you do not specify the name of the output file:

• An .exe file will take its name from the source code file that contains the Main method.
• A .dll or .netmodule file will take its name from the first source code file.

On the command line, it is possible to specify multiple output files for your compilation. All source code files specified after an /out option will be compiled into the output file specified by that /out option. A source code file used to compile one output file cannot be used in the same compilation to compile another output file.

Specify the full name and extension of the file you want to create.

If dir is not specified, the search begins in the directory where the csc command was executed.

The /recurse option lets you compile source code files in all child directories of either the specified directory (dir) or the directory where the csc command was executed.

You can use wildcard characters in a file name to compile all matching files in the project directory without using /recurse.

The /reference option causes the compiler to make public type information in the specified files available to the project you are currently compiling.

The file or files you import must contain a manifest; the output file must have been compiled with one of the /target options other than /target:module.

Use /addmodule to import metadata from an output file that does not contain an assembly manifest.

Although executable files can be referenced as assemblies it is not recommended that shared, referenced code be stored in executable assemblies. Instead, place the shared code in an assembly library.

If you reference an assembly (Assembly A), which itself references another assembly (Assembly B), you will need to reference Assembly B if:

• A type you use from Assembly A inherits from a type or implements an interface from Assembly B.
• You invoke a field, property, event, or method that has a return type or parameter type from Assembly B.

Use /lib to specify the directory in which one or more of your assembly references is located. The /lib topic also discusses which directories the compiler searches for assemblies.

/r is the short form of /reference.

The default identifier is the file name.

Use /linkresource to link a resource to an assembly rather than placing the resource file in the output file.

Resources are public in the assembly when created with the C# compiler.

If filename is an SSCLI resource file created, for example, by resgen.exe, it can be accessed with members in the System.Resources namespace (for more information see System.Resources.ResourceManager). For all other resources, use the GetManifestResource* methods in the System.Reflection.Assembly class to access the resource at run time.

/res is the short form of /resource.

Unless you specify /target:module, /target causes assembly metadata to be placed in an output file.

The assembly manifest is placed in the first .exe output file in the compilation or in the first DLL, if there is no EXE output file. For example, in the following command line, the manifest will be placed in 1.exe:

csc /out:1.exe t1.cs /out:2.netmodule t2.cs

The compiler creates only one assembly manifest per compilation. Information about all files in a compilation is placed in the assembly metadata. All output files except those created with /target:module can contain an assembly manifest. When producing multiple output files at the command line, only one assembly manifest can be created and it must go into the first output file specified on the command line. If the first output file is an executable assembly (/target:exe or /target:winexe) or code library (/target:library), then any other output files produced in the same compilation must be modules (/target:module).

If you create an assembly, you can indicate that all or part of your code is CLS-compliant with the CLSCompliant attribute.

Specify the format of the output file using one of four options:

This information is ignored by the SSCLI implementation of the CLI. However, if the application is executed under the .NET Framework this option will be significant. For more information on the console or Windows subsystem setting see http://msdn.microsoft.com and search for "console subsystem".

Use /target:exe to create a console application.

Unless otherwise specified with the /out option, the output file name takes the name of the input file that contains the Main method.

When specified at the command line, all files until the next /out or /target option are used to create the Windows application.

Only one Main method is required in the source code files that are compiled into an .exe file. The /main option lets you specify which class contains the Main method, in the case where your code has more than one class with a static Main method.

In some international configurations, compiler output cannot correctly be displayed in the console. In these configurations, use /utf8output and redirect compiler output to a file.

option is the minimum warning level you want displayed for the build.

Valid values are 0-4.

The /warnaserror+ option treats all warnings as errors. Any messages that would ordinarily be reported as warnings are instead reported as errors, and the build process is halted (no output files are built).

By default, /warnaserror- is in effect and causes warnings to permit the generation of an output file. /warnaserror, which is equivalent to /warnaserror+, causes warnings to be treated as errors.

Use /warn to specify the level of warnings that you want the compiler to display.