Configuration file Options

There is a number of options that can be used with translator config. The general syntax to add an option is as follows:

<porter>
    <opt name="option_name_1" value="option_value_1"/>
    <opt name="option_name_2" value="option_value_2" attribute1="attribute1_value"/>
    <opt name="option_name_3">Some text</opt>
    ...
</porter>

The options can be split into several categories. This page presents full list of available options.

General workflow options

These options define general translator behavior: logging, errors handling, etc.

log_level

Defines cut level of logs being written by translator. Logs of specified level and more severe ones are emitted, the logs with lower severity are suppressed.

Default value: debug

abort_on_error

States whether the translator should abort execution if any error is encountered. Normally, some errors are not fatal.

Default value: false

write_progress

Whether to display line with completion percentage during the work.

Default value: true

collect_porter_coverage_info

Enables the translator to collect information on usage of its own code. Only works for the Debug (developer) builds of the translator.

Default value: false

Since version: 22.3 (not available for publically released builds)

build_cs_projects

Makes the translator build the project prior to parsing the C# code.

Default value: false

Since version: 22.3 (not available for publically released builds)

Output files control options

These options control how output files are generated.

compare_cpp_hash

Allows it to skip overwriting the translated cpp and h files if the hash of their contents already matches such of the translated code to be saved here. Useful if you’re frequently changing and translating C# code without cleaning the output directory and want to avoid recompiling all C++ files (overwriting the same contents updates file timestamp so that the build system will mark it as changed even if the contents is same).

Default value: true

write_bom

Whether to add BOM record at the beginning of each output C++ file.

Default value: false

write_include_map

States whether to create include map file which then can be used to manage includes from the dependent project. If you plan to translate another project which depends on the current one, creating typemap is the safest way to share type information between them.

Default value: true

tab

Indent substitution. You can use ‘\n’ and ‘\t’ references there as well as other in-line characters.

Default value: Four space characters

endl

Line end substitution. You can use ‘\n’, ‘\r’ and ‘\t’ references there.

Default value: ‘\n’ aka line break

start_block_newline

Whether the opening curl bracket beholds on a dedicated line.

if (++a == 10)
{
    a = 0;
    ++b;
}

if (++a == 10) {
    a = 0;
    ++b;
}

Default value: true

low_case_file_names

Whether output file names are all lowercase. In this mode, word borders in Camel case class names become underscores.

Default value: false

use_pragma_once

Whether to use ‘#pragma once’ instead of scope ifndef.

#pragma one

#include <cstdint>

namespace SampleProject {

enum class Enum: uint8_t
{
    item1,
    item2,
    item3
};

} // namespace SampleProject

#ifndef _SampleProject_enum_h_
#define _SampleProject_enum_h_

#include <cstdint>

namespace SampleProject {

enum class Enum: uint8_t
{
    item1,
    item2,
    item3
};

} // namespace SampleProject

#endif // _SampleCsProject_enum_h_

Default value: true

replace_wchar_with_hex_literal

Whether to replace multibyte symbols in string literals with the hex literals.

System::String a = u"\u0430\u0431\u0432";

System::String a = u"абв";

Default value: false

obfuscate_cpp_headers

<opt name="obfuscate_cpp_headers" value="true" keep_field_names="false" />

If enabled, makes translator generate ‘obfuscated’ headers put into obfuscated_include/ directory alongside with standard include/ one. ‘Obfuscated’ headers get some information on implementation details excluded. For example, types of pointers held by private class memebers are excluded.

One still needs ‘usual’ headers from include/ directory to build the translated project itself. However, for external delivery the headers from obfuscated_include/ must be used. When building your package, make sure to put obfuscated_include/ directory content in place of usual include/ files.

Default value: false

force_public_headers

Enables integrity support for public header files.

Default value: false

Type subsystem options

These options define how translator behaves regarding the translation of the types.

forwarding_if_possible

Use forward declarations in header files instead of includes if possible. This affects function parameters and return values declarations as well as pointers. This does not impact inheritance or value type field cases.

namespace MyProject {
class A;
class B
{
public:
    System::SmartPtr<A> Value;
};
} // namespace MyProject

#include "classes/A.h"
namespace MyProject {
class B
{
public:
    System::SmartPtr<A> Value;
};
} // namespace MyProject

Default value: true

force_include_enum

Use includes instead of forward declarations in header files for enums. Changing the forwarding_if_possible option does not affect this behavior.

#include "enums/A.h"
namespace MyProject {
class B
{
public:
    System::SmartPtr<A> Value;
};
} // namespace MyProject

namespace MyProject {
enum class A;
class B
{
public:
    System::SmartPtr<A> Value;
};
} // namespace MyProject

Default value: false

use_full_base_name

When referring base class, use the full class name (with all namespaces) instead of the short name.

namespace MyProject {
class A
{
    ...
};
class B : public MyProject::A
{
    ...
};
} // namespace MyProject

namespace MyProject {
class A
{
    ...
};
class B : public A
{
    ...
};
} // namespace MyProject

Default value: false

external_object_methods

Use static implementations of ‘ToString’, ‘GetType’, ‘GetHashCode’, ‘Equals’ methods and ‘is’ operator located in ObjectExt class instead of the ones provided by Object class itself. Try this option if you experience problems with these methods being called for primitive types or generic type parameters or alike.

