CapeSoft Logo

CapeSoft NetTalk
Upgrading to NetTalk 10

Download Latest Version
Installed Version Latest Version

NetTalk Upgrade to NetTalk 10

 

 

Introduction

This document works through the major changes between NetTalk 9 and NetTalk 10. It is designed for users, currently experienced with NetTalk 9 to quickly identify and use the new features in NetTalk 10. It covers things that are likely to break when you upgrade your app, and instructions on how to correct the application to allow for a smooth upgrade. It also covers other new features which you may wish to make use of in your application.

I've upgraded to NetTalk 10 and I'm getting Compile Errors!

The most common cause for compile errors (in NetTalk class code, or generated code) is because one of the other related tools you are using has not been updated. Especially StringTheory and xFiles.

If you are getting compile errors in your embed code then see the list below for the various changes.

Quick Bits

The goal of this section is a quick overview of things that have changed since NetTalk 9 which experienced NetTalk 9 users will want to know about.

NOTE: NetTalk uses many of the latest methods and functions in the following products. If you are using these then please update them at the same time.
StringTheory, xFiles, jFiles, WinEvent 5, Draw 4, File Explorer 5
Desktop

Desktop

New Classes

There are a large number of new classes included in NetTalk 10. Here is a list, with links to their respective documentation.
  • NetLDAP - including access to Active Directory Directory Services.
  • NetOAuth - client-side support for Web services that use OAuth logins.
  • NetDrive - a wrapper for popular cloud storage, include Dropbox, Google Drive and Microsoft Onedrive.
  • WebSocketClient - for interacting with servers that use the WebSockets protocol.
  • NetWholePacket - split from the NetSimple class
  • NetMaps - for including interactive Maps functionality in Desktop programs.

Refactored Classes

Several classes have undergone major refactoring to make them easier to use, faster, and more consistent with the other classes. Her is a list to these classes with specific upgrade notes for those classes. While initial compiles may
  • NetSimple - Minor cosmetic changes.
  • NetWholePacket - Code simplified, excess properties removed.
  • NetWebClient - Some properties change to StringTheory, some methods renamed.
  • NetEmail - Some properties change to StringTheory, some methods removed.

OpenSSL Updates

OpenSSL support has been upgraded to version 1.1 (from 1.0) which means all new DLL names. See the section Deploying a TLS Client or Server for more details.

Support for SSLv2 and SSLv3 has been removed. The equates NET:SSLMethod3TLS, NET:SSLMethodSSLv23, NET:SSLMethodSSLv2, NET:SSLMethodSSLv3 have been removed. If you code is using one of these remove the assignment (and let the default value apply.)

Documentation

Documentation is a process, not an event. It is an ongoing effort to make sure that all information is topical, up to date, and accurate. As such if you find documentation confusing, or inaccurate, then please report it so it can be updated. If you encounter cases where documentation is hard to find (starting at the Index) then please report that as well.

Web Server

Quicklist

  • Runtime Settings Control Template
  • Refresh Server Cache button - clear the server side cache without restarting the server.
  • Support for Ranges in requests.
  • Save Form, without saving (aka Interim Save) support added to forms.
  • New Themes, Base and Material17

Date Lookup Button

The Date Lookup button now uses the global button settings, not just the Datepicker icon. You can therefore change the text, and icon, globally in the Web Server procedure on the buttons tab. the text may currently be set to ..., so this will likely need (want) to be removed.

GetContentType

During the NetTalk 9 releases the _GetContentType method was renamed to GetContentType. So if you are upgrading from an earlier NT9 build, or possibly an earlier build, and you have used _GetContentType in your embed code, then remove the underscore from the name.

Port Numbers Possibly Incorrect

The setting for the Port Number has changed. the server can now listen on 2 ports. (See Listening on 2 Ports for more on this.)

If you have an insecure server, ie one serving on a non SSL port (like port 80), then it's likely the conversion from NetTalk 9 has mis-aligned your template setting.

The setting you had will go to the Listen on Secure Port setting.
You will need to move this to the Listen on Insecure Port setting.
This is in the WebServer procedure, General tab.



If you fail to correct this you will see the following error message when the program starts;

Secure Port set to 80, but no Server Domain names are set. Server will run, but is not secure.



Changes to SSL Setup and Naming Convention

In NetTalk 8, setting up a site for TLS support consisted of a single Certificate setting. In NetTalk 9 this grew to 3 settings, allowing a comma separated list for CRT, KEY and Host names. In NetTalk 10 this is reduced again to a single setting, Host Names, and it is moved from the Security tab to the General Tab.



This is a Comma Separated list meaning that a single server can serve multiple domains.

To simplify the setup, the previously recommended naming convention for certificates is now mandatory.

