TOP

ASN.1/C# Compiler Directives Reference

Applies to: ASN.1/C# 5.0

This section lists the compiler directives and provides a thorough description of their function.

--<ASN1.DeferDecoding ref>--

Does not allow the compiler to automatically decode a particular component within SET, SEQUENCE, or CHOICE, and SET OF or SEQUENCE OF elements when its containing type is marked for decoding.

The component referred to by the absolute reference is represented as the Oss.Asn1.DeferredComponent runtime library generic class type. The class type includes the Encoded property, which allows access to the encoded deferred component, and the Decoded property, which allows access to the decoded deferred component.

The Oss.Asn1.DeferredComponent class can store a component either in the encoded form as a byte array or in the decoded form as an object of the Oss.Asn1.BasePdu runtime library class.

Example

ASN.1 C#
--<ASN1.DeferDecoding Module.Type.f1d>--
 
  Module DEFINITIONS ::= BEGIN
     Type ::= SET {
             f1d INTEGER,
             f2 BOOLEAN
      }
  END
    /// <summary>
    /// Represents schema type 'Type' (SET)
    /// </summary>
    [System.Serializable]
    public partial class Type : Oss.Asn1.BasePdu
    {
        /// <summary>Field 'f1d'</summary>
        public Oss.Asn1.DeferredComponent<TypeF1dEncodable> F1d { get; set; }
        /// <summary>Field 'f2'</summary>
        public bool F2 { get; set; }
        ...
    }

The representation shown above in bold is generated only when the DeferDecoding directive is set. The TypeF1dEncodable type parameter is the representation generated for the f1d component type to store the component in decoded form as an object of the Oss.Asn1.BasePdu class.

Remarks

The ASN1.DeferDecoding directive is supported for BER and DER. Do not use it with any other encoding rules.

The IgnoreDeferredDecoding property of Oss.Asn1.BaseDecoderOptions allows you to store all deferred components in the encoded form when IgnoreDeferredDecoding is set as false (by default) or decode them, when IgnoreDeferredDecoding is set as true.

Except for BER and DER, for all encoding rules, all components of SET, SEQUENCE, CHOICE, SET OF, or SEQUENCE OF types are decoded with their containing type.

Implementation limitations

  • The ASN1.DeferDecoding directive is not supported by the EXTENDED-XER codec. On attempt to encode or decode a deferred component, the System.NotImplementedException exception is issued.
  • The ASN1.DeferDecoding directive cannot be used with the -compat v4.0.0 command-line option.

--<ASN1.HugeInteger type>--
--<OSS.HUGE [type]>--

Sets a special representation for INTEGERs whose size is not limited by the C# long integer type. When either directive is used, the corresponding INTEGER types are represented by the System.Numerics.BigInteger value type. By default, INTEGER types are represented by int or long depending on the value range constraints imposed on the INTEGER type.

The OSS.HUGE directive supports both global and local forms. When specified globally, type refers to an ASN.1 INTEGER type that will be represented using the BigInteger representation. Also, when OSS.HUGE is applied globally with no parameters, it applies to all integers in the schema. When specified locally, the directive takes no operands.

The ASN1.HugeInteger directive requires a parameter and it cannot be applied to all integers.

Local Directive Example

HugeInt DEFINITIONS ::= BEGIN
    A ::= INTEGER --<HUGE>--
END

Global Directive Example

--<ASN1.HugeInteger LengthModule.LengthData.lengthOfSolarSystem>--
LengthModule DEFINITIONS ::= BEGIN
    LengthData ::= SEQUENCE {
       lengthOfSolarSystem  INTEGER,
       units ENUMERATED{mm(0), cm(1), m(2), km(3), lightyears(4)}
    }
END

