GETTING STARTED

When creating a new application targeting .NET 6, there are a few steps you will need in order to get the project up and running. Our .NET 6 components have hard dependencies on certain windows components and thus are not able to be hosted on Linux / in Linux containers. They are windows only.

TECHNICAL REQUIREMENTS

.NET 6

It is important to note that this article applies only to 11.4.0 and newer, using our new 5.0 dlls to target .NET 6.

In theory you could use this to target .NET 7 or .NET 8, but we're going with .NET 6 as it's the lowest common supported version number.

The reason our DLLS are labeled 5.0 is that our .NET 5 dlls work for both .NET 5 and .NET 6 - however, Microsoft has end of life-end of supported .NET 5, thus we will be using our SDK to target and support .NET 6 in this instance.

Development Tools/Environment

This document and our SDK assume that you're a developer familiar with basic use of Visual Studio and general c# application development practices using MS Visual Studio 2022 or later. The samples will be using a 64 bit console application targeting .NET 6.0, though the practices apply to any application that uses DotImage in .NET 6 and up

We will be providing examples in C#. Our SDK works with VB.NET as well, but for the sake of simplicity any .NET code will be provided in C#. You can use a converter tool such as Telerik Code converter to convert examples to VB.NET.

SDK Requirements / Versions

A brief set of instructions for downloading our SDK and activating a license will be given, but the rest of the document assumes you've installed the latest DotImage SDK (currently 11.4.0.8 as of June, 2023)

We will be referencing local DLLs but will provide some additional alternate instructions for NuGet packages. However most screenshots will be based on this local install version

If you're a licensed developer, or are actively evaluating our SDK and run into problems/questions, you are welcome to contact support. You can make a support case in writing at our support portal. You may also call in to support during our normal business hours Support Hours: M - F from 8AM - 5PM EDT (New York Time)

Call us: 1-781-743-2119

INSTALLATION AND LICENSING

You may have already installed our SDK from the download site latest version of Atalasoft DotImage SDK, and activated a paid or eval license. If so that's fine. The licensing can be done using our licensing component NuGet package...

NOTE: The current version is 11.4.0.8 as of June 2023. updates of the SDK happen with regularity. We work hard not to make breaking changes so this guide should be compatible with future releases. We will update the specific technical details as needed as changes arise.

If you have not done so, please log in or create an account with Atalasoft so that you can activate our SDK.

EXAMPLE

BUILDING A MINIMAL .NET 6 CONSOLE APP USING DOTIMAGE

We're going to create a minimal Console app using DotImage and targeting .NET 6

It starts from the assumption that on your dev machine, you've installed Visual Studio 2022 and Atalasoft DotImage SDK 11.4 (we will be using 11.4.0.8 which is the current version as of this writing) You can choose to use the NuGet packages instead, We'll provide alternate instructions, but screenshots will be based on the installed SDK version

Starting the Project

• Open Visual Studio 2022 and go to File -> New -> Project
• On the Create new Project dialog we will be selecting Console app,
  And it's important to chose the "Console App" and not "Console App (.NET Framework)" in this case
  
• select that and click next
• On the Configure your new Project page, chose your project name and Location
  • For our needs we have called it "Net6AtalaConsole"
  • the location should be a convenient path/location on your machine
  • Leave the other items defaults - we will create a new solution and place solution and project in the same directory
    
  • Click Next
• In the Additional information, select .NET 6.0 (Long Term Support)
  • and please CHECK the "Do not use top-level statements"
  • While it's fine to uncheck this - all further screenshots will be based on this choice and so in order for your first project to look as close as possible to our reference please follow it for this time.
    
  • Click Create

Configuring The Project

• The first order of business is that DotImage does not support AnyCPU so we need to explicitly pick a Platform Target - either x86 or x64. Since Visual Studio 2022 is a 64 bit process, we will pick x64. If you're using VS2019 or older you would choose x86 simply because VS is 32 bit process and it's easier to use the "native bitness"
• In Solution Explorer, right-click on Net6AtalaConsole poject and select Properties
  
• On the Project Properties tab, expand the Build option under General and find Platform target
• Change it from AnyCPU to x64
  
• Click the Save all
• Next, we need to add a required dependency from Atalasoft: windows forms
  
  This is required because DotImage components are reliant upon this even if you're making a console app, microservice etc...
• In Solution Explorer, right-click on Net6AtalaConsole poject and select Edit Project File
  
• Change the TargetFramework from net6.0 to net6.0-windows
  

      <TargetFramework>net6.0</TargetFramework>
  
      to
  
      <TargetFramework>net6.0-windows</TargetFramework>

  
  Note: for .net8.0 it needs to be net8.0-windows7.0 and NO that is not "windows 7" it's for the windows SDK version 7 because Microsoft is nothing if not confusing when it comes to naming decisions
