Setup an Assembly Project on Visual Studio 2019

Visual Studio has come with the built-in Macro Assembler and providing many debugging capabilities (Register & Memory View, Breakpoints and Step over). However there is no explicit assembly project template to choose from. So, this article will describe the required steps to setting up the assembly project on Visual Studio 2019.

I had compiled the knowledge from many sources and do the trial and error by myself.

1. Installing Visual Studio 2019

Visual Studio 2019 could be downloaded from the site: https://visualstudio.microsoft.com/vs/
The Community 2019 edition is free of charge.

When prompting to select an installed language, I choose C++. I’m not sure whether selecting other languages would work or not for assembly project.

2. Creating a C++ project as a base

Create a C++ empty project.

Named the project: “MASM”. So that, in the later step, we will save this project as a project template for further use. Set the save location to any preferred folder (I have precreated the folder C:\VSProj). Select “Place solution and project in the same directory” to prevent two nested folders with the same name.

The Visual Studio will create the folder with the same project name automatically.

3. Setup the Build Customization as Assembly Language

Right click at the project name > Build Dependencies > Build Customizations…

Select the “masm”, then OK.

Right click at the project name > properties > Linker > System > SubSystem : Windows
This will prevent the assembly program to show the console window ( the black text-mode window). But if you want the console window you can leave it at the default: Console mode.

I prefer the Windows mode because it has look-and-feel of native windows app. For debugging, just use breakpoint and watch windows to look at register and memory values at real-time. However, if we want to test the text mode input/output, we should use the console mode.

4. Creating a Test Assembly File

Right click at the project name > Add > New Item…

Name the file: “Main.asm” . The selected item type is not important. Any type can be selected. But the important is to name it with the “.asm” file extension.

Write a test program. You can copy the code from below. I adapted the code from the wonderful book : Assembly Language for x86 Processors by Kip Irvine. I highly recommend this book for anyone start learning the Assembly language.

.386
.model flat, stdcall
.stack 4096

ExitProcess PROTO, dwExitCode:DWORD

.data
myList DWORD 2, 3, 5, 8

.code
main PROC
  mov eax, 7
  add eax, 8
  INVOKE ExitProcess, eax
main ENDP

END main        ;specify the program's entry point

Press the green, play button: (run with) Local Windows Debugger.
The program will sum 7 with 8 and return the result 15 as shown in the debug output window.

5. (Optional) Setup Listing File

The listing file is useful for examining what the assembler has generated. To setup the listing file generation, right click the project name > Properties > Microsoft Macro Assembler > Listing File > Assembled Code Listing File : $(IntDir)$(ProjectName).lst

Note: The page “Microsoft Macro Assembler” will appear only when there are some assembly files in the project.

Build (and/or run) the project again. You will see the listing file generated at the project’s debug folder.

Drag the listing file into Visual Studio to view it. The listing file content will be like this:

5. (Optional) Setup for Release Mode Build

This section could be skip because it is quite complex. Do it when you need to use the release mode for release build. Or you could come to this section later when in need.

In Visual Studio, there is a separate release mode build configuration. The release mode configuration could be set differently from the debug mode configuration. For example, the release mode may have more optimizations and less debugging features.

If the release mode is needed, we should do the same as the step 3 and 5. Additionally, we need to customize the safe exception handler configurations.

5.1 Setup Subsystem (Windows or Console) and Listing File Generation

Go to the project properties > change the configuration mode to : Release.

Choosing your prefer subsystem (Windows or Console).

Setting up the listing file generation.

Changing the active configuration to Release.

Try building and running the program using the green play button. You will see the error message: “fatal error: LNK1281: Unable to generate SAFESEH image.”.
The next step 5.2 will solve this error.

5.2 Fully Enable or Disable the Safe Exception Handlers

In the release build mode, the default option of the linker is that every images (object files) should have safe exception handlers. However, the default option of the assembler (compiler) is not to use safe exception handlers. These conflicts cause the above error. Now, we have two choices to fix the error.

Way 1: Enable the safe exception handlers in the assembler (compiler).

Way 2: Or we could entirely disable the use of safe exception handler at the linker.
Linker > Advance > Image has Safe Exception Handlers : No

Choose one way but not both!

I preferred way 1 because it looks safer to have safe exception handlers. But, in fact, I am not 100% sure because I don’t have much knowledge about safe exception handlers.

After that we should be able to build and run the program in the release mode without any error.

Caution on switching between Debug and Release : When changing the active configuration in the toolbar and then open the project property pages, the property pages may not be conformed to the current active configuration. This could cause confusion when changing some project settings appear to not affect the current build. If this occur, please ensure the matching of active configuration and the property pages.

6. Save as a Project Template

After these long steps, we might not want to do them every time to create a new Assembly project. Fortunately, Visual Studio can save the project as a project template.

First, edit the Main.asm to contain only template code:

.386
.model flat, stdcall
.stack 4096

ExitProcess PROTO, dwExitCode:DWORD

.data

.code
main PROC

  INVOKE ExitProcess, 0
main ENDP

END main        ;specify the program's entry point

Try running it to make sure that the program works correctly.
If you still use release mode (from step 5), switch back to the debug mode.

Click: Project > Export Template …

Choose our “MASM” project from the drop down list.

Describe the template description.

Finished!

After that when you create a new project, you could select MASM as a project template.