Restrictions

  • The ASN.1/C# compiler does not support value notation for huge INTEGER values that are less than -18446744073709551615 or greater than 18446744073709551615. It will report the "C0267E: Number is too large" error if such a value is encountered in the ASN.1 schema. Note, however, that there is no limitation on values that the application can set using the C# BigInteger struct API.
  • The PER codec does not support coding of constrained INTEGER type values with bounds less than -18446744073709551615 or greater than 18446744073709551615.
  • The PER codec does not support coding of semi-constrained INTEGER type values with lower bounds less than -18446744073709551615 or greater than 18446744073709551615.
  • The PER codec does not support coding of semi-constrained and unconstrained INTEGER type values that are longer than 128K (131072) bits.
  • .NET 4.0 or later is required to build and run the application that maps particular INTEGER types to the BigInteger representation. When compiling the generated classes, the reference to the System.Numerics assembly should be explicitly added to the csc command-line (/r:System.Numerics.dll) or to the corresponding Visual Studio project.

Version Information

These directives are available in version 4.4 and later.


--<ASN1.Nickname ref nickname>--
--<OSS.Nickname ref nickname>--

Provides an alias to a type or module name from an ASN.1 module to be used in the generated code.

Default Behavior

By default, the name used in the generated C# classes is derived from the ASN.1 input file.

Example

In the following notation, the MTN nickname is used for the MyTypeName type, which is an element of MySequence within MyModule.

--<ASN.1.Nickname MyModule.MySequence.MyTypeName MTN>--

The following example illustrates how to name types and identifiers:

ASN.1 C#
--<ASN1.Nickname Module.UserData Monkey>--
--<ASN1.Nickname Module.UserData.* Gorilla>--
--<ASN1.Nickname Module.UserData.*.1 Gibbon>--
--<ASN1.Nickname Module.UserData.*.fvalue Mandrill>--
Module DEFINITIONS ::= BEGIN UserData ::= SET OF SEQUENCE 
  {
    key	INTEGER,
    fvalue OCTET STRING OPTIONAL
   } END
public partial class Monkey : System.Collections.Generic.List<Gorilla>
{
    ...
}
public partial class Gorilla
{
    /// <summary>Field 'key'</summary>
    public int Gibbon { get; set; }
    /// <summary>Field 'fvalue'</summary>
    public byte[] Mandrill { get; set; }
    ...
}

"*" refers to the SEQUENCE type and "1" refers to the first element in the SEQUENCE (the key). In ASN.1:1990 you can omit identifiers for elements of a SEQUENCE, SET, or CHOICE, therefore you can use the number notation to give a name to every component of these constructs. Note that identifiers are mandatory in ASN.1:2015.

The following example shows how to name an item in a NamedNumberList:

ASN.1 C#
--<ASN1.Nickname Module.E.enum1 " new_enum1">--
--<ASN1.Nickname Module.B.bit1 " new_bit1">--
--<ASN1.Nickname Module.I.int1 " new_int1">--
 
Module DEFINITIONS ::= BEGIN
E ::= ENUMERATED {enum1(1), enum2(2)} B ::= BIT STRING {bit1(4), bit2(8)}
I ::= INTEGER {int1(10), int2(8)} END
public partial class E : Oss.Asn1.BasePdu
{
    public enum Values
    {
        NoValue = 0,
        new_enum1 = 1,
        Enum2 = 2
    }
    public Values Value { get; set; }
    ...
}
public partial class B : Oss.Asn1.BasePdu
{
    public enum Values
    {
        NoValue = 0,
        new_bit1 = 4,
        Bit2 = 8
    }
    public Oss.Asn1.BitStringWithNamedBits Value { get; set; }
    ...
}
public partial class I : Oss.Asn1.BasePdu
{
    public enum Values
    {
        NoValue = 0,
        new_int1 = 10,
        Int2 = 8
    }
    public int Value { get; set; }
    ...
}

See Also


--<ASN1.PDU type [, type ] ...>--
--<OSS.PDU [type]>-- | --<OSS.NOPDU [type]>--

Indicates whether an ASN.1 type should be a Protocol Data Unit (PDU).

Default Behavior

By default, only unreferenced types are considered PDUs by the compiler, therefore can be encoded/decoded as complete units.

Example