template <typename T>
class A
{
public:
    System::String ValueToString()
    {
        return System::ObjectExt::ToString(m_value);
    }
private:
    T m_value;
};

template <typename T>
class A
{
public:
    System::String ValueToString()
    {
        return m_value->ToString();
    }
private:
    T m_value;
};

Default value: true

cast_delegate

When being a method parameter, cast delegate function to the actual type of expected parameter. Helps to resolve ambiguity in some cases (in C++, lambdas are not of corresponding MulticastDelegate type which can result in ambiguity if more than one signature exist).

ApplyDelegate(static_cast<typename DelegateType>([](String s) { return s; });

ApplyDelegate([](String s) { return s; });

Default value: true

deprecate_system_base_type

Whether to omit baseclass references for the classes from ‘System’ or ‘Microsoft’ namespaces. Use with care as it affects the whole project. If in doubt, consider using CppIgnoreBaseType attribute instead.

class MyStream
{
    ...
};

class MyStream : public System::IO::Stream
{
    ...
};

Default value: false

exception_as_reference

Whether to pass exceptions to functions by reference rather than by creating a local copy of an exception object.

class MyClass
{
public:
    void HandleException(Exception &e);
};

class MyClass
{
public:
    void HandleException(Exception e);
};

Default value: false

ignore_base_for_static_class

Whether to omit ‘Object’ baseclass for the classes declared as static.

static class MyClass
{
    ...
}

class MyClass
{
    ...
};

class MyClass : public System::Object
{
    ...
};

Default value: true

replace_enumerable_type

<opt name="replace_enumerable_type" enumerable="System.Xml.XmlNodeList" type="System.Xml.XmlNode"/>

Adds a enumerable type that needs downcasting when in loop operations. Use this option to specify explicitly which type downcasts into what.

force_dynamic_cast

<opt name="force_dynamic_cast" from_type="A.B.ClassA" to_type="A.B.ClassB" />

For two given types, forces dynamic_cast to be used instead of default static_cast. Use if auto cast type deduction fails (e. g. due to diamond problem).

remove_redundant_base_interfaces

If enabled, removes redundant inheritance from interface types, i. e. interfaces inherited more than once.

namespace TypesPorting
{
    public interface IFoo
    {
    }
    public abstract class AFoo : IFoo
    {
    }
    public class Foo : AFoo, IFoo
    {
    }
    public class Bar : Foo, IFoo
    {
    }
}

class IFoo : public System::Object
{
    ...
};
class ABSTRACT AFoo : public IFoo
{
    ...
};
class Foo : public AFoo
{
    ...
};
class Bar : public Foo
{
    ...
};

class IFoo : public System::Object
{
    ...
};
class ABSTRACT AFoo : public IFoo
{
    ...
};
class Foo : public AFoo, public IFoo
{
    ...
};
class Bar : public Foo, public IFoo
{
    ...
};

Default value: true

enable_fast_rtti

Enables translator generate code which makes casting faster with the price of bigger image size.

Default value: false

Since version: 20.12

force_static_cast

Enables translator generate ForceStaticCast casts when translating any C-style cast instead of StaticCast or DynamicCast. The ForceStaticCast always works via simple static_cast, so this option can only use if you are sure that in translated code each dynamic_cast will succeed.

Default value: false

Since version: 22.6

C# code analysis options

These options impact how the original C# code gets analyzed

exclude_by_description

Allows it to exclude the entities from translating based on description comment. Individual description comment values can be provided as text inside ‘text’ subnodes.

Example:

<opt name="exclude_by_description">
    <text>This is for COM compatibility.</text>
    <text>For COM compatibility.</text>
</opt>

unexpected_override_as_warning

Makes translator produce warning rather than en error if there is a method that overrides one in C++ but not in C#. They may trigger from e. g. the following code:

class Base
{
    public virtual void Foo() {}
}
class Child : Base
{
    public new virtual void Foo() {} // Overrides in C++, but not in C#
}

Default value: false

Since version: 20.12

use_buildalyzer

Makes translator use Buildalyzer library to pre-compile SDK-styled csproj files before translating.

Default value: false

Since version: 21.3

C++ code generation parameters

These options define how translator uses specific C++ code features.

detect_const_methods

Whether to generate ‘const’ specifier on methods that do not modify their object. These can be either marked with CppConstMethod attribute or found const by translator check. Therefore, if this option is false, CppConstMethod attribute has no effect.

class Foo
{
    public void Bar() {}
}

class Foo
{
    ...
    void Bar() const;
};

class Foo
{
    ...
    void Bar();
};

Default value: false

emit_enumerator_current_value_holder

public MyClass Current
{
    get { return mInner.Current; }
}

CODEPORTING_CURRENT_RETTYPE(System::SharedPtr<MyClass>) MyEnumerator::get_Current() const
{
    System::HolderInitializer<System::SharedPtr<MyClass>> holder(m_CurrentHolder);
    
     return holder.HoldIfTemporary(mInner->get_Current());
}

CODEPORTING_CURRENT_RETTYPE(System::SharedPtr<MyClass>) MyEnumerator::get_Current() const
{
     return mInner->get_Current();
}

Default value: true

Since version: 21.12

exclude_volatile

Whether to pass ‘volatile’ flag from C# to C++.

class Foo
{
    private volatile int m_bar;
}

class Foo
{
    ...
    volatile int m_bar;
};

class Foo
{
    ...
    int m_bar;
};

Default value: false

put_enum_on_top

Whether enum declarations preceed class and struct ones in output header files.

class A {}
enum B { C, D };

enum class B { C, D };
class A { ... };

class A { ... };
enum class B { C, D };

Default value: false

reorder_class_by_inheritance

Reorder class if dependent type declared before dependee.

class C : B {}
class B : A {}
class A {}

class A {}
class B : A {}
class C : B {}

class C : B {}
class B : A {}
class A {}

Default value: false

alternative_string_switch

Define whether to use if-else or do-while form of string switch translation.

string s = "abc", s2;
switch (s)
{
case "abc":
    s2 = "cba";
    break;
case "123":
    s2 = "321";
    break;
}

do {
    if (s == u"abc")
    {
        s2 = u"cba";
        break;
    }
    if (s == u"123")
    {
        s2 = u"321";
        break;
    }
} while (false);

if (s == u"abc")
{
    s2 = u"cba";
}
else if (s == u"123")
{
    s2 = u"321";
}

Default value: false

alternative_null_coalescing

Use an alternative form of ‘??’ operator translation which avoids it calculating right hand operand unless it is used.

Object obj = obj1 ?? new Object();

System::SharedPtr<System::Object> obj = System::ObjectExt::Coalesce(obj1, [&](){return System::MakeObject<System::Object>();});

System::SharedPtr<System::Object> obj = obj1 != nullptr ? obj1 : System::MakeObject<System::Object>();

Default value: false

remove_unused_namespaces

Remove unused ‘using namespace’ directives (the references to namespaces no classes from which ones are used). Such constructs can result in compilation errors: if the classes from the namespace are not used, it is possible that no includes introducing this namespace exist, so the name does not get recognized by the compiler.

using System;
using System.Collections.Generic;
class MyClass
{
    void Foo()
    {
        BitConverter.GetBytes(123);
    }
}

#include "MyClass.h"

using namespace System;

void MyClass::Foo()
{
    BitConverter::GetBytes(123);
}

#include "MyClass.h"

using namespace System;
using namespace System::Collections::Generic;

void MyClass::Foo()
{
    BitConverter::GetBytes(123);
}

Default value: true

indexer_as_method

Defines whether to translate indexer invocation as method instead of operator [] even if the later form is possible.

System.Collections.Generic.List<int> mylist = GetList();
int i = mylist[0];

System::Collections::Generic::ListPtr<int> mylist = GetList();
int i = mylist->idx_get(0);

System::Collections::Generic::ListPtr<int> mylist = GetList();
int i = mylist[0];

Default value: true

create_unit_test_preprocessor_directive

Whether to pass ‘#if UNIT_TEST’ directives from C# to C++.

#if UNIT_TEST
[NUnit.Framework.TestFixture]

class MyTests { ... }
#endif

#ifdef UNIT_TEST
class MyTests : public System::Object, public ::testing::Test
{
    ...
};
#endif

class MyTests : public System::Object, public ::testing::Test
{
    ...
};

Default value: false

generate_abstract_keyword

Whether to add an ‘abstract’ attribute to abstract classes. (Currently it is being inserted as ‘ABSTRACT’ define rather than as native C++11 keyword.)

abstract class Abstract
{
    ...
}

class ABSTRACT Abstract : public System::Object
{
    ...
}

class Abstract : public System::Object
{
    ...
}

Default value: false

use_weak_ptr_std_bind

When generating std::bind() expressions for delegates translating, use WeakPtr instead of raw C++ pointers to pass object reference.

delegate string ModifyString(string str);
class WithDelegate
{
    private string prefix = "prefix_";
    public string AddPrefix(string str)
    {
        return prefix + str;
    }
    public void Foo()
    {
        ModifyString myDelegate = AddPrefix;
    }
}

ModifyString myDelegate = std::bind(&WithDelegate::AddPrefix, System::WeakPtr<WithDelegate>(this), std::placeholders::_1);

ModifyString myDelegate = std::bind(&WithDelegate::AddPrefix, this, std::placeholders::_1);

Default value: false

deferred_init

If enabled, replaces all static fields with singletons and calls static constructors from instance constructors and singleton access functions instead of C++ static objects initializers. Use this option to resolve the static objects initialization races. Slows down static fields access and constructors as there are additional checks.

Static constructors of non-TestFixture classes are translated as constructors of global static variables. Static fields of non-TestFixture classes are translated as static class fields.

Default value: None

auto_ctor_self_reference

If enabled, puts constructor self reference guards where required, allowing it for constructor to refer to ‘this’ without deleting the object. Saves the developer from putting CppCtroSelfReference attributes manually but creates more guards than actually required.

class MyClass
{
    public MyClass()
    {
        SomeOtherClass.DoSomething(this);
    }
}

MyClass::MyClass()
{
    IncSelfReference();
    auto __local_self_ref = System::MakeScopeGuard([this]{ DecSelfReference(); });
    SomeOtherClass::DoSomething(System::MakeSharedPtr(this));
}

MyClass::MyClass()
{
    SomeOtherClass::DoSomething(System::MakeSharedPtr(this));
}

Default value: true

force_add_shared_api_macros

If enabled, forces production of shared_api_defs.h file and inserts corresponding macros into the translated code. This helps to switch between shared and static library project using the make_shared_lib option but without re-translating whole project.

Default value: false

finally_statement_as_lambda

Allows translating the try-finally statement as a lambda expression instead of guard object placement.

try
{
    InnerMethod();
}
finally
{
    Console.WriteLine("Finally");
    throw new Exception();
}

System::DoTryFinally([&] /* try-catch block */ 
{
    InnerMethod();
}
, [&] /* finally block */ 
{
    System::Console::WriteLine(u"Finally");
});

auto __finally_guard_0 = ::System::MakeScopeGuard([]()
{
    System::Console::WriteLine(u"Finally");
    throw System::Exception();
});

try
{
    InnerMethod();
}
catch (...)
{
    throw;
}

Default value: false

setter_wrap_with_lambda

Forces translating complex property assignment operators using lambdas.

obj.PublicProperty += "abc";

System::WithLambda::setter_add_wrap(GETTER_SETTER_LAMBDA_ARGS(obj, PublicProperty), u"abc")

System::setter_add_wrap(static_cast<ConcreteBase*>(obj.GetPointer()), &ConcreteBase::get_PublicProperty, &ConcreteBase::set_PublicProperty, u"abc");

Default value: false

allow_interface_members_base_class_impl

In C++, members of interface can be implemented in the base class. In C#, there’s no way doing so. This option generates required calls in child class; however, this can overcomplicate output code in some cases.

public interface IFoo
{
   void Do(int i, string s);
}
public class FooImpl
{
    public void Do(int i, string s)
    {
    }
}
public class Foo : FooImpl, IFoo
{
}

class Foo : public FooImpl, public IFoo
{
    ...
    void Do(int32_t i, System::String s);
};
void Foo::Do(int32_t i, System::String s)
{
    FooImpl::Do(i, s);
}

Default value: true

polymorphic_memberwiseclone

<opt name="polymorphic_memberwiseclone" value="true">
    <root class="MyNamespace.MyClass"/>
    <root class="MyNamespace.MyClass2"/>
</opt>

By default, MemberwiseClone() method in translated code slices output object to the type it is called for. All information about child classes is lost for all implementation is static. This option allows injecting additional virtual methods to the classes MemberwiseClone() is called for and to their child classes. This fixes MemberwiseClone() behavior, but generates additional code. Please note that translator only considers MemberwiseClone() calls located in same assembly by default and doesn’t generate additional code for classes which are not subjects for MemberwiseClone() calls. To force generating these methods for specific classes and their subclasses (e. g. if MemberwiseClone() is called from different assembly), use ‘root’ subnodes with mandatory ‘class’ attributes containing C# class names.

Default value: false

version_compatibility_check_mode

Allows translator generate code which compares headers version used to compile project and supplied library version on startup.

Default value: stderr

force_const_auto_property_getter

Marks auto-generated property getters as const methods.

Default value: false

force_const_simple_property_getter

Marks simple property getters consisting of single ‘return field_name’ statement as const.

Default value: false

process_base_overloading

Puts ‘using’ statement to re-declare hidden baseclass methods in subclasses.

class Bar {
    ...
    void Do();
};
class Foo : public Bar {
    ...
    void Do(System::String s);
    using Bar::Do;
};

class Bar {
    ...
    void Do();
};
class Foo : public Bar {
    ...
    void Do(System::String s);
};

Default value: false

thread_static_generation

Determines how to translate ThreadStatic attribute.

static System::String m_value;

static thread_local System::String m_value;

static System::String m_value() { static thread_local value = false; return value; }

Default value: native

remove_inactive_code

Drops comments with inactive code.

Default value: false

emit_preprocessor_directives

Propagates preprocessor directives to C++.

Default value: true

emplace_assembly_details

Replaces calls into Assembly::Get*Assembly() with calls to project-local GetAssembly_ProjectName(). Unbinds resources from global variables, hides them into local singleton instead.

Default value: false

add_baseclasses_tests

If the class not marked with NUnit.Framework.TestFixture attribute contains methods maked with NUnit.Framework.Test attribute and is inherited by a class marked with NUnit.Framework.TestFixture attribute, the gtest tests are generated for child class instead of parent class.

class FixtureBase {
    [Test]
    public void MyTest() {}
}
[TestFixture]
class Fixture : FixtureBase
{}

TEST_F(Fixture, MyTest) { ... }

TEST_F(FixtureBase, MyTest) { ... }

Default value: true

nunit_assert_class_aliases

Calls to methods of NUnit.Framework.Assert class are translated into gtest-compatible macros. If you use your own test class with similarly named methods, use this option to enable special treatment of these. Enlist classes wrapped inside ‘alias’ subnode as shown below. Also, you might want to exclude such classes from translating.

<opt name="nunit_assert_class_aliases" value="true">
    <alias class="MyNamespace.MyAssertClass"/>
</opt>

Default value: false

original_tests_names

Toggles prefixing test name with category name to simplify tests group run after translating. Alternatively, if you prefer having original tests names, you might want to disable this option.

<opt name="original_tests_names" value="true"/>

[TestFixture]
public class OriginalTestName
{
    [Test]
    [Category("Original")]
    public void Test1() {}
}

TEST_F(OriginalTestName, Test1) { s_instance->Test1(); }

TEST_F(OriginalTestName, Original_Test1) { s_instance->Test1(); }

Default value: false

cpp_enum_enable_metadata

Enables metadata globally, same as CppEnumEnableMetadata attribute does for individual enums.

<opt name="cpp_enum_enable_metadata" value="true"/>

Default value: false

generate_enum_descriptions

Enables passing System.ComponentModel.Description attribute value to C++ code.

<opt name="generate_enum_descriptions" value="true"/>

To extract such data, use the following syntax:

System::Enum<T>::GetDescription(value)

Here T is enum type and value is enum value.

Default value: false

hide_forward_declarations

Wraps forward declarations section into ‘@cond…@endcond’ section to forbid Doxygen process it.

/// @cond
namespace SomeNS { class Class1; }
/// @endcond

namespace SomeNS { class Class1; }

Default value: false

Since version: 20.7

attributes_into_reflection_info

Makes translator propagate information on specific attributes into reflection tables. Use like the following:

<opt name="attributes_into_reflection_info">
    <attribute>JsonIgnore</attribute>
</opt>

‘Attribute’ subnode with attribute name text specifies the attribute to propagate.

Default value: attributes do not get propagated into reflection information

Since version: 20.8

allow_cast_to_non_generic_list

Allows casts to System.Collections.IList to be translated into compilable code.

Default value: false

Since version: 20.8

fix_setter_return_tag

Replaces <retruns> tag with <param name=“value”> for property setters.

class A
{
    /// <summary>
    /// Foo getter and setter
    /// </summary>
    /// <returns>foo</returns>
    public int Foo
    {
        get { return foo; }
        internal set { foo = value; }
    }

    int foo;
}

class A : public System::Object
{
public:
    /// <summary>
    /// Foo getter and setter
    /// </summary>
    /// <returns>foo</returns>
    int32_t get_Foo();
    /// <summary>
    /// Foo getter and setter
    /// </summary>
    /// <param name="value">foo</param>
    void set_Foo(int32_t value);
 };

class A : public System::Object
{
public:
    /// <summary>
    /// Foo getter and setter
    /// </summary>
    /// <returns>foo</returns>
    int32_t get_Foo();
    /// <summary>
    /// Foo getter and setter
    /// </summary>
    /// <returns>foo</returns>
    void set_Foo(int32_t value);
};

Default value: false

remove_all_comments

Removes all comments from sources.

Default value: false

explicit_destructors

Generates destructors for each translated class or struct.

struct A {}
class B {}

class A : public System::Object
{
public:
    ~A() {}
}

class B : public System::Object
{
public:
    ~B() {}
}

class A : public System::Object
{
}

class B : public System::Object
{
}

Since version: 20.9

Default value: false

rtti_on_testfixture

Allows generating RTTI macros for TestFixture classes.

[TestFixture]
class SimpleTest {}

class SimpleTest : public System::Object
{
    typedef SimpleTest ThisType;
    typedef System::Object BaseType;
    typedef ::System::BaseTypesInfo<BaseType> ThisTypeBaseTypesInfo;
    RTTI_INFO_DECL();
};

class SimpleTest : public System::Object
{
};

Since version: 20.9

Default value: true

force_wrap_iostream

Overloads all methods that accept System::IO::Stream arguments, as if CppIOStreamWrapper attribute was present.

public void IStream(Stream istream)
{
    ...
}

void IStream(System::SharedPtr<System::IO::Stream> istream);
template <typename CharType, typename Traits = std::char_traits<CharType>>
void IStream(std::basic_istream<CharType, Traits>& istream)
{
    auto istreamWrapper = System::IO::WrapSTDIOStream(istream);
    IStream(istreamWrapper);
}

void IStream(System::SharedPtr<System::IO::Stream> istream);

Since version: 20.10

Default value: false

allow_using_directives_in_headers

Makes translator simplify header files by utilizing header directives.

using Namespace1;
using System;
namespace Namespace2
{
    public class Class2
    {
        public void Foo(Class1 c1) { ... }
    }
}

using namespace Namespace1;
using namespace System;
namespace Namespace2
{
    class Class2
    {
    public:
        void Foo(SharedPtr<Class1> c1);
    };
}

namespace Namespace2
{
    class Class2
    {
    public:
        void Foo(System::SharedPtr<Namespace1::Class1> c1);
    };
}

Since version: 20.10

Default value: false

extensions_as_method

<opt name="extensions_as_method" value="true">
    <extension class="Aspose.BarClassExtensions"/>
</opt>

Specifies the classes for which extension method calls should be translated as member function calls instead of a static method from extension class. Value is ignored.

obj.CallExtensionMethod(arg);

obj->CallExtensionMethod(arg);

ExtensionClass::CallExtensionMethod(obj, arg);

Since version: 20.11

Default value: true

generate_begin_end_methods

Allows the translator to generate begin(), end() and other STL-like iterators access methods for those classes implementing the generic IEnumerable interface.

If the class impelements the generic IEnumerable interface via returning GetEnumerator() call of its field or auto-property, and the type of this field or auto-property provides begin() and end() methods, these methods will be proxied at the class level. For example, the following code will go:

public class Class0 : IEnumerable<int>
{
    ...
    protected List<int> list; // List has begin/end methods.
    public IEnumerator<int> GetEnumerator()
    {
        return list.GetEnumerator(); // doing nothing but return list.GetEnumerator()
    }
    ...
}

If the implementation of GetEnumerator() is more complex, or the type of the property or field it operates doesn’t provide begin() and end() methods, these won’t be generated at class level, too. The following classes are not eligable for begin() and end() methods generation:

public class Class1 : IEnumerable<int>
{
    ...
    protected List<int> list; // List has begin/end methods.
    public IEnumerator<int> GetEnumerator()
    {
        list = new List<int>() { 1, 2, 3 }; // Modifying member before calling GetEnumerator()
        return list.GetEnumerator();
    }
    ...
}
public class Class2 : IEnumerable<int>
{
    ...
    protected Class1 list; // Class1 has no begin/end methods.
    public IEnumerator<int> GetEnumerator()
    {
        return list.GetEnumerator(); // doing nothing else than return list.GetEnumerator()
    }
    ...
}

This behavior can be overwritten by using CppNoBeginEndMethods or CppGenerateBeginEndMethods attributes regardless of the option’s value.

class Class0 : public System::Collections::Generic::IEnumerable<int32_t>
{
    ...
public:
    /// A collection type whose iterator types is used as iterator types in the current collection.
    using iterator_holder_type = System::Collections::Generic::List<int32_t>;
    /// Iterator type.
    using iterator = typename iterator_holder_type::iterator;
    /// Const iterator type.
    using const_iterator = typename iterator_holder_type::const_iterator;
    System::SharedPtr<System::Collections::Generic::IEnumerator<int32_t>> GetEnumerator() override;
    /// Gets iterator pointing to the first element (if any) of the collection.
    /// @return An iterator pointing to the first element (if any) of the collection
    iterator begin() noexcept;
    /// Gets iterator pointing right after the last element (if any) of the collection.
    /// @return An iterator pointing right after the last element (if any) of the collection
    iterator end() noexcept;
    /// Gets iterator pointing to the first element (if any) of the const-qualified instance of the collection.
    /// @return An iterator pointing to the first element (if any) of the const-qualified instance of the collection
    const_iterator begin() const noexcept;
    /// Gets iterator pointing right after the last element (if any) of the const-qualified instance of the collection.
    /// @return An iterator pointing right after the last element (if any) of the const-qualified instance of the collection
    const_iterator end() const noexcept;
    /// Gets iterator pointing to the first const-qualified element (if any) of the collection.
    /// @return An iterator pointing to the first const-qualified element (if any) of the collection
    const_iterator cbegin() const noexcept;
    /// Gets iterator pointing right after the last const-qualified element (if any) of the collection.
    /// @return An iterator pointing right after the last const-qualified element (if any) of the collection
    const_iterator cend() const noexcept;
    ...
};

class Class0 : public System::Collections::Generic::IEnumerable<int32_t>
{
    ...
public:
    System::SharedPtr<System::Collections::Generic::IEnumerator<int32_t>> GetEnumerator() override;
    ...
};

Since version: 21.1

Default value: true

default_lambda_capture_mechanism

Specifies the lambda capturing mechanism.

void foo() {
  int32_t value = 10;
  LambdaCaptureTest::VoidVoidDelegate lambda = LambdaCaptureTest::VoidVoidDelegate(static_cast<std::function<void()>>([&value]() -> void {
    ASSERT_EQ(10, value);
  }));
}

void foo() {
  int32_t value = 10;
  LambdaCaptureTest::VoidVoidDelegate lambda = LambdaCaptureTest::VoidVoidDelegate(static_cast<std::function<void()>>([value]() -> void {
    ASSERT_EQ(10, value);
  })).template AddHeldVariable<LambdaCaptureTest::VoidVoidDelegate>("value", value);
}

void foo() {
  System::Details::LambdaCaptureHolder<int32_t> _lch_value = 10;
  int32_t &value = _lch_value.GetCapture();
  LambdaCaptureTest::VoidVoidDelegate lambda = LambdaCaptureTest::VoidVoidDelegate(static_cast<std::function<void()>>([_lch_value, &value]() -> void {
    ASSERT_EQ(10, value);
  })).template AddHeldVariable<LambdaCaptureTest::VoidVoidDelegate>("value", value);
}

Since version: 21.2

Default value: use_holders

avoid_lambda_holders_if_possible

Since version: 21.2

Default value: true

always_include_delegates

Since version: 21.3

Default value: false

force_const_ref_parameters

Since version: 21.6

Default value: false

force_const_ref_return_type_for_auto_properties

Since version: 21.7

Default value: false

force_const_ref_return_type_simple_properties

Since version: 21.11

Default value: false

force_enum_flags_attribute

Since version: 21.7

Default value: false

alternative_debug_class

Makes the translator convert the calls to the methods of the specified class into macros.

C# code:

Aspose.Debug.Assert(true);

Configuration file:

<typemap>
    <class csname="Aspose.Debug" cppname="Aspose::Replace::NullDebug"/>
</typemap>
<opt name="alternative_debug_class" value="Aspose.Debug"/>

C++ code:

NULLDEBUG_ASSERT(true);

Since version: 21.10

Default value: false

class_ptr_alias

Makes the translator generate a special ‘Ptr’ member type to each public class that aliases a smart poitner to this class.

C# code:

public class MyClass
{}

class MyClass : public System::Object
{
    // ...
public:
    /// An alias for shared pointer to an instance of this class.
    using Ptr = System::SharedPtr<MyClass>;
}

class MyClass : public System::Object
{
    // ...
}

Since version: 21.12

Default value: false

Debug and developer version code options

These options control debug and developer version code in generated C++ files.

collect_test_methods

Whether to collect information on translated code test methods in C++ runtime by calling “System::TestToolsExt::RegisterTest()” for each test method on initialization stage.

Default value: false

generate_for_each_member

Enables adding for_each_member subsystem-related code to each class and generating gv (graphviz) dumps of in-memory objects after each test.

Default value: false

for_each_member_cycles_only

Enables cycles search using for_each_member

Default value: false

Since version: 20.11

for_each_member_cleanup_before_each_test

Enables cleaning up the for_each_member model before running each test.

Default value: false

stable_gv_file

Enables renumbering objects in for_each_member-based gv dumps so that the indexes in output files do not depend on any temporary objects being created and then destroyed during the execution. Required if you want to compare the gv file against a template and want it to remain stable in all builds (release and debug builds and Visual Studio and non-Visual Studio builds currently create different amounts of temporary objects, therefore, affecting object indexes in non-stabilized builds).

Default value: false

test_run_stub_file

Creates a file to dump all tests names into during translating

Default value: <Empty>

insert_leakage_detectors

Insert helper code to detect the constructors leaking in references. This usually means that the nested objects created by this constructor refer to the object itself using shared pointers instead of weak ones which promises some big problems (memory leaks, double deletion issues on constructor exceptions, etc.). If enabling this feature, check output in debug to track potential problems.

Default value: false

tests_garbage_collection

Calls DBG_GARBAGE_COLLECTION mechanism after each test.

Island of isolation is found.
Objects:
    0x11223344: MyClass: 2 reference
        m_a: 0x55667788
        m_b: 0x99aabbcc
    0x55667799: MyClass2: 1 reference
        m_owner: 0x11223344
    0x99aabbcc: MyClass2: 1 reference
        m_owner: 0x11223344

Default value: none

tests_garbage_collection_generation

GC generation to collect by __DBG_GARBAGE_COLLECTION wrappers after tests. For optimization purposes.

Default value: 0

add_category_name_to_timeout_tests

If defined, value is used as a category name for all tests with timeouts.

Default value: <Not defined>

for_each_member_short_names

Enables short names being generated for members available through for_each_member-related functions.

Default value: false

enable_warnings_for_virtual_function_calls

Enables translator raising warnings if any virtual methods are called from constructor, as the behavior will be different in C++.

Default value: true

Since version: 20.7

Path resolving behavior

This option regulate how translator check path that located in the config file.

use_porter_home_directory_while_resolving_path

Enables translator using translator home directory and translator executable location when resolving paths mentioned in configuration file. Only affects declarations that go after it in configuration file. Can’t be disabled if it is enabled somewhere else in configuration file.

Default value: false

Project settings

These options specify the settings of output project.

cmake_targets

Whether to build translated project, tests or both.

Default value: Both

make_shared_lib

Whether to generate shared library project or static library project. Only makes effect if building translated project is allowed (see cmake_targets option) and source project ls a library rather than executable.

Default value: false

cpp_lib_path

Path to system library folder (the one containing ‘include/’ and ‘lib/’ directories).

Default value: ../../../../asposecpplib

cmake_temaplates or makefile_templates

Path to the directory with CMakeLists.txt file to be used as a template.

Default value: cmake

generatedlist_template

Path to a file which will be used as a template for outputting list of all generated sources (header and cpp files)

Default value: "" (empty string)

Let’s suppose you have the following GeneratedList.cmake file:

set(generatedhpp
%%HEADERS%%
)

set(generatedcpp
%%SOURCES%%
)

The translator will create file GeneratedList.cmake next to CMakeLists.txt with the following content:

set(generatedhpp
include/public_header1.h
include/public_header2.h
source/private_header3.h
source/private_header4.h
# etc.
)

set(generatedcpp
source/public_source1.cpp
source/public_source2.cpp
source/private_source3.cpp
source/prviate_source4.cpp
# etc.
)

Now you can include this file from CMakeLists.txt and use generatedcpp and generatedhpp variables instead of file(GLOB) cmake command.

include_templates

Path to the directory with shared_api_defs.h template file used to generate shared library API.

Default value: include

source_templates

Path to the directory with embedded_resources.cpp template to support Assembly class and C# project’s resources access.

Default value: source

add_assembly_details

Indicates for which returned assembly current project will be used. I.e for executing_assembly Assembly.GetExecutingAssembly() will be used to access assembly name resources etc.

Default value: <None>

additional_defines

Additional defines for either C# code (used during code parsing) or C++ project (passed to cmake).

Default value: __cplusplus

exclude_conditional_symbols

Exclude defines from being passed from C# project to cmake. Normally, translating applications passes all definitions mentioned in project file to cmake.

Default value: <None>

additional_includes

Additional includes to pass to translated project via cmake.

Default value: <Not defined>

false | No | false

custom_gtest_main

Path to the custom file with gtest main() function to use instead of the default one.

Default value: gtest_main.cc

cpp_files_to

Directory to copy cpp files contained in current project to.

Default value: source

interface_as_public

Unconditionally move all interfaces to public headers, including non-public ones.

Default value: false

internal_as_public

Whether to translate internal members and types as public. Useful when preparing the library to be linked with tests project.

Default value: false

do_not_hardcode_aspose_cpp_path

Disables writing exact path to asposecpplib at CMakeLists.txt. Useful if converted project is compiled from directory different from the one it was translated into.

Default value: false

tools_version

Specific the version of tool that should be used on translating stage. Useful if project converted on machine with higher version of .NET Framework.

14.0

Default value: version of tool specified in project file or any available one if project file doesn’t specify any.

target_framework_version

Specific version of .NET Framework to use when parsing C# project.

Default value: Version specified in project file.

make_library

Alternative way to specify output library type in what relates to shared API macros.

Default value: static

generate_includes_subdirectory

Creates a subdirectory under ‘include’ directory to avoid header name clashes when using several translated projects from single project.

Default value: false

make_cpp_file_name_uniq

Controls translator behavior in whether file names should be unicalized by extending with trailing underscores.

Default value: true

Since version: 20.8

headers_dir_name

Changes the directory where header files of a translated project will be stored. The ‘include’ directory name is used when this attribute is not present in the config file.

Default value: include

Since version: 21.4

sources_dir_name

Changes the directory where source files of a translated project will be stored. The ‘source’ directory name is used when this attribute is not present in the config file.

Default value: source

Since version: 21.4

Code readability

These options improve generated code’s readability. However, the code generated now doesn’t handle some corner cases properly or in the same way C# code does, so using these options on big codebases is error-prone. Instead, use them to translate e. g. code samples for your projects being translated, to make them easy to read.

foreach_as_range_based_for_loop

Translate C# foreach loops as C++ range-based for loops

foreach (HeaderFooter hf in doc.GetChildNodes(NodeType.HeaderFooter, true))
{
    // ...
}

auto hf_enumerator = doc->GetChildNodes(NodeType::HeaderFooter, true)->GetEnumerator();
SharedPtr<HeaderFooter> hf;
while (hf_enumerator->MoveNext() && (hf = DynamicCast<HeaderFooter>(hf_enumerator->get_Current()), true))
{
    // ...
}

for (auto hf : IterateOver<HeaderFooter>(doc->GetChildNodes(NodeType::HeaderFooter, true)) )
{
    // ...
}

Default value: false

simplify_using_statements

Makes translator generate more compact code for ‘using’ statements that relies on used object destructors rather then on correct Dispose calls.

{
    System::SharedPtr<Rs> __using_resource_0 = System::MakeObject<Rs>();
    System::Console::WriteLine(u"Statement");
}

{
    System::SharedPtr<Rs> __using_resource_0 = System::MakeObject<Rs>();
    //Clearing resources under 'using' statement
    System::Details::DisposeGuard<1> dispose_guard_1({ using_resource_0});
    
    try
    {
        System::Console::WriteLine(u"Statement");
    }
    catch(...)
    {
        dispose_guard_1.SetCurrentException(std::current_exception());
    }
}

Default value: false

Since version: 20.8

force_auto_in_variable_declaration

Makes translator generate ‘auto’ types for local variables instead of full type name so that code is more compact.

auto rs = System::MakeObject<Rs>();

System::SharedPtr<Rs> rs = System::MakeObject<Rs>();

Default value: false

Since version: 20.8

prefer_short_type_names

Makes translator prefer short type names where possible instead of fully qualified names in some contexts.

System::StaticCast<A>(o)

System::StaticCast<Full::Namespace::Path::A>(o)

Default value: false

Since version: 20.9

use_stream_based_io

Replaces System::Console calls with cout invocations.

std::cout << "Hello" << std::endl;

System::Console::WriteLn(u"Hello");

Default value: false

Since version: 20.10

generate_get_shared_members

Enables or disables generating GetSharedMembers() method for translated classes.

Default value: true

Since version: 20.11

generate_rtti_info

Enables or disables generating RTTI macros for translated classes.

Default value: true

Since version: 20.11

Code documentation

keep_documentation_comments

Allows passing C# code documentation comments to C++ code.

Default value: false

fix_self_closing_tags

Enables translator transforming self-closing documentation comment tags into pairs of opening and closing ones.

Default value: false

Since version: 20.1

try_expand_cref_types

Enables translator to replace cref types with proper C++ substitutions when translating documentation comments to Doxygen format.

<see cref="Doxygen::GoldTests::Porter::TestClass"></see>

<see cref="TestClass"></see>

Default value: false

Since version: 20.7

hide_internal_declarations

Makes translator mark internal entities for Doxygen to skip them.

/// @cond
    /// <summary>
    /// internal constructor
    /// </summary>
    /// <param name="value"></param>
    AbstractTestClass(uint8_t value);
    /// @endcond

/// <summary>
    /// internal constructor
    /// </summary>
    /// <param name="value"></param>
    AbstractTestClass(uint8_t value);

Default value: false

Since version: 20.8

hide_friend_declarations

Makes the translator to generate the ‘@cond…@endcond’ wrappers around friend declarations to exclude them from the Doxygen documentation.

/// @cond
friend class MyClass;
/// @endcond

friend class MyClass;

Since version: 21.1

Default value: false

remove_private_comments

Makes translator remove comments for private entities.

Default value: false

Since version: 20.8

Legacy options

Options no longer supported but still recognized (and ignored) by translator for compatibility reasons are:

• alternative_base
• boost_ver
• additional_libdirs
• singleton_mode
• auto_weak_ptr_reference
• gtest_path
• insert_using_statement_guard
• using_statement_as_lambda
• using_statement_enhanced

Notes

Code examples used on this page are for illustration purposes only. Actual translator output may differ.