Appendix

Debugging

Debugging is straightforward in Visual Studio. To set a breakpoint, just clicking the grey area in front of the line of the source code. When running, the program will pause before the execution of the breakpoint line.

To look at registers, select Debug > Windows > Registers

To look at variables, select Debug > Windows > Watch. Then type the variable name.
Or select Debug > Windows > Memory > Memory 1. Then type “&varname” at the address box.

An example of pausing at the breakpoint of the Visual Studio Debugger for Assembly Language

22 thoughts on “Setup an Assembly Project on Visual Studio 2019

  1. Hi,
    Great tutorial, just one thing. I’m unable to get an output console, only get a code saying ‘The program ‘[17252] TEST.exe’ has exited with code 0 (0x0).’
    Any suggestions?

    Like

  2. Works great!
    I had a problem trying to use 64 bit registers (rax) , and could only use 32 bit registers.
    Any idea how to change the project to support 64 bit registers?

    Like

    1. 1. At the tool bar > change the drop down list from “x86” to “x64”
      2. Set: configuration > linker > advance > entrypoint : “main”
      3. Try this 64 bit assembly code:

      ExitProcess PROTO
      .code

      main PROC

      sub rsp, 28h
      mov rcx, 1234

      call ExitProcess
      main ENDP

      END ; for 64 bit, need to specify the program’s entry point
      ; at configuration > linker > advance > entrypoint : “main”

      Like

    1. Thank you! I’m not sure how to convert from 8086 to 32 bit.

      Do you also want to change the underlying OS from DOS to Windows?
      1. I think that assembly commands for 8086 could be directly used on 32-bit. (Backward compatibility from Intel)
      2. For interrupt handling, some interrupt command may need to be replaced by Win32 API call.

      However, I don’t have direct experience on the conversion.

      Like

  3. I followed the exact same steps as explained here, but the assembler fails with exit code 1:

    Error MSB3721 The command “ml.exe /c /nologo /Zi /Fo”Debug\Main.obj” /Fl”Debug\MASM.lst” /W3 /errorReport:prompt /TaMain.asm” exited with code 1.

    If I then copy the exact command line in the Developer command prompt, it works fine. Then I copy the link command line and the build completes succesfully:

    C>ml.exe /c /nologo /Zi /Fo”Debug\Main.obj” /Fl”Debug\MASM.lst” /W3 /errorReport:prompt /TaMain
    .asm
    Assembling: Main.asm

    C>link /OUT:”C:\Users\XXXXXXXX\Documents\Visual Studio 2019\Projects\MASM\Debug\MASM.exe” /MANIFE
    ST /NXCOMPAT /PDB:”C:\Users\XXXXXXXX\Documents\Visual Studio 2019\Projects\MASM\Debug\MASM.pdb” /
    DYNAMICBASE “kernel32.lib” “user32.lib” “gdi32.lib” “winspool.lib” “comdlg32.lib” “advapi32.lib”
    “shell32.lib” “ole32.lib” “oleaut32.lib” “uuid.lib” “odbc32.lib” “odbccp32.lib” /DEBUG /MACHINE
    :X86 /INCREMENTAL /SUBSYSTEM:WINDOWS /MANIFESTUAC:”level=’asInvoker’ uiAccess=’false'” /Manifest
    File:”Debug\MASM.exe.intermediate.manifest” /LTCGOUT:”Debug\MASM.iobj” /ERRORREPORT:PROMPT /NOLO
    GO /TLBID:1 debug\main.obj

    C>dir /b Debug
    Main.obj
    MASM.Build.CppClean.log
    MASM.exe
    MASM.exe.intermediate.manifest
    MASM.ilk
    MASM.log
    MASM.lst
    MASM.pdb
    MASM.tlog
    MASM.vcxproj.FileListAbsolute.txt

    If I then start the Visual Studio debugger (F11) I receive the message:

    “Source information is missing from the debug information for this module”

    and I cannot use symbolic debugging.

    Like

  4. I spent 2 days, but now I know what is going on. The project is fine. No problem there. It assembles, links and runs correctly outside of Visual Studio. The problem here is Visual Studio. It says that ML.EXE returns errorlevel 1, but that is not true. ML.EXE returns 0. In fact, Visual Studio never creates a process for ML.EXE and can therefore not know what the errorlevel is. What happens is that Visual Studio creates a batch file (.cmd) in the user’s temp folder and executes that batch file from there. If that batch file fails, then Visual Studio assumes that ML.EXE generated the error. Not necessarily true also, since LINK.EXE could have failed instead of ML.EXE.

    Now, why does that batch file fail on my computer but not on yours? For obvious security reasons, I use on my computer a group policy that prohibits code execution from the user’s temp folder (and in fact, any writeable folder). As a result the Visual Studio build process fails, of course.

    I believe that it is not a good security practise what Visual Studio is doing. Granted, some writeable folder is needed for the build with permission to execute. But to use the user’s temp folder is too obvious. I normally grant an exception for the project folder until the project is finished or not needed anymore.

    What the good solution is here, I do not know yet. I do not know if the temporary file location in Visual Studio can be changed. If yes, the project folder should be used. Any idea if that is possible?

    Like

    1. Wow, very informative. Thank you for sharing this.
      I have no experience changing the visual studio temp folder, though. Please feel free to share your progress. Very interesting case.

      Like

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s