As a part of your EADN (Eplan API Developer Network) partnership with Eplan GmbH & Co. KG, you get the opportunity to sign your software interface with our products. This allows you (or your customer) to use the API assembly without having an Eplan API developer license on his workstations. Instead, he receives – through you – a runtime license for an API interface. 

This chapter describes how you (or your developers) should proceed, to get properly signed EADN modules. 

What is possible with API licenses?

At first there should be clarified why signing is necessary. There are 2 kinds of API licenses: 

a) API developer license – It should be used only for development and testing of an API interface. Normally it has a limitation of a maximum size of Eplan projects to 5 pages. Only unsigned API programs can be loaded using it.

b) API runtime license – In this case there can be used only signed API programs, so we need to sign it. The routine how to do it is described bellow. 

A user can check available licenses and select one by starting Eplan with shift key (then the Select license dialog will appear). When Eplan is already running, the current license can be retrieved from: 

a) the About Eplan dialog

b) in the API using the  EplApplication.License  property and the  License  class. 

The Concept of EADN / API Runtime signing

EADN / API Runtime signing uses a concept of combining standard .NET strong-naming with additionally including an Eplan license option to the software.
To achieve this combination, please follow the instructions in this chapter. 

Requirements

After you have concluded your EADN contract or purchased an API Runtime license and you created a new software interface with Eplan, the main administrator of your Eplan cloud organization will get informed about a new entitlement for using the cloud-based EADN Signing service. Additionally, you will receive a file containing the public part of a standard signature key, normally used for strong-naming a .NET assembly. We created this key especially for your software. 

For using the Eplan-Cloud based signing service, you have to be member of the regarding organization and got assigned the role User to the application EADN Singing:

Check available licenses inside active organization

Public pre-signing keyfiles (e.g.  1234_public.snk, refer to Delay sign the assemblies) that are used inside a Visual Studio project must match the used Eplan Cloud organization.
To verify which pre-signing keyfiles can get used inside the active Eplan Cloud organization, authorize (refer to Authorize manual usage of EADN-Signing) and use the endpoint GET /licenses  and check the result.

1. Click on endpoint GET /licenses 
   → Section gets expanded and shows more details
2. Click on Try out
3. Click on Execute
4. Check Response of server in section Code

The above example shows property  optionId  with the value 1234, which means assemblies with the used pre-signing keyfile  1234_public.snk  would be allowed to get signed inside the active Eplan Cloud organization.

Example of response if no pre-signing key is assigned to the current organization ➔ organization not allowed to sign assemblies. 

How to proceed

Take the following steps to get your application EADN / API Runtime signed: 

Modify the AssemblyInfo

In your software projects, you need to add an additional attribute to your  AssemblyInfo  files of all the assemblies that are referencing Eplan API Assemblies. The  EplanSignedAssemblyAttribute  is implemented in the  Eplan.EplApi.Starter.dll, which you always have to reference in your API application. The following example shows how to use the attribute in your  AssemblyInfo  file:

using System.Reflection;
using System.Runtime.CompilerServices;
using System.Runtime.InteropServices;
using Eplan.EplApi.Starter;
//..
[assembly: EplanSignedAssemblyAttribute(true)]

Delay sign the assemblies

The easiest way for delay signing your assemblies (DLL  or  exe) is entering the public key file in the signing properties of your software projects in Visual Studio. Check Sign the assembly and activate the Delay sign only flag. See the following image: 

The delay signing is done, when building the software project and with it creating the assembly. 

Alternatively, you can use Microsoft's Assembly Linker  Al.exe  to manually delay sign assemblies. Please refer to respective MSDN documentation. 

Upload files manually

Log in to the Eplan Cloud Developer Portal https://developer.eplan.com.

Authorize manual usage of EADN-Signing

1. Select EADN-Signing in available list of APIs
2. Click on Authorize
     → The authorization dialog opens
3. Click the drop-down list and select EADN Signing
4. Click on Authorize
     → The API is allowed for manual usage via Try it out feature
5. Click on Close
     → The authorization dialog is closed
     → Activated authorization is shown via closed lock symbol

After successful authorization, the entry USER is displayed as active role:

Example when authorization was not successful:

Upload pre-signed assemblies / executables

1. Click on endpoint POST /assemblies
     → Section gets expanded and show more details
2. Click on Try it out
     → Enables value entry in the Request Body section
3. Click on Add file item
     → Adds a new Choose file row
4. Click on Choose file
     → File selection dialog opens
     → Select pre-signed assembly
     → Confirm with Open to add local file for upload
     → Repeat steps 3 and 4 for each file which needs to get signed