• Just below that add a new item:
  

  	<UseWindowsForms>true</UseWindowsForms>

• Your project file will now look something like this
  
  

  <Project Sdk="Microsoft.NET.Sdk">
  
    <PropertyGroup>
      <OutputType>Exe</OutputType>
      <TargetFramework>net6.0-windows</TargetFramework>
      <UseWindowsForms>true</UseWindowsForms>
      <ImplicitUsings>enable</ImplicitUsings>
      <Nullable>enable</Nullable>
      <PlatformTarget>x64</PlatformTarget>
    </PropertyGroup>
  
  </Project>
  

  
  
  
• Save and close this
• This completes all the base setup.. this approach needs to be done with just about any .NET 6 project regardles of whether it's console app or even a web app or microservice etc. the .net6-windows and UseWindowsForms are required by our components - it means you CAN NOT host our components within Linux continers. You must run this in windows / windows container.

Prerequisites (Project Assembly References)

Now, we can get on with adding references and coding

This paper as mentioned is written for the case of "we have installed the DotIamge SDK on the machine where we're developing" and will use default paths. Then we'll mention how to use NuGet packages.

• In Solution Explorer, right click on the Dependencies (underneath Net6AtalaConsole) and select Add Project Reference
  
• and click Add
• Back in Reference Manager, the correct dlls should be showing as checked
  
• click OK
• If you expand Dependencies -> Assemblies, you should now see Atalasoft.dotImage, Atalasoft.dotImage.Lib and Atalasoft.Shared
  

Sample Image File

For this demo we're goint to use a simple image file named "tiger.jpg". It's just a test image - you can substitute your own

• In solution explorer add a folder (right click the project and then Add -> New Folder to the NetAtalaConsole project and name it "images"
• drag/drop your image file from windows into it
• Now, right click on the image file in question and click properties
• In the Properties tab, go to the Copy to Oputput directory and change it to Copy Always
  

The Code

We're just going to make an AtalaIamge from the file and write some stuff to the console so we can see it's working

under static void Main(string[] args)
replace
Console.WriteLine("Hello, World!");
with:

Console.WriteLine("Creating AtalaImage");

AtalaImage img = new AtalaImage("images/Tiger.jpg");
Console.WriteLine("  Size: " + img.Size);
Console.WriteLine("  Size: " + img.PixelFormat);
img.Dispose();

Console.WriteLine("Hit ENTER to quit");
Console.ReadLine();

NOTE you will get an error from AtalaIamge unless you add a using Atalasoft.Imaging statement so the whole code would look like this:

When you build and run it you shoud see the output

EMBEDDING LICENSING

So, you've got a working app.

However, if you now try and take that app and bin directory and copy to another computer or run it within a windows container it will complain that it can't find a license file

To properly license the exe we need to embed the license.

The process is outlined in HOWTO:License a .NET 6 Application (embedding license in an exe)

For this, I've made a copy of the app and named it Net6AtalaConsole_license_embedding

Notice I uesd underscores and not spaces

THIS IS CRITICAL NOT TO USE SPACES

Spaces in project names break the licensing

So, to do this we need to use a NuGet package as there is no direct refencable DLL

• Go to Tools -> NuGet Package Manager -> Manage NuGet Packages For Solution
  
• Go to browse and search for AtalasoftLicenseCompiler
  and since we were doing x64 we want to install
  AtalasoftLicenseCompiler.x64
  
• Click Install
• This should have added a "ghosted" "Properties" folder to your solution
• Right click on that and Add -> new Item
  
• If this comes up with "FileName.cs" then you need to click "Show All Templates"
  
• Now, scroll down until you find Text File
• Select that and make the name "licenses.licx" make sure it's exactly this (licensing will fail if you name it anything else)
  
• and click Add
• In the licenses.licx file add the following line:
  

  Atalasoft.Imaging.AtalaImage, Atalasoft.dotImage
  

• click save

NOTE: in this case, all we are licensing is DotImage base SDK... if you have other assemblies you're licensing you may need to add other lines. Please see this KB for the full list of possible licenses.licx lines:

HOWTO: License an EXE for Deployment (.NET Framework)

Now, if all goes right then you will be able to REBUILD the solution.

The output window should show success and you should see something along these lines:
File Properties\Net6AtalaConsole_license_embedding.dll.licenses is created.

Any errors in finding license files will be shown there - review the log if you have issues

If you run into trouble and need support, please create a support case, then copy the full output window log into a text file and provide that with the case (we would like text and NOT screenshots please)

You can test if the license embedding was correct by following this KB article:
HOWTO:Verify That You Have Successfully Embedded Licensing in EXE

Sample Application

Net6AtalaConsole
Net6AtalaConsole_embedded_licensing