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:

How to proceed

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

Modify the AssemblyInfo.cs 

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

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" -comment "This is a test comment from $(USERNAME)" -accessToken "<YourPATforEADNSigningService>" -assemblies "<SourceFolderWithPreSignedFiles>\$(TargetFileName)" -destinationPath "<TargetFolder>" -deleteAfterwards

Parameter description

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

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 given folder in parameter  destinationPath.

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

a) 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. 

b) 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: 

Outdated process: Using the EPLAN File Exchange

As an old alternative to the "Upload files manually" step, you can use the outdated but still working method of uploading via EPLAN File Exchange:

Requirements

You need the login data of your account for the EPLAN file exchange website and the main administrator of your EPLAN cloud organization will get informed about new entitlement for using the cloud-based EADN Signing service.

Zip and Upload to EPLAN File Exchange

Create one or several ZIP archives containing all the assemblies to be signed. Please take into account that the zip files may not be password-protected. 

Log in to the EPLAN file exchange portal at https://service.eplan.de/exchange with the login data mentioned above. 

Select the software project for which the assemblies should be signed. The project has to be the same as the one for which you received and used the respective public key. 

Now upload the zip file to our server by clicking Upload one file, selecting the zip file and clicking Upload. This triggers the signing process. 

Receive the signed Assemblies

As soon as your files have been signed you will receive an email that you can download the ready-signed files again from our file exchange portal. Log in again and find your files under "My downloads". The ZIP file contains an additional log file with a message, whether the signing was successful or not. In case the signing procedure failed, the log file will contain further information about the problem. 

What to do in case of problems

In case of any problems with signing, please write to EPLAN API Support: support-eplan@eplan.de.