Including Light.GuardClauses as source code

Light.GuardClauses is not only available as a NuGet package / DLL, but also as a single source code file. This should be especially interesting for framework / library developers that do want to use Light.GuardClauses in their projects but not depend on the DLL.

There are two ways to grab the sources.

Copying the source code of the .NET Standard 2.0 version

A default source code version is published as part of this repository. Simply copy the contents of Light.GuardClauses.SingleFile.cs in the top level directory of this repo. This file is always updated when a new version of Light.GuardClauses is released.

This default single-source code file has the following preferences:

• All types use the internal modifier. This way the source code of Light.GuardClauses does not extend your own API
• The source code is compliant with .NET Standard 2.0.
• The source codes uses Nullable Reference Types.
• ReSharper Contract Annotations are included

Depending on your target framework, you might need to reference the following NuGet packages:

• System.Runtime.CompilerServices.Unsafe: the Unsafe.As method is used in Light.GuardClauses. This is usually required when targeting .NET Standard.
• System.Memory: Light.GuardClauses also provides assertions for Span<T> and ReadOnlySpan<T>.

If this doesn't fit your needs, you can generate your custom single-source-code file.

Generating a custom single-source-code file

The Light.GuardClauses.SourceCodeTransformation project can be configured to customize the output of the single-source-code file. You can either create a JSON file called "settings.json" right besides the csproj file of this project, or you can configure the generator via command line arguments (the generator uses Microsoft.Extensions.Configuration internally). The default structure of this JSON file looks like this:

{
    "changePublicTypesToInternalTypes": true,
    "baseNamespace": "Light.GuardClauses",
    "removeContractAnnotations": false,
    "includeJetBrainsAnnotationsUsing": true,
    "includeJetBrainsAnnotations": true,
    "includeVersionComment": true,
    "removeOverloadsWithExceptionFactory": false,
    "includeCodeAnalysisNullableAttributes": true,
    "includeValidatedNotNullAttribute": true,
    "removeValidatedNotNull": false,
    "removeDoesNotReturn": false,
    "removeNotNullWhen": false,
    "includeCallerArgumentExpressionAttribute": true,
    "removeCallerArgumentExpressions": false
}

Here is a description of all possible parameters (the names are case-insensitive):

Parameter	Type	Default Value	Description
BaseNamespace	string	"Light.GuardClauses"	Changes the namespace where all types of Light.GuardClauses will be part of.
ChangePublicTypesToInternalTypes	bool	true	This value indicates whether all types should be changed from public to internal. This way, Light.GuardClauses will not extend your API.
RemoveContractAnnotations	bool	false	This value indicates whether the ContractAnnotationAttributes should be removed from the assertions and methods of Light.GuardClauses. This attribute helps ReSharper analyzing possible null references.
IncludeJetBrainsAnnotations	bool	true	This value indicates whether the definition of the ContractAnnotationAttribute should be included at the end of the generated source file.
IncludeJetBrainsAnnotationsUsing	bool	true	This value indicates whether the using JetBrains.Annotations statement should be included at the top of the generated file.
IncludeVersionComment	bool	true	This value indicates whether the version should be printed as a comment at the top of the generated file.
SourceFolder	string	Light.GuardClauses project folder	The absolute or relative path to the folder that contains the Light.GuardClauses cs files. Usually, you do not have to set this value - it is dynamically resolved to the project folder that contains Light.GuardClauses.csproj
TargetFile	string	..\Light.GuardClauses.Source\Light.GuardClauses.cs	The absolute or relative path to the target file that will be generated. By default, the file will be written next to the Light.GuardClauses.Source.csproj file.
RemoveOverloadsWithExceptionFactory	bool	false	This value indicates whether assertion overloads that use an exception factory delegate are omitted.
IncludeCodeAnalysisNullableAttributes	bool	true	This value indicates whether the Code Analysis Attributes for Nullable Reference Types should be included in the single source file. These are necessary for .NET Standard 2.0 as the attributes are only available for .NET Core 3.0 and later versions.
IncludeValidatedNotNullAttribute	bool	true	Indicates whether the definition of the ValidatedNotNullAttribute is included in the source code. There is no public version of this attribute from Microsoft yet, so if you want to use it, you should include it.
RemoveValidatedNotNull	bool	false	Indicates whether [ValidatedNotNull] attributes are removed from parameter arguments in assertions.
RemoveDoesNotReturn	bool	false	Indicates whether [DoesNotReturn] attributes are removed from methods of the Throw class.
RemoveNotNullWhen	bool	false	Indicates whether [NotNullWhen] attributes are removed from arguments of IsXXX assertions
IncludeCallerArgumentExpressionAttribute	bool	true	Indicates whether the definition of the CallerArgumentExpressionAttribute is included in the source code. You can set this to off is your target framework is .NET Core 3.0, .NET 5 or newer. Other frameworks like .NET Standard 2.x or .NET Framework require the definition of this attribute.
RemoveCallerArgumentExpressions	bool	false	Indicates whether [CallerArgumentExpression("parameter")] attributes are removed from parameterName arguments.