MARSHALLTOWN Software SDK

A Better Way for Integration Development

The MARSHALLTOWN Software SDK provides a framework for rapid development of applications which integrate with Microsoft Dynamics AX and nearly any other system. The framework prescribes a robust, flexible, and proven architecture for building decoupled services and responsive web applications. 

Our goal for customers

With the purchase and use of the MARSHALLTOWN Software SDK, customers will be completely self-sufficient and capable of designing and implementing web applications tailored for their direct business needs.

Pricing

$35,000 + time and materials for in-person training.

This includes the source code for all C# libraries and X++ code as well as ready-to-consume nuget packages.

Full documentation in book and PDF form with examples.

The license is a perpetual use license.

SDK Training

28 hours of training is included with the price of the SDK.

We will schedule a pre-training call with one of your developers to provide a link to an Azure Dev Ops project with the source code and documentation.  We like to have the SDK X++ code installed in your AX system before training.

We will send some spiral bound SDK documentation for your team to review.  These are an excellent resource that we use often internally at MARSHALLTOWN.

We will schedule a time for on-site training at your location with an experienced MARSHALLTOWN software engineer.  By the end of training your team will have built an application of your choice that should be production-ready.

Typical training:

Day 1

AM – SDK introduction
PM – Begin project

Day 2

AM – Project work
PM – Project work

Day 3

AM – Finish project
PM – Automated Build and Deploy

Day 4

Any remaining hours may be spent with any remaining project work, can be saved for a later date after the training, or to address any questions that arise.