In the following example, MyType is treated as a PDU, even if it is referenced in another type definition. Note that the types in the directive must be specified using the absolute reference notation.

--<ASN1.PDU Module.MyType>--
 
Module DEFINITIONS ::= BEGIN
  AnotherTypeRef 
  ::= MyType 
  MyType ::= SET 
  {
    b BOOLEAN
   }
END

--<ASN1.RealRepresentation realKind [type1 [, type2, ... ]]>--

Enables you to select the representation (binary or decimal) to be used for ASN.1 values of type REAL. This directive can be applied to particular REAL types, or can specify a default for all REAL types. By default, the REAL type is represented by the double C# type.

The realKind operand can be binary or decimal. It specifies how the REAL type should be represented in the generated .cs files.

binary
Is implemented by the double C# type. It is the default.
decimal
Corresponds to the decimal C# type.

Example

ASN.1 C#
--<ASN1.RealRepresentation decimal Module.MyType.a1.b2>--
Module DEFINITIONS ::= BEGIN
MyType ::= SEQUENCE {
       a1 SET { b1 INTEGER, b2 REAL },
       a2 REAL
     }
END 
///<summary>Field 'b2'</summary>
public decimal B2 { get; set; }


///<summary>Field 'a2'</summary>
public double A2 { get; set; }

In the above example, the decimal C# type is used to represent the field b2 of the field a1 of the type MyType, while the field a2 of the type MyType is represented by the double C# type.

Remarks

For a global effect, the ASN1.RealRepresentation directive must be used with no type references and placed before the first module in the ASN.1 input.

See Also

OSS.DECIMAL | OSS.DOUBLE


--<ASN1.Remove ref [, ref] ...>--

Instructs the ASN.1 compiler to ignore certain ASN.1 types or components. The compiler does not generate code for these types. This is useful when you want to omit certain parts of an ASN.1 specification without modifying the original ASN.1 source.

ref can refer to: defined types, defined values, members of CHOICE types (excluding the last of the remaining), components that are marked OPTIONAL in a SEQUENCE or SET type, components that have a DEFAULT value in a SEQUENCE or SET type, information object classes, information objects that are not included in information object sets, information object sets.

The ASN1.Remove directive informs the compiler that an ASN.1 item should be treated as if it was not included in the ASN.1 source text, in other words, no associated code is generated in the .cs files for this type for use by the application. However, removal of components leads to encodings that are perfectly compatible with counterpart applications that do not use the ASN1.Remove directive. By default, all parts of the ASN.1 input are included in the compiler-generated files.

Example

In the following example, after compiling the syntax, an empty class structure S with no component accessor or mutator methods is generated in the .cs file:

ASN.1 C#
--<ASN1.Remove Mod.Int>--
--<ASN1.Remove Mod.S.a>--
--<ASN1.Remove Mod.i>--
 
Mod DEFINITIONS ::= BEGIN
   S ::= SET { a SET OF SET OF SEQUENCE {
                 b Int
                 } OPTIONAL
        }
   v S ::= {}

   Int ::= INTEGER
   i Int ::= 10
END
    /// <summary>
    /// Represents schema type 'S' (SET)
    /// </summary>
    [System.Serializable]
    public partial class S : Oss.Asn1.BasePdu
    {

        /// <summary>
        /// Determines whether the specified object is equal to the current object.
        /// </summary>
        /// <param name="right">The object to compare with this object. </param>
        /// <returns>true if the specified object is equal to the current object; otherwise, false.</returns>
        public override bool Equals(object right)

       ...
   }

Also, no static readonly variable and static property are created in the Values.cs module class to represent the value i.

--<ASN1.Remove Mod.bit, Mod.Int>--
--<ASN1.Remove Mod.Set.a.b.c.d.*.e>--
  
Mod DEFINITIONS ::= BEGIN
   Int ::= INTEGER
     A ::= SEQUENCE {a Int OPTIONAL, b BIT STRING}
   a A ::= { a 1, b bit}
  bit BIT STRING ::= '0'B
  C ::= CHOICE { a Int }
  Set ::= SET {
     a SET {
       b SET {
        c SET {
            d SET OF SET {
              e INTEGER OPTIONAL
            }
          }
        }
     }
   } 
   s Set ::= { a { b { c { d { {e 3}, {e 4}, {e 5} } } } } }
  END

