Chapter 6. Compiling and Building
Project files must be compiled and built before they can be used to generate an application to be deployed to the users. Before you compile and build a project or solution, you need to configure the various project properties and solution properties so that you can build your project or solution in desired ways.
Configuring project properties
This section describes how you can configure the C# project properties, including properties related to application, build, build events, package, debug and signing, so that you can build your projects in ways that best fit your needs.
Configuring C# project properties
To configure Properties settings for a C# project, right-click the project node in Solution Explorer, and then select Properties so that the Properties window pops up.
Application
The Application tab in the project designer allows you to specify the various application configurations, such as assembly name, target framework, output type, and ways of resources management.
The following settings allow you to specify some basic configurations for the application, including the assembly name, default namespace, target framework, output type, as well as the entry point when you start an application.
Assembly name
Designates the name of the output files that contain the assembly metadata. If it is changed here, the output assembly name will be changed too.
Default namespace
Specifies the base namespace for files newly added to the project.
Target framework
Defines the .NET version that your application targets. The dropdown list has different values depending on the .NET versions that are installed on your current machine. If your project targets .NET Core, you can choose one of the supported .NET Core versions listed in the section Targeting a framework.
Output type
Specifies the type of application to build. The output type varies depending on the type of project you create. For a Web application project, for example, you must select Console Application as the output type. For a Console App project, you can select from Windows Application, Console Application, or Class Library.
Startup object
Designates the entry point to be called when you start an application. The entry point is usually set either to the main form in your program or to the Main procedure that runs when you start the application. If your compilation has multiple types that contain a Main method, you can specify which type contains the Main method that you want to use as the entry point into the application. This property for class libraries defaults to (Not set) because they don’t have an entry point.
Assembly information...
This option allows you to edit the assembly information.
Title: Specifies the title of the assembly manifest.
Description: Enters a description about the assembly manifest.
Company: Specifies the company name of the assembly manifest.
Product: Specifies the product name of the assembly manifest.
Copyright: Specifies the copyright notice for the assembly manifest.
Trademark: The registered trademark of the specified assembly manifest.
Assembly Version: Specifies the version of the assembly.
File Version: Specifies the Win32 file version.
GUID: Generates a unique GUID for the assembly.
Neutral language : Specifies the language supported by the assembly.
Enable COM hosting: Specifies whether types in the assembly are available to COM.
Resources
The Resources settings allow you to specify how resources of your application will be managed.
Icon and manifest
The Icon and Manifest option is enabled by default. These settings allow you to select your own icon, or to select different manifest generation options. In most cases, you can rely on this radio button to manage your application resources. If you want to provide resource files for the project, select the Resource files radio button instead.
Icon
Designates the .ico file that you want to use as the icon for your application. Enter the name of the .ico file, or click Browse to select an existing icon. Note that this feature is available only for .NET Framework apps created outside SnapDevelop.
Manifest
Selects a manifest generation option when the application runs on Windows Vista under User Account Control (UAC). This option can have the following values:
- Embed manifest with default settings. This is the default option. It embeds security information into the executable file of the application, specifying that
requestedExecutionLevel
beAsInvoker
. - Create application without a manifest. This method is known as virtualization. Use this option for compatibility with earlier applications.
- Embed manifest with default settings. This is the default option. It embeds security information into the executable file of the application, specifying that
Use a custom manifest. Use this option to select a manifest locally.
Resource files
Select this radio button when you want to provide a resource file for the project. Enter a path name of a resource file or click Browse to add a Win32 resource file to the project.
Build
The Build settings allow you to configure the various build properties, such as conditional compilation symbols, target platform, warning and error treatment, as well as output management. To access these settings, click the Build tab in the project designer.
Configuration and platform
SnapDevelop currently supports two ways to build: Debug and Release, and the platform on which an application runs is set to Any CPU by default. Therefore, you can choose to perform the Debug configuration on any CPU or the Release configuration on any CPU. However, the Debug and Release options cannot be selected at the same time. The Configuration and Platform options make it possible for you to select the specific configuration and platform you want to display or modify.
Configuration
Specifies the configuration settings (Debug or Release) you want to display or modify.
Platform
By default, the platform is set to Any CPU, which means that you can build and deploy your application on any development platform.
Compilation symbols
Designates one or more symbols to perform conditional compilation. Use a semi-colon or comma to separate symbols if you specify multiple symbols here. If you designate a conditional compilation symbol here, you can use the symbol to compile your project-wide source files conditionally without having to define such a symbol in individual files.
The -define option defines names as symbols in all source code files in your program. The -define option is equivalent to a #define preprocess directive except that this option is applicable for all files in your project. A symbol specified here remains defined unless otherwise undefined using an #undef directive. If you use the -define option, an #undef directive in one file has no project-wide effect.
You can use symbols created by this option with #if, #else, #elif, and #endif to perform conditional compilation for the source files in your project.
For example, if you have created a Console App using SnapDevelop and you enter ABC; HelloWorld in the Conditional compilation symbols box, you can set the project compilation conditions in the .cs file in Solution Explorer.
class Program { static void Main(string[] args) { #if (ABC) Console.WriteLine("ABC"); #else Console.WriteLine("Hello World!"); #endif #if (HelloWorld) Console.WriteLine("Hello World!"); #else Console.WriteLine("Hello World!"); #endif Console.ReadKey(); } }
If you run the application, you will get the following output.
If you un-define ABC using an #undef directive and then run your application again,
#undef ABC using System; using System.Collections.Generic; using System.Linq; using System.Threading.Tasks; namespace ConsoleApp1 { class Program { static void Main(string[] args) { #if (ABC) Console.WriteLine("ABC"); #else Console.WriteLine("Hello World!"); #endif #if (HelloWorld) Console.WriteLine("Hello World!"); #else Console.WriteLine("Hello World!"); #endif Console.ReadKey(); } } }
you will get the following output:
Define DEBUG constant
Select this option to treat DEBUG as a constant symbol in all source code files in your project. Enabling this option has the same effect as entering DEBUG in the Conditional compilation symbols box.
Define TRACE constant
Select this option to treat TRACE as a constant symbol in all source code files in your project. Enabling this option has the same effect as entering TRACE in the Conditional compilation symbols box.
Platform target
Designates the processor on which the output file is to run.
Select Any CPU if you want your output file to run on any processor;
Select x86 if you want it to run on any 32-bit Intel-compatible processor;
Select x64 if you want it to run on any 64-bit Intel-compatible processor;
Select ARM32 if you want your output file to run on any 32-bit ARM-compatible processor;
Select ARM64 if you want your output file to run on any 64-bit ARM-compatible processor.
Prefer 32-bit
If you enable this option, your application runs as a 32-bit application on both 32-bit and 64-bit Windows operating systems. If you disable this option, your application runs as a 32-bit application on 32-bit Windows operating systems and as a 64-bit application on 64-bit Windows operating systems. Note that the Prefer32-bit option is available only if the Platform target list is set to Any CPU. This option is not available for Class Library projects.
If you run an application as a 64-bit application, the pointer size doubles, and incompatibility may occur with other libraries that are exclusively 32-bit. Run a 64-bit application only if the application requires over 4 GB of memory or 64-bit instructions significantly improve performance.
Allow unsafe code
Allows code that uses the unsafe keyword to compile. By default, C# does not support pointer arithmetic in order to ensure type security. However, you can use the unsafe keyword to define an unsafe context in which pointers can be used. Unsafe code has the following properties:
- Unsafe code can be types, methods, or code blocks.
- Unsafe code may improve an application’s performance by removing array bounds checks.
- Unsafe code must be compiled with the unsafe compiler option.
- Unsafe code causes security problems.
- Unsafe code is necessary when you call native functions that require pointers.
Optimize code
If you enable this option, the C# compiler optimizes your code by making your output files smaller, faster, and more efficient.
Errors and warnings
The following settings configure the error and warning options when you are building your project.
Warning level
Specifies the warning level for the compiler to display. The warning levels range from 0 to 4. Higher warning levels show more warnings while lower warning levels show more serious warnings. The following table illustrates the meanings of individual warning levels.
Warning Level Description 0 Does not show any warning messages. 1 Shows serious warning messages. 2 Shows level 1 warnings and less serious warnings. 3 Shows level 2 warnings and less serious warnings. 4 Shows all level 3 warnings plus informational warnings. Suppress warnings
Blocks the generation of one or more warnings. Use semi-colon or comma to separate warning numbers if there is more than one warning, for example, 1701;1702.
Treat warnings as errors
The following settings allow you to determine which warnings are treated as errors.
None
Treats no warnings as errors.
All
Treats all warnings as errors.
Specific warnings
Treats specific warnings as errors. Use a semi-colon or comma to separate warning numbers if you want to specify multiple warnings as errors.
Output
The following settings allow you to specify the output configuration for the build process.
Output path
Designates the path of the output files. Select Browse to specify a path, or directly enter a path in this box. If you don’t specify a path, the compiled files will be output into the default path, which is bin\Debug or bin\Release\.
XML documentation file
Designates the name of a file which contains documentation comments. If you enable this option and build your project, you will see a .xml file in Solution Explorer. For example,
Conditional compilation symbol
You can define a Conditional compilation symbol here and use the #if directive to conditionally compile code when the corresponding Conditional compilation symbol is defined.
Generate serialization assembly
Specifies whether the compiler will use the XML Serializer Generator Tool (Sgen.exe) to create XML serialization assemblies. Serialization assemblies can improve the startup performance of XmlSerializer if you have used that class to serialize types in your code.
By default, this option is set to Auto, which specifies that serialization assemblies be generated only if you have used XmlSerializer to encode types in your code to XML.
Off specifies that serialization assemblies never be generated, regardless of whether your code uses XmlSerializer.
On specifies that serialization assemblies always be generated. Serialization assemblies are named TypeName.XmlSerializers.dll.
Advanced
The Advanced dialog box allows you to specify advanced build configurations, including the version of a programming language, the way compiler errors are reported, debugging information, file alignment, as well as library base address.
Language version
Designates the version of the programming language to use. Each version has its own specific features. This option makes it possible for you to force the compiler to enable some of the implemented features, or to allow only the features that are compatible with an existing standard. The following table displays the various language versions that are currently available in the SnapDevelop compiler.
Language Version Meaning C# latest major version (default) The compiler recognizes all valid language syntax from the latest major version that it can support. C# latest minor version (latest) The compiler recognizes all valid language syntax from the latest minor version that it can support. ISO-1 The compiler only recognizes syntax included in ISO/IEC 23270:2003 C# (1.0/1.2). ISO-2 The compiler only recognizes syntax included in ISO/IEC 23270:2006 C# (2.0). C# 3 The compiler only recognizes syntax included in C# 3.0 or earlier versions. C# 4 The compiler only recognizes syntax included in C# 4.0 or earlier versions. C# 5 The compiler only recognizes syntax included in C# 5.0 or earlier versions. C# 6 The compiler only recognizes syntax included in C# 6.0 or earlier versions. C# 7 The compiler only recognizes syntax included in C# 7 or earlier versions. C# 7.0 The compiler only recognizes syntax included in C# 7.0 or earlier versions. C# 7.1 The compiler only recognizes syntax included in C# 7.1 or earlier versions. C# 7.2 The compiler only recognizes syntax included in C# 7.2 or earlier versions. C# 7.3 The compiler only recognizes syntax included in C# 7.3 or earlier versions. C# 8.0 The compiler only recognizes syntax included in C# 8.0 or earlier versions. C# 9.0 The compiler only recognizes syntax included in C# 9.0 or earlier versions. Internal compiler error reporting
Specifies whether to report internal compiler errors.
The Prompt is selected by default, which means that you will receive a prompt if any compiler error occurs.
If you select None, the error will be reported only in the output of the text compiler.
If you select Send, an error report will be sent automatically.
If you select Queue, error reports will be queued.
Check for arithmetic overflow/underflow
Specifies whether runtime exceptions occur if an integer arithmetic statement exceeds the scope of the checked or unchecked keywords and leads to a value that exceeds the range of the data type.
Debugging information
Determines the type of debugging information that is generated by the compiler. The following table displays the various types of debugging information and their respective meanings.
Type Description Full Generates debugging information to .pdb file, and attaches a debugger to the running program. None Does not generate debugging information. PdbOnly Generates debugging information to .pdb file and allows debugging when the program is started in the debugger, but only displays assembler when the running program is attached to the debugger. Portable Generates a .pdb file. Embedded Inserts portable symbol information into the assembly. Do not generate the .pdb file. File alignment
Determines the size of the output file. You can select any value, measured in bytes, from the dropdown list, which includes 512, 1024, 2048, 4096, and 8192. The size of the output file is determined by aligning a section on a boundary that is a multiple of this value.
Library base address
Designates the preferred base address where a DLL can be loaded. The default base address for a DLL is specified by the .NET Framework common language runtime.
Build events
The Build Events settings allow you to specify build configuration instructions and specify the conditions for the running of post-build events. To access these settings, click the Build Events tab in the project designer.
Pre-build event command line
Allows you to write commands to execute before the build starts. If you want to write long commands, you can enter your commands in the Pre-build Event Command Line input box that pops up when you click Edit Pre-build.
The command line input boxes allow you to insert a variety of macros, which are case-insensitive, and which can be used to designate locations for files or to get the actual name of the input file.
Appendix B: List of Pre-build and Post-build Macros lists and explains the macros that you can add in the command line.
Post-build event command line
Allows you to write commands to execute after the build finishes. If you want to write long commands, you can enter your commands in the Post-build Event Command Line input box that pops up when you click Edit Post-build.
The command line input boxes allow you to insert a variety of macros, which are case-insensitive, and which can be used to designate locations for files or to get the actual name of the input file.
Appendix B: List of Pre-build and Post-build Macros lists and explains the macros that you can add in the command line.
Run the post-build event
Specifies the conditions for the running of the post-build events. The following table lists the various conditions and the results of applying these conditions.
Option Result Always Post-build events will run regardless of the condition. On successful build Post-build events will run if a project is successfully built. When the build updates the project output Post-build events will run only if the compiler's output files (.exe files or .dll files) differ from the previously compiled files.
Package
The Package settings allow you to configure the various package properties, such as package generation, package ID, package version, package author, output path, as well as all details about the package. To access these settings, click the Package tab in the project designer.
Generate NuGet package on build
If you enable this option, you can use SnapDevelop to automatically generate the NuGet package when you build the project. You can meaningfully configure the various package properties only if the Generate NuGet Package on Build option is enabled.
Require license acceptance
If you enable this option, you will be asked whether to accept the package license before you install a particular package.
Packaging options
The following table lists the variety of package properties and the meanings of individual package properties.
Property Description Package ID A unique and case-insensitive package identifier. IDs generally follow the .NET namespace naming conventions and do not allow spaces or characters, which are invalid for a URL. Package version The version of the package. Authors The author(s) of a package. Use comma to separate authors if the package is created by a group of authors. Company The creator(s) of a package. Use comma to separate creators if there are several creators. Product The name of the product. Description A general description of the package. Copyright Copyright details for the package. Project URL URL for the package's home page. Icon URL URL for an image used as the icon of the package. Repository URL URL for the repository. Repository type The type of the currently used repository. Tags Keywords that represent the characteristics of a package and that may help you find the particular package on nuget.org. Release notes A description of the changes made in the current release package. Assembly neutral language Specify the assembly neutral language of the project. Assembly version Each assembly has a unique version number that represents its identity and this version number consists of four parts: <major version>.<minor version>.<build number>.<revision>. Assembly file version A version number given to file as in file system. Licensing Specify the license expression or the path of the license file.
Debug
The Debug settings allow you to specify how the SnapDevelop debugger behaves in a C# project. To access these settings, click the Debug tab in the project designer.
The following table lists the debug options you can configure for your application and explains the meaning of each option.
Profile -- Displays the currently active project. You can click New to add a new project for which you want to configure the start options. Or you can click Delete to remove a project from the dropdown list.
Launch -- Specifies the launch action when you select Start from the Debug menu.
- If you select Project, which is the default option, the debugger launches the startup project for debugging.
- If you select Executable, the debugger launches and attaches to an executable (for Windows/Console Application projects) outside SnapDevelop when you debug the application. If you select the Executable option, you will be asked to provide a path to the executable to run in the Execute file input box that follows immediately on the next line.
- Docker -- If you choose Docker, you need to configure the Docker engine and choose whether to start a browser.
- KubernetesCompose -- If KubernetesCompose is selected, the project will be started and compiled in the KubernetesCompose environment.
- Kubernetes -- If you select Kubernetes, you can further set whether to start the browser and change Kubernetes related settings, such as cluster source, cluster context, namespace, container engine, storage warehouse, etc.
Application arguments -- Specifies command line arguments for the application being debugged.
Working directory -- Specifies the working directory of the application being debugged. By default, the working directory for C# applications is \bin\debug.
Environment Variables -- .NET Core reads environment variables stored in the launchSetting.json file when you start your application. You can set the environment to any value, but .NET Core supports three common values: Development, Staging, and Production.
- Development: The development environment can enable features that cannot be enabled in the production environment.
- Staging: The staging environment is primarily used to test all install/config/migration scripts and procedures before applying them to production. Additionally, staging is used to run performance tests, especially load tests, which are often environment-sensitive.
- Production: Choose a production environment to maximize security, performance, and application robustness. A production environment differs from a development environment in many ways: such as caching; client-side resources are bundled, reduced, and possibly served by a CDN; diagnostic error pages are disabled; friendly error pages are enabled; production logging and monitoring are enabled. Note that if no environment is set, it defaults to Production.
Signing
The Signing settings allow you to sign the application and deployment manifests and also to sign the strong name assembly. To access these settings, click the Signing tab in the project designer.
Sign the assembly
You can enable this check box to sign the assembly and create a strong name key file. Enabling this option allows you to sign the assembly using the Al.exe tool supported by the Windows Software Development Kit (SDK).
Choose a strong name key file
You can specify a new or existing strong name key file that can be used to sign the assembly. Select New to create a new key file or Browse to choose an existing one. If you select New, the Create Strong Name Key dialog box pops up, which allows you to designate a key file name and protect the key file with a password. The password must be at least six characters in length. If you specify a password, a Personal Information Exchange (.pfx) file is created. If you don’t specify a password, a Strong Name Key (.snk) file is created. The two types of files are briefly introduced in the following table.
If you build a project with one of the key files created, the created file will be used to sign the assembly.
File Type Description .pfx file Contains certificate and its public and private keys. It is used for code signing and serves to prevent malicious tampering with assemblies distributed publicly. .snk file Contains the strong key. It is used for strong-naming, which uses a key pair to uniquely identify an assembly. Delay sign only
You can enable this check box to delay assembly signing. If you enable this option, your project cannot be debugged and will not run. However, you can use the strong name tool (Sn.exe) with the
-Vr
option to skip verification during development.
You can view the components (for example, .dll files) in the compiled project files to check if an assembly is signed.
This image indicates that an assembly is signed.
This image indicates that an assembly is not signed (probably because the Sign the assembly option is not enabled).
If you enable the Delay sign only option, you will obtain the public key but the assembly is currently not signed.
Configuring solution properties
A solution configuration specifies how projects in the solution are to be built. To configure the Solution Properties, right-click your solution node in Solution Explorer, and then select Properties so that the Solution Properties dialog box pops up.
Startup project
The Startup Project options allow you to specify which project to run when you launch the SnapDevelop debugger. To configure the Startup Project settings, expand the Common Properties node, and then select Startup Project.
Current selection
Enable this option if you want the current project to run when you launch the SnapDevelop debugger.
Single startup project
Enable this option if you want any project to run when you launch the SnapDevelop debugger.
Project dependencies
When you build a solution, you need to build some projects first in order to generate executable code that can then be used by the other projects. The Project Dependencies settings allow you to determine the desired build order for projects in your solution. To configure the Project Dependencies settings, expand the Common Properties node, and then select Project Dependencies.
Projects
The dropdown list has all projects in your solution. You can select any project that uses executable code generated by another project or other projects.
Depends on
You can select any project that generates executable code used by the project you selected in the Projects dropdown list.
Note that circular dependency is not allowed. For example, if project A depends on project B, which in turn depends on project C, then project C cannot depend on project A or project B and project B cannot depend on project A.
Please also note that the projects selected on the Depends on pane may not be actually built. Whether the projects are built or not depends on the selection of the check boxes for the projects in the active solution build configuration.
Configuration properties
The Configuration Properties settings allow you to manage the various properties for the entire solution. You can decide whether to build a particular project, and what configuration of a particular project to build on what development platform. To configure the Configuration Properties settings, expand the Configuration Properties node, and then select Configuration.
Configuration manager
When you click Configuration Manager... in the Solution Properties dialog, the Configuration Manager dialog box displays and allows you to create and specify configurations and platforms at both the solution level and the project level.
Active solution configuration
Specifies what configuration is built at the solution level when you select Build Solution on the Build menu. You can select one of the two default configurations - Debug and Release, or you can add new ones. If you realize that an existing configuration name is not appropriate, you can rename it. If you do not need a particular configuration anymore, you can remove it from the Active Solution Configuration box. This will remove all solution and project configurations you specified for that combination of configuration and platform.
To add a new configuration:
Select <New> from the Active Solution Configuration box.
Enter a name for the new configuration on the New Solution Configuration window.
Select a configuration from the Copy settings from box if you want to use the settings from an existing solution configuration or select <Empty> otherwise.
Select the Create new project configurations check box if you want to create project configurations simultaneously.
To rename a solution configuration:
Select <Edit> from the Active Solution Configuration box.
Select the configuration you want to modify on the Edit Solution Configurations window.
Click Rename and then enter a new name.
To remove a solution configuration:
Select <Edit> from the Active Solution Configuration box.
Select the configuration you want to remove on the Edit Solution Configurations window.
Click Remove.
Active solution platform
Specifies the solution-level development platform you want your solution to target. The development platform defaults to Any CPU, but you can also create new platforms. If you realize that an existing platform name is not appropriate, you can rename it. If you do not need a particular platform anymore, you can remove it from the Active Solution Platform box. This will remove all solution and project configurations you specified for that combination of configuration and platform.
To create a new solution platform:
Select <New> from the Active Solution Platform box.
Select a new platform (x64 or x86) from the Type or select the new platform box.
Select a platform from the Copy settings from box if you want to use the settings from an existing solution platform or select <Empty> otherwise.
Select the Create new project configurations check box if you want to create project platforms simultaneously.
To rename a solution platform:
Select <Edit> from the Active Solution Platform box.
Select the platform you want to modify on the Edit Solution Platforms window.
Click Rename and then enter a new name.
To remove a solution platform:
Select <Edit> from the Active Solution Platform box.
Select the platform you want to remove on the Edit Solution Configurations window.
Click Remove.
Project contexts
Although the combination of configuration and development platform has been specified at the solution level when you specify active solution configuration and active solution platform, Project Contexts allows you to finally decide whether to build a particular project, and what configuration of the project to build on what development platform. The following table lists the various project contexts and their respective meanings.
Item | Description |
---|---|
Project | Lists all projects in your solution. |
Language | The programming language used in this project. |
Configuration | Lists the type of build currently active for each project. You can select Debug, Release, or any custom configuration from the dropdown list. You can perform the same operations as you set the active solution configuration. But the configurations you specify here are applicable project-wide only. |
Platform | Selects the development platform you want your project to target. You can perform the same operations as you set the active solution platform. But the platform you select here applies project-wide only. |
Build | Specifies whether to include a particular project when you build the solution. The check boxes for all projects are selected by default, but you can uncheck the box(s) for the project(s) you don’t want to build. |
Configuration
Displays the results of your setting of the Active Solution Configuration in Configuration Manager.
Platform
Displays the results of your configuration of the Active Solution Platform in Configuration Manager.
Project contexts
Displays the results of your configuration of the project contexts in Configuration Manager. Note that the configurations specified in Configuration Manager can be modified here. The modifications made here are equivalent to those made in Configuration Manager. If you have modified the project contexts properly, you need to click Apply to validate such modifications.
Building, rebuilding, or cleaning projects and solutions
After you have configured the project properties and solution properties, you can then build, rebuild, or clean the projects and solutions.
Building, rebuilding, or cleaning a single project
You can take the following steps to build, rebuild, or clean a single project.
Select the node of a project you want to build/rebuild/clean in Solution Explorer.
Select Build on the menu bar, and then select one of the following options:
Option Description Build ProjectName Compiles only the project files that have changed since the project was most recently built. Rebuild ProjectName Cleans the project and then builds all project files. Clean ProjectName Removes all compiled project files (such as .dll files and .exe files).
Building, rebuilding, or cleaning an entire solution
You can take the following steps to build, rebuild, or clean an entire solution.
Select the solution node in Solution Explorer.
Select Build on the menu bar, and then select one of the following options:
Option Description Build Solution Compiles only the solution files that have changed since the solution was most recently built. Rebuild Solution Cleans the solution and then builds all solution files. Clean Solution Removes all compiled solution files (such as .dll files and .exe files).