Getting started with the Qlik Sense .NET SDK

The Qlik Sense .NET SDK is a development toolbox for use with applications such as Microsoft Visual Studio. To use the Qlik Sense .NET SDK, you need to be able to connect to Qlik Sense, access the server, create the right kind of session, and interact with either the Hub object for management tasks or App objects for tasks within apps.

Before you start, you will need to know:

• Your security settings. The setup of the URI depends on your security settings. These are defined in the QMC. For more information, see QMC - Proxies. You can also ask your IT administrator.
• Whether you want to authenticate to Qlik Sense Server with a proxy (QPS) or without one.

• If you authenticate to Qlik Sense Server with a proxy (QPS), which one of the three modes, you want to authenticate with (NTLM, NTLM and other credentials, or Static header). To find out which mode to use, check your settings in the QMC.

To get started and connect to the Qlik Sense installation using the Qlik Sense .NET SDK follow these four steps:

1. Identify the URI needed to connect to Qlik Sense.
2. Get access to the Qlik Sense Server.
3. Decide which session type to use.
4. Interacting with the Qlik Sense.

When you have worked through these steps, you will have successfully connected to the engine and run a simple request.

We recommend that you download and run the appropriate example before you continue reading. All the sample code for the connection examples is available on GitHub.

Source code found on GitHub (only in English)

Identify the URI needed to connect to Qlik Sense

These examples are written for someone using Qlik Sense Server. If you work with Qlik Sense Desktop, continue straight to Interact with Qlik Sense.

To connect to Qlik Sense with the Qlik Sense .NET SDK, identify the URI for the Qlik Sense Server.

Example: https://server.domain.com:4747

• WebSocket protocol: https or wss.
• Host: FQDN (Fully qualified domain name) or IP address.

• Port: With proxy (443), without proxy (4747) or without security (80).

  For more detailed information regarding ports, see Port overview.

Verify the URI by copying and pasting it into a web browser to open the hub. If the hub does not appear, see Troubleshooting .NET SDK.

Get access to the Qlik Sense Server

The next step is to set up the security mode for the communication. If the security mode is not established, access to the location object will be refused. Authenticate to Qlik Sense Server either with a proxy (QPS) or without.

Authentication with proxy

When you connect to Qlik Sense Server through the proxy there are three possible authentication modes to use:

• NTLM (NT LAN Manager)

  By default, NTLM authentication is used to connect to a Qlik Sense installation.

  When you connect to several Qlik Sense servers on the same domain, use the AsNtlmUserViaProxy method. Windows sends the credentials of the logged-on user and the domain.

• NTLM and other credentials

  When you connect to Qlik Sense Server on other domains, such as Azure or Amazon, or when you want to authenticate as a user other than the logged-on user, use the AsNtlmUserViaProxy method. You supply the credentials to be used for authentication.

• Static header

  When you send authentication information with a static header, use the AsStaticHeaderViaProxy method. You supply a user ID, and a header name as a description.

  When using static headers, you can still use SSL by setting proxyUsesSsl to true. By default, the AuthenticationHeaderName is X-Qlik-User. For information about how to configure AuthenticationHeaderName, see Authentication methods.

  Information noteOnly use this setting when you can restrict who is allowed to send users to the proxy.

In all cases, you use the appropriate method on the Qlik.Engine.Location object. If you use a virtual proxy, the parameter VirtualProxyPath has to be set on the Qlik.Engine.Location object.

QMC - Virtual proxies

Authentication without proxy

If you access a Qlik Sense Server and bypass the proxy, use the AsDirectConnection method, which takes a User Directory and a user as parameters. By default, the parameter extendedSecurityEnvironment is set to false. For more information, see Create virtual proxy.

When you access the Qlik Sense Server directly, the certificates must be available. If you connect to a the local computer, the certificates should already be in place. If you connect from a remote server, export the certificates from the QMC and install them locally or pass them as a parameter. For information about exporting certificates, see Certificates.

Decide which session type to use

When you use the Qlik Sense .NET SDK, you work in engine sessions. Within an engine session, you must connect to the Qlik Sense Server using proxy sessions for each connection. The engine sessions may be client, named, or isolated sessions.

Decide which type of session to work with.