The .rmv file will contain the following ASN1.Remove directives for types, values, components that reference items marked for removal:

--<ASN1.Remove Mod.s>--
"s" contains values for the component e marked for removal.
--<ASN1.Remove Mod.C>--
"C" references the type Int marked for removal.
--<ASN1.Remove Mod.a>--
"a" contains the reference to the defined value bit marked for removal.
--<ASN1.Remove Mod.A.a>--
The defined type Int for the component A.a is marked for removal.

Remarks

When an ASN.1 item is marked for removal, any references to the item must also be removed (by using the ASN1.Remove directive). If errors related to missing references occur and the -genDirectives or the -keepNames command-line option is specified, the OSS ASN.1 compiler automatically generates the ASN1.Remove directives in a file with an .rmv extension (this file will have the same prefix as the .gen file).

The generated .rmv file can be passed at the command-line (before any compiler options) to let the compiler automatically remove the types that are causing problems.

Under special circumstances, the ASN1.Remove directives cannot be generated into the .rmv file. In such a case, you should successively call the ASN.1 compiler several times (correcting the syntax) until the ASN.1 notation compiles correctly.

The listing file generated with the -listingFile command-line option omits removed items entirely. To get a full listing with removed items included, use the -modListingFile command-line option.

Standard directives applied to or found inside ASN.1 items marked for removal have no effect.

The ASN1.Remove directive applied to the fields of a parameterized type results in removing those fields from each instance of the parameterized type, and therefore we do not recommend it.

Removing fields from a type that is referenced in the COMPONENTS OF type notation results in removing those fields from each type specified with the COMPONENTS OF type notation.

With the CANONICAL-XER encoder the ASN1.Remove directive cannot be applied to a SET or SEQUENCE component with a default value (see the ITU-T Recommendation X.693 (11/2008) paragraphs 9.5 and 9.6.3).


--<ASN1.Version 1990 | 1994 | 1997 | 2002 | 2008 | 2015
      moduleName [{ oid }]>--

This directive is useful for applications that have several versions of ASN.1 source in use.

If ASN1.Version conflicts with a -1990 | -2015 compiler option, the higher version year is used.


--<ASN1.WorkingSet name type [, type] ... >--

Enables you to select from the input ASN.1 schema, a subset of types that can be used in your application. In other words, the ASN1.WorkingSet directive enables you to specify, using one directive, all PDUs (the types of the messages to encode and decode). Values, information objects, etc. defined in the working set are also represented in the compiler generated code.

name is a working set name required for consistency between the ASN.1/C product and the ASN.1/C++ and ASN.1/Java products; otherwise it is ignored.

If type is a module name, this directive has the same effect as the OSS.ROOT directive, which causes all unreferenced types within this module to be considered PDUs.

See Also

OSS.ROOT


--<OSS.ASN1VER type 1990 | 1994 | 1997 | 2002 | 2008 | 2015>--

Specifies the version of the ASN.1 standard for the input files.

Default Behavior

By default, before detecting a particular type of notation, the compiler uses neutral mode. After the compiler detects notation particular to a version, it switches out of neutral mode and enforces conformance to that standard.

See Also

ASN1.Version


--<OSS.BMPSTRING [type]>--
--<OSS.UNIVERSALSTRING [type]>--

Determines the representation of the ASN.1 UTF8String type as either a C# string (default) or int[], which is the same as the representation of an ASN.1 UniversalString.

Example

In the following example, TwoByteLocal is set to the BMPString representation and FourTypeGlobal - to the UniversalString representation.

ASN.1 C#
--<OSS.UNIVERSALSTRING Module.FourByteGlobal>-- 
Module DEFINITIONS ::= BEGIN
    DefaultRepresentation ::= UTF8String
    TwoByteLocal	  ::= UTF8String --<BMPSTRING>-- 
    FourByteGlobal    ::= UTF8String