Bonus topics depend on the capabilities of your development team but may include:  Semantic versioning of libraries, source control methodology (C#, X++, SQL), automated AX environment restore techniques, enhanced automated builds and deployments, etc…

Optional

Optionally we have some pre-build modules that you can bolt on to your system.

Introduction

Service Architecture

As developers, we struggle to develop and maintain a variety of applications which connect efficient user interfaces to back end data sources. The MARSHALLTOWN Software SDK provides the building blocks to implement patterns and architectures which have been designed to promote the following:

  • Rapid application development
  • Loose coupling between applications and data sources
  • Protocol & platform independence
  • Consistency among applications
  • RESTful design

 In general terms, the architecture prescribed by the SDK is fundamentally based on:

  • Strongly-typed Data Models
    • Objects which are effectively property bags with no logic
    • Represent the data passed between systems (domains)
    • Optimized for and implemented consistently in each domain
  • Common data envelope
    • Data models are passed between domains in a JSON MtResult envelope
    • Provides for transmission of results and errors from service calls
  • Common pattern for Service Interface/Implementation layers as applicable to each domain; for example, Dynamics AX 2009 service implementations follow a common pattern involving:
    • Static Service Interface classes
      • Provide outward facing interface for a service, mapping/routing calls to actual (concrete) Service Implementation classes
      • Translate (serialize/deserialize) data to/from X++ Data Models
    • Concrete Service Implementation classes
      • Implement the business logic for the Service Interface
    • Common pattern for Service Proxy/Contract/Facade layers enabling service consumption from C# applications, again leveraging base classes and objects:
      • Service Contract interfaces
        • Enable loose coupling between C# code and service implementations
      • Optional Service Facade classes wrap Service Contracts, providing (if needed):
        • Point of commonality for shared, non-implementation-specific logic
        • Additional layer of decoupling
      • Service Proxy classes
        • Implement the Service Contract
        • Invoke Service Interfaces across domains
        • Translate (serialize/deserialize) data to/from C# Data Models

Development of each layer is simplified by the SDK.

SDK Components

C# components are provided both as precompiled NuGet packages and as source code.  X++ components are provided via XPO files.

MtCommon

The MtCommon library (for C# and X++) provides common, critical SDK components which are useful regardless of the type of application being developed (desktop or web).

  • dll – C# class library / NuGet package
    • Primary contents:
      • C# data envelope implementation (MtResult<T>)
      • Objects critical to error handling mechanisms:
        • MtException
        • MtApiCallException/MtApiCallInfo (provides debug information about service API calls)
      • Interfaces and classes simplifying access to application configuration settings used by the SDK
    • MtCommon – X++ object library
      • Primary contents:
        • X++ data envelope implementation (MT_Result)
        • JSON serialization/deserialization classes (MT_JSON, MT_TextStream)
        • Class enabling serialization of complex Data Models (MT_TypeSpec)
        • Service Implementation base class & supporting objects (MT_Service_Base)

MtCommon.Ax

This C# library provides components which simplify the implementation of the Service Proxy layer for a Dynamics AX service implementation within any C# application (desktop or web).

  • Ax.dll – C# class library / NuGet package
    • Primary contents:
      • Service Proxy layer base class (AxBase), handling:
        • Example: Invocation of AX 2009 Service Interface layer via Business Connector
        • Data envelope validation
        • Data Model translation (serialization/deserialization)
      • Objects critical to error handling mechanisms:
        • MtAxApiCallInfo (implementation of MtApiCallInfo, provides debug information about Business Connector calls with AX 2009)
      • Interface/class simplifying access to Business Connector settings (IAxBusinessConnectorSettings/MtAxBusinessConnectorSettings)

MtCommon.Web

This C# library provides SDK components specifically useful for developing web applications implemented with ASP.NET MVC.  When consumed by a new web project as a NuGet package, the package installs several out-of-box templates for standard MVC project files which help to bootstrap the MARSHALLTOWN Software SDK – yielding a quick, ready starting point for development. 

  • Web.dll – C# class library / NuGet package
    • Primary contents:
      • Mt-Metro UI CSS (based on Metro UI CSS) enabling responsive, mobile-friendly UI design
      • Ready-made shared view layout (cshtml) and related:
        • MtNavigationContextModel
          • Base class for strongly typed, shared view model
        • MtController<TNavigationContextModel>
          • Controller base class wrapping shared view model
        • Navigation and debug menu-building classes
      • Mechanisms for:
        • Error handling
        • Developer debugging
        • Simple UI user prompts
        • Routing/navigation simplification
        • Dependency injection using config to loosely bind service libraries at run-time
        • Implementing MtResult-aware Web API services compatible with the prescribed service architecture
  •  

Example Projects

Three example web projects are provided which demonstrate the service architecture and key SDK features.  The MARSHALLTOWN Software SDK Bootstrapping Guide provides more detail about each example as well as everything necessary to get started with the projects.

  • Web (Simplified)

Companion to the Simplified Service Architecture diagram, demonstrating an abstract scenario involving a simple AX service and a web application

  • Web (Generalized)

Companion to the Generalized Service Architecture diagram, demonstrating an abstract scenario involving a simple AX service and web application

  • Web

Simple inventory transfer AX service and web application demonstrating several key concepts

Requirements

  • A good space for training with a quality projector(s) or large TV(s)
  • Developer quality laptops
  • Microsoft Visual Studio 2019 or later
  • Microsoft .NET Framework 4.7.2 or later
  • A quality text editor like Sublime Text or Notepad++
  • Linqpad 5 (A great tool for any C# developer)
  • Everything Search Tool (voidtools.com)
  • Chromium Edge, Google Chrome, or Firefox (Internet Explorer is not acceptable)
  • Microsoft Dynamics AX – AOS and .NET Business Connector or AIF
    • For development of applications with Dynamics AX integration
  • Microsoft IIS (Internet Information Services) Installed on Developer Machines
    • For development of web applications
  • Windows Server 2019 or later
    • For hosting IIS
  • On-Premise TFS or Azure Dev Ops Project for automated builds
  • Azure Dev Ops or Octopus Deploy for release and automated deployment

What about .NET Core?

The SDK version for .NET Core is coming. .NET Core has been moving so fast and changing so much we’ve decided to wait until .NET 6 to formalize our SDK standard and make it available. The principles all remain the same!