5. (Optional) Add personal Comment for full upload-job
     → The authorization dialog is closed
6. Click on Execute
     → All selected files will get uploaded and tried to get signed
7. Check Response of server in column Code
8. Select and copy value of ID in Response body, for later usage of all files

Check status of uploaded files

Log in to the Eplan Cloud Developer Portal https://developer.eplan.com.
If required, perform Authorize manual usage of EADN-Signing.
Make sure you have the ID of the desired upload process handy (see also Select and copy value of ID in Response body).

1. Click on endpoint GET /assemblies/{id}/status
     → Section gets expanded and show more details
2. Click on Try it out
     → Enables value entry in the Parameters section
3. Insert previous copied ID into parameter Id of the uploaded package
4. Click on Execute
     → Details about given signing job are getting returned
5. Check response of server in section Responses and get details about results of signing process

Receive the signed Assemblies manually

Log in to the Eplan Cloud Developer Portal https://developer.eplan.com.
If required, perform Authorize manual usage of EADN-Signing.
Make sure you have the ID of the desired upload process handy (see also Select and copy value of ID in Response body).

1. Click on endpoint GET /assemblies/{id}
     → Section gets expanded and show more details
2. Click on Try it out
     → Enables value entry in the Parameters section
3. Insert previous copied ID into parameter Id of the uploaded package
4. Click on Execute
     → Download request is getting executed
5. Click on Download file in section Responses
     → Save file selection dialog opens
     → Confirm with Save to download the file

Delete uploaded files manually

Log in to the Eplan Cloud Developer Portal https://developer.eplan.com.
If required, perform Authorize manual usage of EADN-Signing.
(see also Limitations below)
Make sure you have the ID of the desired upload process handy.
(see also Select and copy value of ID in Response body)

1. Click on endpoint DELETE /assemblies/{id}
     → Section gets expanded and show more details
2. Click on Try it out
     → Enables value entry in the Parameters section
3. Insert previous copied ID into parameter Id of the uploaded package
4. Click on Execute
     → Delete request is getting executed
5. Check result request in column Code in section Responses

Fully automated signing process

Preparations / prerequisites

To take advantage of fully automated signing of assemblies during the build process of Visual Studio, you must create a personal access token (further called PAT) for the application EADN Signing inside the profile editor of your Eplan Cloud organization.

See Eplan Cloud help:
   • Open My Settings
   • Add personal access token (PAT)
   • Roles and permissions

Download the provided PowerShell script from the Developer Portal  EADN Singing for using it in Post-build event of Visual Studio.

An example for calling the script including available parameters can be found inside the script itself:

# Example command line:
#
# powershell -ExecutionPolicy Bypass -file "<YourFolderName>\PostBuildScript.ps1"

Parameter description

*current baseUrl can be viewed at any time in the Developer Portal

Examples for all countries except China

This allows, for example, files with the same name to be processed in one signing operation.

Examples for China only

Adopt command line for PostBuild-event in Visual Studio

1. Click on Build events
     → Pre- and Post-build details of Visual Studio are shown
2. Click on Edit Post-build…
     → Post-build Event Command Line dialog opens
3. Paste required command line call
4. Click on OK
     → Post-build Command Line dialog is closed

Output console will show details after building:

All files (no matter if singing process was successful or not) will get extracted to the given folder in the  destinationPath  parameter.

Limitations

  • The filenames in one upload have to be unique. Adding the same filename multiple times (on the same folder level) is not allowed, because it can not be reflected in the ZIP-file for download.

  • Each upload job can have a max. total file size of ~40 MB

  • There is an upload limit of max. 9999 kept upload jobs for each organization.

  • No automatic “cleanup” is done in organization storage.

  • If upload limit is reached, older uploaded files have to get deleted before new uploads are possible.

Special cases

How to sign automatically generated serialization DLLs

If you use an automatically created serialization DLL for your classes, you need to delay-sign them via the  sgen.exe  tool. This tool can be found the SDK directory of your development environment. 

Signing of your own COM interop DLLs

As you probably know, any strong-named .NET assembly can only reference / load other strong-named assemblies. In case your application registers COM DLLs, the development environment normally automatically creates so-called interop DLLs, which contain the .NET wrapping of the respective COM methods. Normally, these DLLs are not signed. To create these assemblies in an already delay-signed way Microsoft provides the command line tool tlbimp.exe – also to be found in the SDK directory of your development environment. See the following example, how it is used: 

What to do in case of problems

If you encounter issues with the signing process, please contact the Eplan Global Support Portal.