• Client session

  A client session works between your application and the Qlik Sense client. If you connect to the Qlik Sense Server, you join the client session by default. Set the session by the ISession method and specify when connecting to the app.

  Example

  
  	IAppIdentifier appIdentifier = location.AppWithId("AppId");
  	ISession defaultSession = Session.Default;
  	using (IApp app = location.App(appIdentifier, defaultSession))
  	{
  		//..
  	}

• Named session

  A named session is used when different clients want to join the same session without interfering with the Qlik Sense client. This could for example be used between a Windows application and a Windows service. You set the name for the session. The session can be set by the ISession method and supplied when connecting to the app.

  Example

  
  	IAppIdentifier appIdentifier = location.AppWithId("AppId");
  	ISession customAppSession = Session.WithApp(appIdentifier, "MyCustomSession");
  	using (IApp app = location.App(appIdentifier, customAppSession))
  	{
  		//..
  	}

• Isolated session

  An isolated session is used a to ensure that no other clients joins the session. You set the session using the ISession method and supply it when you connect to the app. For information about sessions, see Sessions.

  Example

  
  	IAppIdentifier appIdentifier = location.AppWithId("AppId");
  	using (IApp app = location.App(appIdentifier, Session.Random))
  	{
  		//..
  	}

Interact with Qlik Sense

You can now interact with Qlik Sense. This can be done through the Hub, to perform tasks on management level, or through the App object, to perform tasks within an app.

	Uri uri = new Uri("ws://127.0.0.1:4848");
	ILocation location = Qlik.Engine.Location.FromUri(uri);

	Uri uri = new Uri("http://localhost:4848");
	ILocation location = Qlik.Engine.Location.FromUri(uri);

	private static void HubInformation(ILocation location)
	{
		using (var hub = location.Hub())
		{
			Console.WriteLine("Product Version: " + hub.ProductVersion());
			Console.WriteLine("OS Name:    " + hub.OSName());
			Console.WriteLine("OS Version: " + hub.OSVersion());
		}
	}			

       private static void ListApps(ILocation location)
	{
		foreach (var appIdentifier in location.GetAppIdentifiers())
		{
			try
			{
				using (var app = location.App(appIdentifier))// Location specified in Accessing
				{
					var layout = app.GetAppLayout();
					Console.WriteLine(layout.Title + " [" + app.Type + "]");
				}
			}
			catch (MethodInvocationException e)
			{
				Console.WriteLine("Could not open app: " + appIdentifier.AppName + Environment.NewLine + e.InvocationError.Message);
			}
			catch (TimeoutException e)
			{
				Console.WriteLine("Timeout for: " + appIdentifier.AppName + Environment.NewLine + e.Message);
			}
		}
	}			

	private void OpenApp(bool noData = false)
	{
		IApp app;
		String appname = "YourAppName";

		try
		{
			ILocation location = Qlik.Engine.Location.FromUri(new Uri("ws://127.0.0.1:4848"));
			location.AsDirectConnectionToPersonalEdition();

			var appIdentifier = location.AppWithNameOrDefault(appName);
			if (appIdentifier == null)
			{
				MessageBox.Show(@"The app (" + appName + @") does not exist.");
				return;
			}
			ISession session = Session.WithApp(appIdentifier, SessionType.Default);
			app = location.App(appIdentifier, session, noData: noData);
		}
		catch (MethodInvocationException invocationException)
		{
			MessageBox.Show(@"Error for details see invocationException.InvocationError.Code.");
			return;
		}
		catch (Exception exception)
		{
			MessageBox.Show(@"No engine found, make sure the engine is started and try again." + "\n" + exception.Message);
			return;
		}
		NxAppLayout appLayout = app.GetAppLayout();
		if (appLayout.IsOpenedWithoutData)
		{
			MessageBox.Show(@" - Opened without data");
		}
		else
		{
			MessageBox.Show(@" - Opened with data");
		}
	}

To verify the connection use the Location.IsAlive method. This method returns True if the connection is successful.

There are several ways to connect to Qlik Sense through the Qlik Sense .NET SDK, depending on how you want to interact with your applications and expand your Qlik Sense solution. See, Sample code for how to connect to Qlik Sense.