Anything Dynamics
There are two ways to find out the version information. Either use LCS or look at individual files on the box (in case the VM is not hosted on LCS).
In the LCS case, browse to the environment in question and follow the “View detailed version information” link. The following information will be available:
The following article outlines the steps to carry out in order to be able to use, develop and debug a simple IPaymentDevice-derived peripheral that can be used by the Dynamics 365 for Retail and Operations HardwareStation.
The following steps should be carried out on a development box.
I used HW0002 profile. We need to use the PinPad device type and set some new parameters. Lets use “SAMPLEDEVICE2”. Notice that the originally shipped Microsoft code already uses “SAMPLEDEVICE”, so I deliberately choose a different string.
Edit as seen in the screenshot and save.
Next, pick the store you want to use for development and testing. I picked Houston. Go into the store settings and update the HardwareStation settings, make sure you match the same hardware profile from above.
Note, that I am running all components (HQ and store) on the same cloud-hosted box. There is a certificate for all sites already installed, so I decided to use the same url, in order to re-use the SSL certificate (pick it during the installation). I choose hardwarestation.cloud.dynamics.com. It could be anything, but you will have to get through some additional steps to get the SSL cert or self-signed cert to work properly.
Once these things are all setup and saved, we need to push these changes to the channel, via the 1090 (Registers) job. Run it and make sure the changes have been applied (via “Download sessions” form)
Go back to the same screen for the Houston store, and download the hardware station installer. Once downloaded, install it on the development box. You also need to add a hosts file entry for the development box:
127.0.0.1 retailhardwarestation.cloud.dynamics.com
and a host header of
retailhardwarestation.cloud.dynamics.com
for the newly installed website.
At the end of the installation, make sure the final ping works to the newly installed station succeeds (url is https://retailhardwarestation.cloud.dynamics.com/HardwareStation/ping).
Re-use the HardwareStation.Peripherals.Desktop project from the Retail Sdk but strip out everything we do not need. At the end, only leave the SampleManagerDevice.cs, make sure to rename it to “SAMPLEDEVICE2” in the class export attribute and remove any binary references to HardwareStation.Peripherals.*. We are doing that so we won’t need to drop all these other binaries. Its unfortunate that the simple Retail Sdk sample has that many dependencies. Here we are going for the simplest way to get started, so we remove all of these references.
Compile the code.
Drop the dll and pdb into the HardwareStation’s binary folder. For me, that was at “C:\Program Files (x86)\Microsoft Dynamics 365\70\Retail Hardware Station\Package\bin”.
Last but not least, add the assembly to the HWST’s web.config file at the //hardwarestation/composition node, at the top. I added this entry:
<add source=”assembly” value=”SampleExtensionLibrary” />
(I renamed it, but any assembly name will work for you here.)
We need POS (Modern POS or Cloud POS) and pair the hardware station. The quickest way would be to use Cloud POS as no installation is needed. Once you paired the station with POS (via the “Select HardwareStation” button) you should log off once.
A good way to verify that the HardwareStation is being used is to use F12 Developer tools or Fiddler. Whenever an item gets added to the cart, we should see certain calls to the HWST:
At this point, we are ready to debug. Attach to the w3wp.exe project for the HardwareStation (i.e use ProcessExplorer to find out the process ID) and set breakpoints in your SAMPLEDEVICE2 payment device (i.e. OpenAsync method).
In order to make sure that our officially built HardwareStation has everything we need, we need to carry out these steps on files that are under source control:
Now we are in a position to try, debug, evaluate the calls and can implement the “real” code. Happy coding.
There are a few wikis at https://docs.microsoft.com/en-us/dynamics365/unified-operations/dev-itpro/index?toc=dynamics365/unified-operations/fin-and-ops/toc.json which help with specific dev ALM and deployment topics. I found myself and from questions of others that it is difficult to pull all this information together into a single process. This write-up hopefully helps somebody that wants to update to follow the process without errors. It will certainly help me next time I need to take a hotfix since I can just follow a simple cheat sheet. So lets get started.
There are 3 different update types. 1) A platform update is fully backwards compatible with the application, its of binary nature, and it can simply be deployed. 2) A X++ application hotfix ships fixes in X++ source code that can be integrated into ones own code (code merged), sort of like a customization. And finally, 3) a binary hotfix is an application update for other tools, binaries, and Retail source code. The latter is cumulative, so you will always get the latest. For that reason, use a good naming convention for the packages you download (and upload to the Asset library) as this helps later when you need to bring multiple environments to the same hotfix level.
Recommended (best) practices:
See the picture below to see an overall flow of the process. Refer to it while reviewing the following sections.
Note, that there are 4 total different deployment packages that could be deployed (purple boxes). See the details below how to get them.
Note: For the following steps, the integration of the Retail Sdk’s build with the Dynamics 365 for Operations build is assumed. If you do not have this setup, follow Retail Sdk and Dynamics 365 build definition.
Platform updates are the easiest. There is no code merge required, not VSTS needed, you just move it to the Asset library and deploy it. See more information at FAQ monthly platform updates.
X++ hotfixes are not cumulative, so there may be some code merging needed, if you pick multiple. Visual Studio and the Dynamics Operations VS addin will help with that.
Ideally, you pick the hotfix you need and be done with it. However, I have found it to be better in the long run to take all hotfixes. It incurs slightly more testing up-front, but less testing when updating to the next major version. Additionally, other fixed issues you may just not have not encountered will get fixed before you see them.
I got burned by a failed hotfix application after my dev box became corrupted. I could not tell for sure which files had been touched… Since then, I do a simple robocopy-backup to be able to rollback if something happens.
I have had issues with the VS addin in the past, so I always use the command line version. Additionally, it is important to understand the –prepare statement. Use it! Otherwise, code merges you may need to do later will be hard.
Update:
Below is a batch script that I add to each Metadata folder (VSTS too). Just update the environment variables, and remove the commented lines one by one, first -prepare, then -install. See below for details. here is the contents of the script:
setlocal set HotfixPackageBundlePath=C:\Temp\Downloads\AllX++HotfixesTill06192018\HotfixPackageBundle.axscdppkg set PLD=k:\AosService\PackagesLocalDirectory set TFSUri=https://xxxx.visualstudio.com/defaultcollection rem bin\SCDPBundleInstall.exe -prepare -packagepath=%HotfixPackageBundlePath% -metadatastorepath=%PLD% -tfsworkspacepath=%PLD% -tfsprojecturi=%TFSUri% rem bin\SCDPBundleInstall.exe -install -packagepath=%HotfixPackageBundlePath% -metadatastorepath=%PLD% -tfsworkspacepath=%PLD% -tfsprojecturi=%TFSUri% endlocal
Save it with a name like UpdateAppHotfixes.cmd. Run it from an elevated cmd console, while the local directory is the PackagesLocalDirectory.
This step will apply the actual changes to the files that were prepared in the previous step.
Binary hotfixes are cumulative. You need to pick one of them, and you will get the latest. If Retail channel components are not customized, then there is no code merge needed.
Use the LCS environment’s Maintain menu to deploy this package.
In order to effectively do code merges, it is suggested to use 2 branches. For more details, check Retail Sdk Overview (at the end of the wiki page).
Ideally, the Retail Sdk branch would be hosted in the same VSTS project, in parallel to the Trunk folder.
In order to update it:
Before checking in these changes, lets make sure that all builds fine. Open a Visual Studio MSBuild developer command window, and type “msbuild” at the root of the Retail Sdk customization branch. Once all builds fine, submit the changes with a meaningful changeset name.
Inspect the submitted changes in the VSTS code branch. In the example below, I see 2 checkins for the X++ hotfixes, one other code change, one to update the Retail Sdk mirror branch and one to code merge the Retail Sdk customization branch.
Find the packages in VSTS and upload them to LCS.
Deploy the packages from the LCS asset library (in the image below the 3rd and 4th). The RetailDeployablePackage is only needed in case of Retail channel customizations.
Once the deployment succeeded, you should see the tile count go down.
Follow the wiki about how to deploy the store components (Modern POS, Modern POS Offline, Hardware station, Retail Store Scale Unit)
Note: Implemented with Dynamics 365 version 7.2.* (but likely working fine with lower or higher versions). Sample code can be downloaded at the end of this blog.
A little-known feature is the ability to log into POS with a barcode scanner or MSR. All the low-level plumbing is already implemented in POS to accept the data and to call the right RetailServer activity. Also, CRT handlers exist that carry out the mapping from the scanned/swiped data to the credential Id, which is then ultimately used to look up a user. This handler is being called as part of the authentication pipeline of the CRT.
A manager must first assign a worker’s credential. For that add the operation called “Extended log on” an appropriate button layout and sync the download job that pushes the data for the registers (by default 1090). When that button is clicked, the following screen can be used to assign credential ids (insert/update):
Use the scanner or MSR when the application indicates it. Once saved, you are all set to try the login. For that, just scan/swipe on the logon dialog and the credential id is being looked up (read):
If the credential was found, the correct user will be logged in without any further prompt.
If you want to use this functionality, you will very likely want to adjust the code that maps the scanned/swiped data to a credential id. The default implementation takes the first 5 characters and throws the rest away. What if the information in the scanned/swiped data is the same for the first 5 characters and only differs further down the string? We will need to implement our own CRT handler(s) so we can replace the mapping functions. The following example uses MSR data simulated by the Peripheral Simulator for Retail.
Note: The crt.STAFFCREDENTIALSVIEW view shows what information is stored for any staff member. The good thing is we do not need to touch any of that code, we just need to adjust the 3 CRT request handlers that need the mapping from scanned/swiped data to the credential id.
namespace MyCompany.Commerce.Runtime.MyExtendedAuthService
{
using Microsoft.Dynamics.Commerce.Runtime;
using Microsoft.Dynamics.Commerce.Runtime.Handlers;
using Microsoft.Dynamics.Commerce.Runtime.Messages;
using Microsoft.Dynamics.Commerce.Runtime.Services.Messages;
using System;
using System.Collections.Generic;
using System.Globalization;
public class UniqueSecretExtendedAuthenticationService : INamedRequestHandler
{
public IEnumerable SupportedRequestTypes
{
get
{
return new[]
{
typeof(GetUserEnrollmentDetailsServiceRequest),
typeof(GetUserAuthenticationCredentialIdServiceRequest),
typeof(ConfirmUserAuthenticationServiceRequest)
};
}
}
public string HandlerName
{
get
{
return "auth://example.auth.contoso.com/msr";
}
}
public Response Execute(Request request)
{
if (request == null)
{
throw new ArgumentNullException("request");
}
Response response;
Type requestType = request.GetType();
if (requestType == typeof(GetUserEnrollmentDetailsServiceRequest))
{
response = this.GetUserEnrollmentDetails((GetUserEnrollmentDetailsServiceRequest)request);
}
else if (requestType == typeof(GetUserAuthenticationCredentialIdServiceRequest))
{
response = this.GetUserAuthenticationCredentialId((GetUserAuthenticationCredentialIdServiceRequest)request);
}
else if (requestType == typeof(ConfirmUserAuthenticationServiceRequest))
{
response = this.ConfirmUserAuthentication((ConfirmUserAuthenticationServiceRequest)request);
}
else
{
throw new NotSupportedException(string.Format(CultureInfo.InvariantCulture, "Request '{0}' is not supported.", request));
}
return response;
}
private GetUserAuthenticationCredentialIdServiceResponse GetUserAuthenticationCredentialId(GetUserAuthenticationCredentialIdServiceRequest request)
{
return this.GetUserAuthenticationCredentialId(request.Credential, request.RequestContext);
}
private GetUserAuthenticationCredentialIdServiceResponse GetUserAuthenticationCredentialId(string credential, RequestContext requestContext)
{
// TODO: this is the place where you can customize the mapping between what was scanned/swiped and what the credential id is in the StaffCredentialsview
string credentialId = credential;
return new GetUserAuthenticationCredentialIdServiceResponse(credentialId);
}
private GetUserEnrollmentDetailsServiceResponse GetUserEnrollmentDetails(GetUserEnrollmentDetailsServiceRequest request)
{
string credentialId = this.GetUserAuthenticationCredentialId(request.Credential, request.RequestContext).CredentialId;
return new GetUserEnrollmentDetailsServiceResponse(credentialId, string.Empty);
}
private Response ConfirmUserAuthentication(ConfirmUserAuthenticationServiceRequest request)
{
return new NullResponse();
}
}
}
Note: The changes in Customization.settings and commerceruntime.exe.config need to be made in the RetailSdk under VSTS, so these changes will be used by the build and package generation.
A fully working zipped up project can be found below. Just add the project to the SampleExtensions\CommerceRuntime folder and compile.
Extensions.MyExtendedAuthService
Below are some code samples for reading and writing data in Channel database. This is just for Channel database. This does not necessary mean that the data needs to go to D365 HQ. It may, either via CDX pull job or via Real-time service call. This information is only for simple reads and writes in Channel db.
Prerequisites:
Dynamics 365 for Operations (1611)
KB3214687
KB3214679
First, create the SQL table in ax schema and a view in crt schema:
CREATE TABLE [ax].[MY_EXTENSION](
[DATAAREAID] [nvarchar](4) NOT NULL,
[RECID] [bigint] NOT NULL,
[COL1] [int] NOT NULL,
[COL2] [nvarchar](100) NOT NULL,
[COL3] [bit] NOT NULL,
[ACCOUNTNUM] [nvarchar](20) NOT NULL)
. . .
END
GO
CREATE VIEW [crt].[MY_EXTENSIONVIEW] AS
(
SELECT ACCOUNTNUM, DATAAREAID, COL1, COL2, COL3 FROM [ax].[MY_EXTENSION]
)
GO
GRANT SELECT ON [crt].[MY_EXTENSIONVIEW] TO [UsersRole];
GO
The shown sample adds 3 columns to be stored from 3 extension properties.
Grant the right permissions to table and view. This is the list of supported SQL roles:
| DataSyncUsersRole | Used by CDX process account |
| PublishersRole | Used by publishing process account (eCommerce) |
| ReportUsersRole | Used by reporting user account |
| UsersRole | Used by runtime user (RetailServer) |
Next, create a sproc for updating:
CREATE PROCEDURE [crt].[MY_UPDATEEXTENSIONPROPERTIES]
@TVP_EXTENSIONPROPERTIESTABLETYPE [crt].EXTENSIONPROPERTIESTABLETYPE READONLY
AS
BEGIN
DECLARE @nvc_DataAreaId NVARCHAR(4);
DECLARE @recId bigint;
DECLARE @accountNum [nvarchar](20);
DECLARE @Col1Value int = 0;
DECLARE @Col2Value nvarchar(100) = '';
DECLARE @Col3Value bit = 0;
SELECT DISTINCT TOP 1 @recId = tp.PARENTRECID, @nvc_DataAreaId = ct.DATAAREAID, @accountNum = ct.ACCOUNTNUM
FROM @TVP_EXTENSIONPROPERTIESTABLETYPE tp
JOIN [ax].CUSTTABLE ct on ct.RECID = tp.PARENTRECID
WHERE tp.PARENTRECID <> 0
SELECT @Col1Value = COALESCE(tp.PROPERTYVALUE, 0)
FROM @TVP_EXTENSIONPROPERTIESTABLETYPE tp
where tp.PARENTRECID <> 0 and tp.PROPERTYNAME = 'COL1'
SELECT @Col2Value = COALESCE(tp.PROPERTYVALUE, '')
FROM @TVP_EXTENSIONPROPERTIESTABLETYPE tp
where tp.PARENTRECID <> 0 and tp.PROPERTYNAME = 'COL2'
SELECT @Col3Value = CAST(CASE WHEN tp.PROPERTYVALUE = 'True' THEN 1 ELSE 0 END AS BIT)
FROM @TVP_EXTENSIONPROPERTIESTABLETYPE tp
where tp.PARENTRECID <> 0 and tp.PROPERTYNAME = 'COL3'
MERGE INTO [ax].[MY_CUSTOMEREXTENSION] dest
USING (SELECT @accountNum as ACCOUNTNUM) as source on dest.ACCOUNTNUM = source.ACCOUNTNUM
WHEN matched then
update set dest.COL1 = @Col1Value, dest.COL2 = @Col2Value, dest.COL3 = @Col3Value
when not matched then
INSERT (RECID, ACCOUNTNUM, DATAAREAID, COL1, COL2, COL3)
VALUES (@recId, @accountNum, @nvc_DataAreaId, @Col1Value, @Col2Value, @Col3Value);
END
GO
GRANT EXECUTE ON [crt].[MY_UPDATECUSTOMEREXTENSIONPROPERTIES] TO [UsersRole];
GO
Note the MERGE INTO statement. This allows to either create or update a record.
For reading in the CRT, here especially for extension properties, use SQLPagedQuery, SQLServerDatabaseContext and ExtensionsEntity:
var query = new SqlPagedQuery(QueryResultSettings.SingleRecord)
{
Select = new ColumnSet(new string[] { "COL1", "COL2", "COL3" }),
From = "MY_EXTENSIONVIEW",
Where = "ACCOUNTNUM = @accountNum AND DATAAREAID = @dataAreaId",
};
query.Parameters["@accountNum"] = customer.AccountNumber;
query.Parameters["@dataAreaId"] = request.RequestContext.GetChannelConfiguration().InventLocationDataAreaId;
using (var databaseContext = new SqlServerDatabaseContext(request))
{
ExtensionsEntity extensions = databaseContext.ReadEntity(query).FirstOrDefault();
if (extensions != null)
{
var col1 = extensions.GetProperty("COL1");
if (col1 != null)
{
customer.SetProperty("COL1", col1);
}
else
{
customer.SetProperty("COL1", 0);
}
. . .
}
else
{
customer.SetProperty("COL1", 0);
}
}
In order to write the data to the db, use this code to call the sproc shown above:
using (var databaseContext = new SqlServerDatabaseContext(r))
using (var transactionScope = new TransactionScope())
{
if (!r.Customer.ExtensionProperties.IsNullOrEmpty())
{
ParameterSet parameters = new ParameterSet();
parameters["@TVP_EXTENSIONPROPERTIESTABLETYPE"] = new ExtensionPropertiesTableType(r.Customer.RecordId, r.Customer.ExtensionProperties).DataTable;
databaseContext.ExecuteStoredProcedureNonQuery("MY_UPDATEEXTENSIONPROPERTIES", parameters);
}
transactionScope.Complete();
}
In the case of you want to write other data to the database (no extension properties to entities), build the SqlParameters one by one and match in your sproc. For reading, it may be easier to just treat it as extension properties, then convert to whatever you want. Or you could create your own entity and query for that.
This video demonstrates how to store application settings securely and manage them in AX. These settings are needed for AX business logic and CommerceRuntime business logic. The data is fetched via a RetailTransactionServiceEx call. The CommerceRuntime service takes care of calling the RTS and caching for a configurable period. Video also shows how to test this by exposing it via RetailServer and using the RetailServer TestClient.