AF SDK .NET Version Differences

The .NET Framework version of AF SDK is packaged in the AF Client Windows install kit that must be run by a system Administrator at the time of installation. The installation process is responsible for setting up various system folders and configuration files and ensuring proper permissions are in place.

Since the .NET 8 version of AF SDK is only distributed as a NuGet package, there is no installation process. Therefore, some additional configuration is required prior to use.

The only required setup step prior to using the .NET 8 AF SDK is installation of the latest x64 Microsoft Visual C++ Redistributable. If it is not installed or the version installed is older than the minimum required version, users will see a runtime exception indicating the required version was not found. You can find the latest x64 installer here: https://learn.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist

Additionally, AF SDK utilizes various supporting configuration files. AF SDK will create the necessary folders and files at runtime, but behavior will vary depending on the user’s permissions and the application’s user context. Note that you may choose to run a .NET Framework AF Client installation on the client machine to get the benefit of the installation process even when running a .NET 8 application.

When running a .NET 8 AF SDK application, consider the following configuration details:

• The following configuration files are required by AF SDK. By default, they will be created in the %PROGRAMDATA%\OSIsoft\AF folder as a system-wide configuration. If the user running the application does not have write access to that location, the files will be created in the user’s %APPDATA%\OSIsoft\AF folder.

  • AFSDK.config - Contains AF SDK global settings as well as the list of known PI Asset Framework servers.

  • PIDataArchiveKST.config - Contains additional settings related to PI Data Archive connections as well as the known list of PI Data Archive servers.

• The following configuration files are optional, and defaults will be used if not present. Files must be in the %PROGRAMDATA%\OSIsoft\AF folder to be loaded.

  • AFCertificate.config - On a client machine, specifies the certificateMode for TLS cert validation. “AllowExpiredOrRevoked” is used by default.

  • AFTrace4.config - Used to specify custom trace listeners for logging. None are enabled by default.

• AF SDK uses PlugIns which can be loaded from multiple different locations on the system. The .NET 8 AF SDK NuGet package includes the standard client PlugIns which will therefore be included in the build output of any application using the .NET 8 AF SDK. PlugIns will be loaded from the application directory. If not found there, they will be loaded from the %PROGRAMDATA%\OSIsoft\AF\PlugIns folder provided the user has access to that folder.

The AF SDK UI library containing common components is not available in the .NET 8 version. Furthermore, there are no dialogs for user input or confirmation in the .NET 8 AF SDK. For example, if a user fails to authenticate, they will not see a login prompt dialog.

The .NET Framework version of AF SDK contains functionality providing interoperability with PI SDK. Since PI SDK does not have a .NET 8 version, that functionality has been removed in the .NET 8 AF SDK.

Removed methods & properties:

• AFAttribute.RawPIPoint

• AFAttribute.RawPIPointPath

• AFValue.ToPIValue()

• AFValue.FromPIValue()

• AFValues.ToPIValues()

• AFTime.PITime

• AFTime constructor no longer works with a PITime object

In .NET Framework, some DateTime operations are rounded to the nearest millisecond while in .NET 8+ those operations will use full precision. This could result in different results for TimeSpan values returned from AF SDK between the versions beyond millisecond precision.

Parsing and formatting of floating-point numbers has been improved in .NET compared to .NET Framework resulting in potential differences in display values when displaying values as strings or performing string conversions.

.NET Framework relies on National Language Support (NLS) for globalization functionality while .NET by default uses International Components for Unicode (ICU). There will therefore be some changes in behavior when dealing with string values in AF SDK between the .NET Framework and .NET 8 versions. Specifically:

• Sort order of strings may differ in cases of non-alphanumeric characters.

• Zero-weight characters are ignored in some string operations (e.g. null characters, control characters) in ICU but they are not ignored in NLS.

• Ligature characters that are used to join two letters together (e.g. Æ, Œ, or ß) are not considered equal to their non-ligature counterparts in ICU but they are in NLS.

BinaryFormatter is removed in the .NET 8 version of AFSDK, so the “EnableBinaryFormatter” AFSDK configuration setting is also removed. Only explicitly implemented/allowed data types can be serialized and deserialized in the .NET 8 AFSDK. If you encounter a value that cannot be read using the .NET 8 AFSDK, you may need to use the .NET Framework version with the “EnableBinaryFormatter” flag set to true.