| Refresh | This website www.ni.com/en/support/documentation/supplemental/15/national-instruments-visa--net-library.html is currently offline. Cloudflare's Always Online™ shows a snapshot of this web page from the Internet Archive's Wayback Machine. To check for the live version, click Refresh. |
This page covers the key features of the NI-VISA .NET library. To download the NI-VISA .NET library and find documentation and examples, refer to .NET Resources for NI Hardware and Software.
The NI-VISA .NET library contains classes that provide a .NET interface to NI-VISA. This library is compliant with the VISA Implementation Specification for .NET authored by the IVI Foundation. This library supersedes the NI VisaNS library, which was implemented before the IVI Foundation standardized the .NET API to VISA. NI-VISA is the NI implementation of the industry standard Virtual Instrumentation Software Architecture (VISA) specification. Together, the VISA and VISA .NET specifications define a standard, consistent API for communicating with instruments and other devices in the .NET environment. NI-VISA .NET supports several bus and interface technologies, including TCP/IP, USB, GPIB, Serial, and PCI/PXI. The classes provided by the NI-VISA .NET library implement interfaces and use types that are defined in the IVI VISA .NET library (Ivi.Visa) that is provided by the IVI Foundation. For more details about the IVI VISA .NET library, refer to VPP-4.3.6: VISA Implementation Specification for .NET.
In a typical application, NI recommends that you use an instrument driver specific to your instrument if one is available. Refer to the Download API for Third Party Instrument section of .NET Resources for NI Hardware and Software for where to download instrument drivers. Use the NI-VISA .NET library only if such a driver is not available or you need additional features that are not available in the driver.
The NationalInstruments.Visa namespace includes .NET classes that provide a rich, object-oriented interface to the NI-VISA driver. The VISA session object is the fundamental concept in the VISA API specification. A VISA session identifies a resource. There are several types of resources, including instrument resources, socket resources, and interface resources. In the NI-VISA .NET class library, classes that derive from Session, referred to as Session-derived classes, encapsulate VISA session objects.
Methods of Session-derived classes perform operations, such as reading or writing data, on the VISA session object. Methods of NI-VISA .NET classes map to operations in the NI-VISA C API. Properties of Session-derived classes configure the VISA session object and map to attributes in the NI-VISA C API.
Session-derived classes have .NET event members. You can register a delegate with a .NET event to receive notification when the event occurs. Session-derived class methods and properties perform error checking and translation of NI-VISA driver error codes into .NET exception types.
The primary classes in the NationalInstruments.Visa namespace are GpibSession, PxiSession, SerialSession, TcpipSession, TcpipSocket, UsbSession, and VxiSession. These Session-derived classes, also referred in this document as the “leaf” classes, derive indirectly from Session. These classes provide the core VISA functionality. Each Session-derived class represents a VISA resource type. Each Session-derived class exposes only the methods, properties, and events that are valid for the resource type that the Session-derived class represents. GpibInterface, PxiBackplane, PxiMemory, UsbRaw, VxiBackplane, and VxiMemory are additional Session-derived leaf classes for advanced applications.
To communicate with a VISA resource in a typical .NET application or library, create an instance of the specific Session-derived class that corresponds to the resource. Set properties on the instance to configure the resource. Call methods on the instance to read from and write to the resource. You must call Dispose to release the resource when you no longer need to access it.
Some types of applications or libraries, such as instrument drivers, must access resources in an interface-independent manner. NI-VISA .NET includes additional classes that you can use to create and access VISA resources in an interface-independent manner. For example, to create an object you can use to communicate with an instrument over a GPIB interface or serial interface, call Open and cast the return value to MessageBasedSession.
The primary set of operations you perform on a Session-derived object is the set of input/output operations. The operations you use for I/O for message-based resources are different than the methods you use for register-based resources. Each Session-derived leaf class provides only the I/O methods that are appropriate for the resource that the Session-derived class represents.
To communicate with message-based resources, you must pass strings or byte arrays between the application and the resource. A GPIB instrument is an example of a message-based resource. To communicate with register-based resources, you must set registers on the resource or directly access memory exported by the resource. A PXI instrument is an example of a register-based resource.
Session-derived classes that represent message-based resources include a RawIO property that provides methods you can use to read from and write to message-based resources. The RawIO object provides both synchronous and asynchronous read and write methods. Synchronous methods perform the entire operation and return when the operation completes. Asynchronous methods start the operation, return immediately, and when the operation completes, call a delegate you provide or hold the data until you request it.
Use ReadString to synchronously read a string from a resource. Use Read to synchronously read an array of binary data from a resource. Use BeginRead to start an asynchronous read operation. Use EndReadString or EndRead to obtain the result of an asynchronous read operation.
Use Write to synchronously write a string or an array of binary data to a resource. Use BeginWrite to start an asynchronous write operation. Use EndWrite to obtain the result of an asynchronous write operation.
Session-derived classes that represent message-based resources include a FormattedIO property that provides higher-level formatted I/O operations you use to read from and write to message-based resources.
Use one of the Write or WriteLine methods to synchronously format and write text-based messages to the resource. Use WriteBinary to send blocks of binary data. Use the BinaryEncoding property to specify how the FormattedIO object formats binary data.
Use one of the Read methods to synchronously read and parse text-based messages and binary data from the resource. The various Read methods include functionality for reading byte, character, double, integer, and floating point values. For example, ReadInt64 reads an ASCII-encoded Int64 value and ReadDouble reads an ASCII-encoded Double value. Use the BinaryEncoding property to specify how the FormattedIO object parses binary data.
Use one of the Printf methods to format the data into the specified format and write to the resource. Use one of the Scanf methods to read a formatted string from the resource and parse the string according to the specified format. The format specifiers used in the format string provided to the Printf and Scanf methods are very similar to those used for the VISA viPrintf and viScanf functions, with some differences. For more details about the FormattedIO methods and supported format specifiers, see the description of IMessageBasedFormattedIO in the VPP-4.3.6 specification.
Session-derived classes that represent register-based resources include methods you use to read from and write to memory that is exported by register-based resources.
Use In8, In16, In32, and In64 to read scalar values from device memory. Use MoveIn8, MoveIn16, MoveIn32, and MoveIn64 to read arrays of values from device memory.
Use Out8, Out16, Out32, and Out64 to write scalar values to device memory. Use MoveOut8, MoveOut16, MoveOut32, and MoveOut64 to write arrays of values to device memory.
The NI-VISA driver returns error codes that indicate the success or failure of an operation. When a NI-VISA .NET method call or property access results in an error in the NI-VISA driver, the .NET class creates and returns an Ivi.Visa.NativeVisaException. The ErrorCode property in this exception object contains the error code that the NI-VISA driver operation returned.
Various MessageBasedSession methods to read and write data will return an Ivi.Visa.IOTimeoutException if the operation timed out. The ActualCount property in this exception contains the number of elements read or written before the timeout occurred. The ActualData property in this exception contains the bytes read or written before the timeout occurred.
For a list of all NI-VISA error codes, refer to the Error Codes topic in the NI-VISA Help. To access the NI-VISA Help from the Start menu, select Start»Programs»National Instruments»VISA»NI-VISA Help.
The ResourceManager class provides functionality for locating, parsing, and opening Session-derived classes with resource names. Use Open to instantiate the appropriate Session-derived class depending on the given resource name. Use Find to obtain a list of resource names available in the application domain, given a search expression. Use Parse to obtain additional information about a resource name.
You must call Dispose to release the resource when you no longer need to access it. Any Session-derived object instantiated using the Open method is still valid after the ResourceManager instance is disposed.
The NI-VISA .NET API is similar to the VisaNS API and supports majority of the features VisaNS provides. VisaNS is the legacy .NET API for VISA created by NI before the standard specification was available. NI recommends that you use the standard NI-VISA .NET API instead of VisaNS for any new application that you develop. Support for the legacy VisaNS API will be removed in a future release.
In addition, it is possible to modify applications that use the VisaNS API to use the standard NI-VISA .NET API instead. For example, the supported Session-derived classes in the new API are similarly named with similar constructors. However, because the new API implements interfaces specified by the IVI specification and uses several types defined in that specification, the actual members of these Session-derived classes are different from those in VisaNS and therefore will require manual changes to your applications to migrate from VisaNS to NI-VISA .NET. In some cases, such as the formatted I/O functionality, the API is significantly different from VisaNS and may require larger changes for migration.
Some features supported by the VisaNS API are not supported or are supported differently in the NI-VISA .NET API. Some of the major differences are described below.