CRT and KEY files must be named in the form domain.CRT and domain.KEY. For example, for the site capesoft.com, the CRT file is named capesoft.com.crt and the key file is capesoft.com.key .

The CRT and KEY file belong in the Certificates folder (by default, a child folder of the EXE folder.) the Certificates folder though can be set to a different location by changing the p_web.site.CertificatesPath property. It is also a setting which can be set via the new Settings Control Template.

Listening on 2 Ports

When NetTalk 4 came out (circa 2006) it was reasonable common for web servers to mix secure serving with insecure serving, depending on where on the site the user was. Through NetTalk 9 this was accomplished by having 2 Server objects in the WebServer procedure, one set up to listen on one port (say Port 80) and the other setup to listen on another port (say Port 443).

The web has progressed over the years and these days mixing secure and insecure pages is considered bad. So it became common to set the insecure port to simply redirect to the the secure port.

In NetTalk 10 the server is now able to listen on 2 ports, and so it becomes trivial to set the server to listen on an insecure port, and automatically respond with a 301 Moved Permanently message to the browser which then knows to use the secure port instead.

It will thus be necessary to remove the second object in the WebServer procedure, and just set the two port numbers for the primary object correctly.

Responsive Layout

To enable responsive code generation;
WebServer procedure, Defaults Tab, Browse Tab, Layout Method, Children Layout Method, Set both to Div.
WebServer procedure, Defaults Tab, Form Tab, Layout Method, Set Div.

Changes Required to Convert your App from NetTalk 9 to NetTalk 10

Embed code in NetSimple, NetSimple with WholePacket support, and NetWebClient classes may need altering.

NetSimple

  1. _SSLSwitchToSSL method renamed to SwitchToSSL
  2. WholePacket support has been removed (see below)

NetWholePacket

The WholePacket functionality has been refactored to make it easier to use, and more consistent with the other classes. If you are using WholePacket functionality in your program then you will need to tweak your code as described below. The changes have been carefully engineered to generate compile errors, so once your program compiles error free then all the necessary changes should have been made.
  1. The WholePacket functionality has been removed from the Netsimple class and moved to its own class, NetWholePacket. If you have an object, using NetWholePacket then change the class it uses from NetSimple to NetWholePacket.
  2. Whole packets used to flow through the Process method, with a packet type set to NET:SimpleWholeDataPacket. The code in here should be moved to the PacketReceived method. This method is only called when a complete packet arrives.
  3. The use of WholePacketQueue.WholeBinData and WholePacketQueue.WholeBinDataLen in PacketReceived has changed. You should now use self.WholePacket.GetValue() and self.WholePacket.Length()
  4. The WholePacketSend method has been renamed to Send.
  5. The WholePacketUseLengthField has been renamed to UseWholePacket. Instead of setting this to 1, or true, it should be set to netWPP:LengthPrefix.
  6. WholePacketUseBigEndian property renamed to UseBigEndian
  7. WholePacketLengthInclusive property renamed to LengthInclusive

WebClient

  1. In NetTalk 10 the Page property (which was a STRING) is now renamed as ThisPage, and is declared as a STRINGTHEORY object.
    This will affect code you may have embedded in the PageReceived method.
    The contents of the ThisPage property can be retrieved using ThisPage.GetValue(). For example
    whatever(self.page)
    would be replaced with
    whatever(self.thispage.GetValue())
  2. The PageLen property has been removed. Use self.ThisPage.Length() instead.
  3. The _Command property (String) has been replaced with _CommandText (StringTheory.)
    Use _CommandText.GetValue()
  4. The _PageContentLen property has been renamed to PageContentLen.
  5. The _GetContentType method has been renamed to GetContentType.
  6. The _HTTPVersion property has been renamed to HTTPVersion. As from version 9.20 this property defaults to 1.1 not 1.0.
    If you have this line in your embed code;
    net._HTTPVersion = 'HTTP/1.1'
    then you can just remove the line.

Other CapeSoft Accessories

NetTalk 10 uses features in StringTheory 2.63. As a rule of thumb when updating NetTalk make sure StringTheory is updated as well.

NetTalk makes use of many features in jFiles and xFiles. If you are using these then make sure you are on the latest versions.

Safe Update is derived from the NetWebClient class. As such SafeUpdate was tweaked to support the new code in NetTalk 10. When upgrading to NetTalk 10 also upgrade your install of Safe Update to build 3.13 or later.

WebServer

If you are creating a non-TLS web app, then see Port Numbers Possibly Incorrect.

If you are creating a TLS (secure) web app then see Changes to SSL Setup and Naming Convention and Listening on 2 Ports.

[End of this document]
Return to NetTalk Documentation Index