END
public partial class DefaultRepresentation : Oss.Asn1.BasePdu
{
    public string Value { get; set; }
    ...
}
public partial class TwoByteLocal : Oss.Asn1.BasePdu
{
    public string Value { get; set; }
    ...
}
public partial class FourByteGlobal : Oss.Asn1.BasePdu
{
    public int[] Value { get; set; }
    ...
}

Remarks

With the BMPString and UniversalString representations, character data is automatically converted to UTF-8 format before encoding. Also, it is converted from UTF-8 format after decoding.


--<OSS.DataCallback [absoluteReference] ["]FunctionName["]>--

Associates a field of a SEQUENCE or SET type, an alternative of a CHOICE type, or an element of a SEQUENCE OF or SET OF type with your callback function. This directive is useful when using partial decoding.

Remarks

When specified globally (either in an ASN.1 file before the module definition or in a separate directives file), the OSS.DataCallback directive takes an absoluteReference to a field.

FunctionName is used to construct names of the user-defined callback methods. There are two callback methods per directive: BeginFunctionName() and EndFunctionName().

When specified locally, the OSS.DataCallback directive must be placed next to the field definition, as shown in the following example:

age INTEGER(1..100) --<DataCallback "FunctionName">--,

It is possible for a named type to appear more than once in a PDU. When an OSS.DataCallback directive is applied to such a field, the decoder will call the same callback function for each occurrence. The callback, however, cannot differentiate a call for one field from a call for the other since they are both associated with the same function. To discern the difference, consider the OSS.InfoCallback directive.

See Also


--<OSS.DECIMAL [type]>--
--<OSS.DOUBLE [type]>--

Determines the representation of the ASN.1 REAL type as either a C# double (default) or decimal.

Example

In the following example, the OSS.DECIMAL directive is used, therefore the local DOUBLE directive overrides the global default set:

ASN.1 C#
--<OSS.DECIMAL>--
 --<OSS.DOUBLE Module.DataFolder.b>--

 Module DEFINITIONS ::= BEGIN
    DataFolder ::= SEQUENCE {
       a REAL --<DOUBLE>--,
       b REAL,
       c REAL
    }
 END
public partial class DataFolder : Oss.Asn1.BasePdu
{
    /// <summary>Field 'a'</summary>
    public double A { get; set; }
    /// <summary>Field 'b'</summary>
    public double B { get; set; }
    /// <summary>Field 'c'</summary>
    public decimal C { get; set; }
    ...
}

See Also

ASN1.RealRepresentation


--<OSS.FIELDNAME ref newName>--
--<OSS.VALNAME ref newName>--
--<OSS.TYPENAME ref newName>--

Instructs the ASN.1 compiler to use the specified newName for a value, field in a structure, or a type.

Example

ASN.1 C#
--<OSS.FIELDNAME MyMo.Item.available inStock>--
--<OSS.TYPENAME MyMo.Name Title>--

MyMo DEFINITIONS ::= BEGIN
Name ::= IA5String Item ::= SEQUENCE {
available BOOLEAN,
count 	INTEGER
}
END
public partial class Item : Oss.Asn1.BasePdu
{
    /// <summary>Field 'available'</summary>
    public bool inStock { get; set; }
    /// <summary>Field 'count'</summary>
    public int Count { get; set; }
    ...
}
public partial class Title : Oss.Asn1.BasePdu
{
    public string Value { get; set; }
    ...
}

See Also

ASN1.Nickname


--<OSS.INCLUDES "file"[, "file"...]>--

Specifies the name of one or more configuration files that you can add to the ASN.1 input. This is useful when defining different sets of compiler directives that can be included or excluded, depending on the application.

Default Behavior

By default, no configuration files are inserted into the ASN.1 input.

Example

In the following example, directives from file1.cfg and file2.cgf are inserted at the location of the OSS.INCLUDES directive:

--<OSS.INCLUDES "file1.cfg", "file2.cfg" >-- 
 Sample1 DEFINITIONS 
 EXPLICIT TAGS ::= BEGIN
...

Remarks

This directive can be specified only globally and must have at least one configuration filename as operand. The configuration file must contain global directives.

Directives obtained by specifying the OSS.INCLUDES directive can be used only on a single ASN.1 module definition and override any conflicting directives in the asn1dflt file.


--<OSS.InfoCallback [absoluteReference] ["]FunctionName["]>--

Used when an OSS.DataCallback directive is applied to a type that occurs in multiple locations in a message.

Example

For the following definition

M DEFINITIONS AUTOMATIC TAGS ::= BEGIN

PackageInfo ::= SEQUENCE {
     from         Address,
     to           Address,
     posted       DATE
}

Address ::= SEQUENCE {
     zipcode      INTEGER( 0..99999 ),
     addressline  VisibleString( SIZE (1..64) )
}
END

a directive such as

--<OSS.DataCallback M.Address.zipcode "ZipCode">--

would cause the BeginZipCode() and EndZipCode() methods to be called for both PackageInfo.from.zipcode and PackageInfo.to.zipcode, but the methods would not be able to differentiate the two fields. Use OSS.InfoCallback to solve the problem. By employing --<OSS.InfoCallback M.PackageInfo.from "fromAddress">-- you instruct the compiler to use the BeginfromAddress() and EndfromAddress() callback methods. The BeginfromAddress() method is invoked before partial decoding of the from field begins and the EndfromAddress() method is invoked after its decoding is finished.

See Also


--<OSS.LONG [type]>--

Determines the representation of the ASN.1 INTEGER type as a C# long (64-bit).

Remarks

When constraints are applied to INTEGER types, the compiler chooses the smallest representation that can carry all the required values, thus ignoring such directives, except when a directive is specified locally (inline).


--<OSS.NOVALUE val>--

Disables generation of C# value representations for the specified name.

Example

ASN.1 C#
--<OSS.NOVALUE Module.ID>--

Module DEFINITIONS ::= BEGIN
Name ::= IA5String ID ::= INTEGER
myName Name ::= "John" myID ID ::= 12345
END
public static class Values
{
    private static readonly Name _myName = new Name {
        Value = "John"
    };
    /// <summary>Represents schema value 'Module.myName'</summary>
    public static Name MyName {
        get {
            return _myName;
        }
    }
}

--<OSS.ROOT [module [{oid}] ...]>--

Identifies ASN.1 modules that are used as root modules. In a root module, all unreferenced types are considered PDUs. In addition, the scope of non-root modules is to supply external references to root modules. If no module is provided, all input modules are considered root modules.

Default Behavior

By default, the last ASN.1 input file specified on the command line contains the root module.

Example

--<OSS.ROOT DirectorySystemProtocol{joint-iso-ccitt ds(5) modules(1) dsp(12)}>--

See Also

-root


--<OSS.SUPPRESS msgID[, msgID ...]>--

Disables printing of specific informatory and warning messages.

messageID specifies which message needs to be suppressed. The messageID can be either the full message identifier (A0178W) or just the numeric part of the message number (178).

By default, informatory and warning messages are suppressed when -noRelaxedMode is turned on.

Example

In the following example, message A0178W warns that the first digit of a number in a module definition should be non-zero:

--<OSS.SUPPRESS A0178W>--
Sample DEFINITIONS ::= BEGIN Age ::= INTEGER
legalAge Age ::= 021
END

See Also


This documentation applies to the OSS® ASN.1 Tools for C# release 5.0 and later.

Copyright © 2021 OSS Nokalva, Inc. All rights reserved.
No part of this publication may be reproduced, stored in a retrieval system, or transmitted in any form or by any means electronic, mechanical, photocopying, recording or otherwise, without the prior permission of OSS Nokalva, Inc.
Every distributed copy of the OSS® ASN.1 Tools for C# is associated with a specific license and related unique license number. That license determines, among other things, what functions of the OSS ASN.1 Tools for C# are available to you.