As well as some minor improvements, Versions 2 & 3 of FakeXrmEasy include three very useful new features.

Automatic Plugin Step Registration
The first new feature is the addition of Automatic Plugin Step Registration. Previously, when using Pipeline Simulation, you had to explicitly register the Plugin Steps as part of the setup of your tests, like this:

Not only was this time-consuming, but it was also error-prone. Tests might end up failing becaue of invalid plugin registration, rather than because of genuine errors. With Automatic Plugin Step Registration, if you use a declarative method of registering your plugins steps with a tool like spkl, your plugin steps will automatically be registered in your tests. This is a great time-saver and will help you avoid making mistakes in registering plugin steps in your tests.
There's a sample solution showing how to get this working with spkl here and more documentation here.

Plugin Step Audit
The second new feature is called Plugin Step Audit. With this enabled (by using the UsePluginStepAudit pipeline option in the AddPipelineSimulation directive), FakeXrmEasy will keep a record of the Plugin steps which fire during your tests, and this can be used to verify that you have set your plugin registration up correctly, and that the pipeline is working as expected. This could be used, for example, to test that you have configured your filtering attributes correctly in your step registration. The advantage of using this feature is that you can test that your steps registration is configured correctly without having to set up test data in order to test it - if you only need to know that a plugin fires under certain circumstances, without needing to know what the result of the plugin firing is, then you can test this with plugin step auditing. I'll talk later about the principle that Unit Tests should only test one thing and this feature allows you to do exactly that.

Plugin Registration Validation
Additionally, the Automated Plugin Registration feature validates your plugin registration and prevents you from defining registrations which would not be valid when registering message processing steps against a real instance of CRM.
For example, if your plugin registration config contains two steps with the same GUID, you will get an error, or if you try and register a plugin using a configuration which you would not be able to do against a real Dynamics instance, such as registering a pre-image on a Create step.

Having explored the new features available in V2/3, I'd like to discuss the use of Pipeline Simulation in general, what its pros and cons are, and when I think you should use it.

The advantages of using Pipeline Simulation
I think there are three main advantages to using Pipeline Simulation when testing your Dynamics Code.

Allows for end-to-end testing of code
Plugin pipeline simulation allows you to perform full end-to-end testing of your transactions. So, if you have a plugin which creates or updates an entity, and this entity also has a plugin registered against it, you will be able to test the full end-to-end process. This is particularly useful when you have some code which is not called from the context of a plugin transaction, but, for example, an Azure Function. If your function creates a record and a plugin populates some attributes on that record which your Azure Function relies on, then pipeline simulation will allow you to test this. With pipeline simulation, the faked context behaves just as the real CRM instance would behave.

Troubleshoot the whole pipeline
Related to the above feature is the fact that with pipeline simulation its possible to troubleshoot and debug the entire transaction pipeline. Imagine for example that an Azure function which creates a record in CRM and then does something with that record, and that Azure function is not working as expected. With pipeline simulation, you can trouble shoot the entire function from start to finish and step into the plugin code even if it is called from the Azure Function. There is a good video demonstrating this here.

Testing plugin registration
This is another real bonus - if you use a declarative method such as spkl to register your plugins, you can test that your have registered your message processing steps correctly before you even deploy them to the database. You can check filtering attributes and images are defined correctly and, as mentioned above, the framework will even test whether your registration does anything 'illegal' like registering two steps with the same GUID.

Ease of use
Introducing newcomers to the practice of Unit Testing in general, and specifically when talking about the creation of fake plugin execution contexts, can be confusing if the developers are new to the concepts of Unit Testing and Fakes. Being able to demonstrate a Unit test which just consists of setting up some test data and then issuing a 'Create' message and testing the outcome is simpler than having to demonstrate the use of a fake Plugin Execution Context, registering input parameters, etc. Using Pipeline Simulation can be a good first step in the learning curve which comes with writing dataverse Unit Tests.

Why use anything else?
If using Pipeline Simulation in our Unit Tests is so good, should we always use it? Should we stop writing tests which invoke the plugin directly and simply call the CRUD or other messages which will cause the pipeline to fire? Why go through the complexity of writing Unit Tests which explicitly test our plugins when we could 'just' test our plugins by executing a service request and letting the plugin pipeline simulation execute the plugin(s) for us?

Well, the truth is, that when we use pipeline simulation, we are no longer truly Unit Testing our code - testing the entire execution pipeline is really a kind of integration testing, albeit with tests that use a fake execution context and with many significant advantages (speed, repeatability, etc) over integration testing with a real instance of CRM. Strictly speaking a Unit Test should only test one thing, and if our tests invoke a whole plugin pipeline, we can no longer say that we are just testing a single function.

Does this matter? Does the fact that we can no longer call these tests Unit Tests make any difference? Well, yes, in many cases it does. By simulating the entire plugin execution pipeline we are introducting fragility and dependencies in our tests. If a test fails, we can't be sure whether this is because the code under test is failing or because some other part of the pipeline is failing because it depends on certain data or certain conditions being true. Testing a pipeline plugin may well require more setup before each test and as the plugin pipeline grows in complexity so will the dependency on data which is not relevant to the test in question, but still required to allow the pipeline to run to completion without error. Tests which rely on the plugin pipeline execution are more likely to start failing some time after they have been written because changes to any of the individual plugins called within the plugin pipeline introduce further dependencies.

This is not to say that we shouldn't use pipeline simulation, just that we should think about the reasons why we are using it and should only use it when our tests require the entire pipeline to run, such as when testing calls from Azure Functions which require the plugin pipeline to execute. We can consider there to be three levels of plugin testing which can be carried out using FakeXrmEasy:

• Method
• Plugin
• Pipeline
  
  

Ideally, the code in your plugins should be broken into discrete methods for each function within the plugin. True Unit Testing will be done at this level - a method is called with certain parameters and a single outcome of that method call can be tested.

Sometimes we want to be able to test the execution of an entire plugin, not just the individual methods within it. We might want to test how the plugin reacts when called with different parameters, such as different messages, targets or images. Or what happens when a pluginn which contains multiple methods is called.

Finally, we may sometimes need to invoke the entire plugin pipeline. This should not so much be because we want to test the entire pipeline, although we may sometimes want to do this, but more because the code we are testing relies on the plugin pipeline executing because (for example) it expects a certain record to have been created or updated during the pipeline execution which is required later in the code being tested. It's also really useful to be able to test that your plugin step registration has been configured correctly.

As a developer, it's really up to you to make a judgement call as to which level of testing you will use and you will most likely find that you will use a mixture of all three methods to acheive a good level of code coverage and robustness in your tests.

I'd recommend watching the excellent videos explaining Pipeline Simulation on the FakeXrmEasy youtube channel.

In conclusion, I think that pipeline simulation, especially when used in conjunction with automatic plugin registration using a tool like spkl, is a really useful feature of FakeXrmEasy. I don't see it as a replacement for the other methods of testing plugin code, but an invaluable tool when you need to be able to test more than just the code in a specific plugin. It brings us ever closer to the ideal of being able to fully test our Dataverse code locally before we deploy it to a real Dynamics instance.

As the table has no SVG icon, adding the table to the Sitemap results in the table being rendered like this (in Chrome):

or this (in Firefox):

So, how do we add an icon to these tables so they display as we would want them to in the Sitemap? If we open our solution in the old customiser interface we can see that the 'Update Icons' button that exists for custom entities does not appear, and if we look in the PowerApps portal, again, there is no option to add a web resource as an icon as there is for custom entities.
The entity does not even show up in the list of tables in the XRM Toolbox 'Iconator' tool (https://www.xrmtoolbox.com/plugins/MscrmTools.Iconator), so we can't use that to give the table an icon.
Finally, if we look in the App SiteMap editor, the table has the option 'Use Default Image' displayed but this is greyed out with no option to change it.

But you can add an icon for the table to use in the sitemap, using the following very counter-intuitiuve approach:
In Advanced Settings, select the Settings -> Customizations option and then click 'Customize the System' to open the Default solution:

Now navigate down to Model Driven Apps and from here open the App whose Sitemap you want to fix:

This will open the App Designer just as if you had opened it from the Power Apps portal, but this time if you go to the Sitemap Editor via this route, the option to choose an icon has now become enabled and you can select from any of the out of the box or custom icons available in your environment.

Choosing an icon and saving the Sitemap results in the icon being displayed as you'd expect. I don't know if this behaviour is by design, as it doesn't really make sense that the only way to do this is to edit the Model-Driven App through the Default Solution, but it works!

On a final  note, the solution above works when you want to add an entity with no SVG icon to the Sitemap, but it does not help when one of these entities appears as a lookup on a form. Here's the OOB Unit Of Measure entity as it appears on one of the OOB forms - if you know how to get rid of that 'Jigsaw puzzle piece' icon, do let me know!

With many thanks to Mishel Achkov from Microsoft for pointing out this solution to me.

My first reaction when I came across this test was dismay as I thought that I would not be able to continue testing without first having to implement the unimplemented method, but in fact, this is far from the case. The library provides a number of ways to very easily to invoke these unimplemented methods without having to contribute to the FakeXrmEasy project.

Whilst I would encourage everyone to contribute to this or any other Open Source project, there is actually good reason why some of these requests are unimplemented - in fact, there is no need for all organisation requests to be implemented in the FakeXRMEasy library.

Clearly, the most obvious reason for a method not being implemented in FakeXrmEasy is that the XRM SDK is growing all of the time, and the FakeXrmEasy contributors may never have the time to implement the ever growing number of requests.

Another reason, however, is that not every method needs to be implemented as Microsoft themselves have implemented it, because this is not, or should not, be relevant to your testing. Take, as an example, the OrganisationRequest which converts a Word Template into a PDF document as discussed here. For the contributors to the FakeXrmEasy project to try and implement this request would be a collosal waste of time, and there is a very high chance that their implementation would be nothing like Microsoft's. But why would you need a faked implementation of this method to produce the same output as Microsoft's? Your tests should really not be interested in the contents of the PDF that gets produced - it's Microsoft's job to test that their implementation works correctly, and your unit tests should not really care about the actual contents of the PDF.

Be that as it may, if you have code which at some point calls this particular Organisation Request, you don't want your tests to fail with the "not yet supported..." error message, and I will show you a couple of ways in which you can very easily implement fakes of these methods so that you can continue testing what's important - ie, your own code.

AddExecutionMock
This is the easiest way to add a mocked execution of an Organisation request to your tests and acording to Jordi Montaña, "should be used when you just want to override something ocasionally. AddExecutionMock is the easiest since you can override one fake message easily inline with your unit test." As a simple example, let's look at faking a method which does nothing but return a simple Success or Failure response. An example of this is the CalculateRollupFieldRequest - If we have a plugin which calls this method, we most likely don't really care how Microsoft implements this in the background, we just want to be able to call it from our plugin and for the request not to fail. We can do this using the AddExecutionMock method.

To do this, we need to add a call to AddExecutionMock when we are initialising our test, after we have instantiated our faked context, so our initialisation might look like this:

We now need to add our own mocked implementation of the CalculateRollUpFieldRequest method. As the CalculateRollUpFieldRequest returns a CalculateRollupFieldResponse, our implementation just needs to return a CalculateRollupFieldResponse.

If our code needs to check the outcome of the request for some reason, then it can set the properties of the response like this:

That's all it takes to Mock this request. Your unit tests should now continue to work when they hit the call to CalculateRollUpFieldRequest. There is also a RemoveExecutionMock method which you can call if you want to remove this mocked execution, which might be useful if you wanted to write two different implementations (if, for example, you wanted to be able to test what happens when your response returns failure rather than success). This can just be called like this:

Another example - mocking the generation of a PDF from a Word Tempalate
Another example of how easily an OrganisationRequest can be mocked is the OrganisationRequest I mentioned earlier which converts a Word Template to a PDF. Our tests should not really care about the content of the PDF generated, but if called from our code, the method does need to return something, so how do we go about adding a faked implementation of this request?

As before we need to add a faked implementation to our faked context when we initialise our tests:

We then need to add a faked version of the request - the OrganisationRequest we are faking has a property called "PdfFile" and returns the PDF as a byte stream, but we really don't need to return a fully formed PDF, so we can just fake the request and its response like this:

As before, we have the option of calling the RemoveExecutionMock() method if we want to implement the method if a different way during this test execution.

AddFakeMessageExecutor
According to Jordi, "if you want to override a message that is meant to be more generic and re-used across tests, then the AddFakeMessageExecutor is meant to be used for that, since you can encapsulate the logic in a separate class and pass it your context in every test". The implementation of the FakeMessageExecutor is slightly more complex, but not significantly so. The most significant difference with this method is that it gets the test execution passed into it. This means that, as Jordi says, the implementation can be written into a seperate class which does not need to 'know' the context of the Unit Test, as the context will be passed in as a parameter when called.

Let's take as an example this time a slightly more complex OrganisationRequest, the CloseIncidentRequest. If we do not care the outcome of this request, we could just implement this as a method which returns an empty CloseIncidentResponse in the same way as our first example above. But if we want the request to act in the same way as a real CloseIncidentRequest would by creating an IncidentResolution entity in the database and changing the Status and Status reason of the Incident, we can do this as well, using the context.
As before we start by adding a call to the AddFakeMessageExecutor method when we initialise our test.

We then need to implement the faked version of the request by implementing an instance of the IFakeMessageExecutor interface:

That's all it takes to add a Fake implementation of the CloseIncidentRequest. As before, there is a RemoveFakeMessageExecutor method which can be used to remove this faked implementation if you need to use more than one faked implementation in your test class.

AddGenericFakeMessageExecutor
Finally, the FakeXrmEasy library contains a method AddGenericFakeMessageExecutor which "was added to be able to execute late bound custom actions and out of the box requests which didn't have an OrganizationRequest class generated in the SDK but could still be invoked by creating an OrganizationRequest manually. "

Jordi continues: "I think some devs wanted it to test calling some out of the box messages that were accessible in the API, but that really, shouldn't be called as it was supposed to be unsupported doing so.... :D  I kept it because it's still useful for users who still use late bound actions...."

I've never had to use this, but it works very similarly to the AddFakeMessageExecutor, and I'll make sure that I update this blog post if I do find myself using it. As with pretty much everything else in FakeXrmEasy, there are Unit Tests in the source code which demonstrate how to use this. Here's an example: https://github.com/jordimontana82/fake-xrm-easy/blob/f294b9af7319f8e23d4032a9290ec75a628f2435/FakeXrmEasy.Tests.Shared/FakeContextTests/TestGenericMessageExecutors.cs

I hope this blog has helped explain how easy it is to write faked implementations of Organisation Requests which have not been implemented in FakeXrmEasy. Happy Testing!

A common requirement for users of Dynamics 365 is to generate PDF documents based on Word Templates. A common solution to this is to use Power Automate to generate the PDF and there are plenty of examples online on how to do this, such as this. A disadvantage of this approach, however, is that the documents are created asynchronously and this means that users may have to wait an indeterminate amount of time, without feedback, before the Flow completes.
This is fine when the document is created as part of an automated process, such as overnight invoice generation, but not ideal when the requirement is to produce the document on demand.
Fortunately, since version 9.0.1905.2010 of Dynamics 365, an out-of-the-box method of generating PDF's from Word Templates has been available for the platform. Orginally announced for the Sales Hub, and only available for Account, Contact, Lead, Opportunity, Order, Quote, and Invoice tables, as of 2020 release wave 2 this has now been extended to all custom entities. (docs.microsoft.com/en-us/dynamics365/sales-enterprise/create-quote-pdf). At the moment, the ability to generate a PDF from an out-of-the-box form button is still a Sales Hub only feature, but there is, however, an OrganizationRequest (ExportPdfDocument) which can be used to generate a PDF from a Template.
The ExportPdfDocument request requires three parameters:

• the GUID of the Word template
• the GUID of the record the PDF should be generated for
• the ObjectTypeCode of the record the PDF should be generated for

Thus we can create a method such as the following which takes the GUID of the relevant record and either the name or the GUID of the Word Template, and either the name or the ObjectType code of the relevant entity (with a couple of helper methods to retrieve the Guid of the Document and the ObjectTypeCode if not known):

The function returns the PDF as a ByteArray. What we do with this depends on our requirements. One such requirement might be to save the document as an annotation against the record the PDF was generated againts. This is easily done:

The exportPdf method is also available as a Web API Action. More details here:
https://docs.microsoft.com/en-us/dynamics365/sales-enterprise/developer/exportpdf-api

 Updating your solutions with a meaningful description and version number with every significant change is clearly good practice. It allows us to compare which versions have been deployed to which environments, helps us to see when versions were developed and what has been changed with each release.
Additionally, it might be that you want to take advantage of the deployment option (available for example in Wael Hamze's Azure Devops Tasks) to only deploy the the CRM solution if the version number is different from that which exists in the target environment. (This might be, for example, because your check-in only contains new tests, or some other component which does not need a Dynamics solution deployment.

 So, updating Solution Version Numbers is can clearly be useful and good practice, but it's a little cumbersome to do this through the Dynamics front end - we have to log into Dynamics, navigate to the Solutions area, find the solution we've updated, open it, update the version number with whatever the appropriate version number is (and add a comment detailing the change we've made, of course)! Wouldn't it be great if we could simplify this process?
Well, with a little help from LINQPad we can make this a whole lot easier and add some standardisation to the way we version our solutions at the same time. A solution is just an entity in Dynamics like any other, so we can easily retrieve and update the details of a solution using the Dynamics SDK. Here's a method we can use to retrieve a Solution given its name:

Now that we have the details of the solution, we can use LINQPad's TextBox and Button controls to create a simple UI that allows the user to input a new description and save it, as you can see below.

Here is the full text of the LINQpad script:

The format of the version number is a simple Year.Month.Date.IncrementalNumber, but you can clearly amend this to suit your own Versioning strategy. I've uploaded a copy of the script to LINQPad's Instant Share here: share.linqpad.net/uvdbxx.linq

User accounts which are MFA protected will be met by a screen like this in which they must enter a code which will be generated by Microsoft and either sent to the user by email or SMS, or through the Microsoft Authenticator phone app.

Using the method described in this post it is possible to programatically generate the OTP (One TIme Password) needed to sign in and for your tests to use this to connect to the Power Platform as part of your tests. You can use the Otp.Net library to generate the OTP you need to log in.
The sample code in the EasyRepro solution already references this library, so in this article I will just show you how to generate the MFA 'secret key' which you will need to use in order to generate the OTP used in your tests.

You can obtain an MFA secret key for your account using these instructions - you will need Microsoft's Authenticator App to get this working:

1. Go to your Office365 'My account' page. This is available at: https://portal.office.com/account/ or by clicking on the 'cog' icon in Dynamics 365 and selecting 'Privacy and Cookies':

or by clicking 'My Account' from the top right menu in Outlook.com.

2. Click on 'Manage security & privacy'

3. Click on 'Create and manage app passwords'

4. On the page which opens, there are two tabs which don't look like tabs. Click on the first of these: 'Additional security verification'
5. Click on 'Set up Authenticator app'

6. Click on 'Configure app without notifications'

8. Make a note of the 'Secret Key' which is displayed

9. In the authenticator app on you phone, Click the '+' to add an account and select 'work or school account'
10. Scan the QR code displayed on the web page
11. If the App displays a six-digit code, click 'Next' on the web page
12. Click Verify Now on the web page
13. Enter the six-digit verification code from the app into the web page
14. Add your MFA Secret key from step 8 with the spaces removed to your app.config as shown below, in the same section that you add your username and password:
<add key="MfaSecretKey" value="MfaSecretKeyWithSpacesRemoved" />
If you follow the examples in the EasyRepro repository your tests will now automatically generate and enter the one time password whenever the login dialogue box appears.

The second article explained how to manage MFA protected accounts.
In this third article, I will explain how we can improve things by encapsulating all of this logic into a couple of useful methods which allow us to connect to Dynamics 365 by simply typing a single line of code.

Using ‘My Extensions’ to encapsulate this into a single ‘login’ command
Clearly, we don’t want to have to type all of the code from the previous articles into LINQPad every time we want to connect to Dynamics365. Using the MyExtensions class, we can very easily encapsulate all of the above logic into a single method, so that when you want to create a  connection to one of your Dynamics 365 instances, all you need to type is something like this:

The MyExtensions class allows us to create reusable methods and other reusable components. To access the file, you can find and double click on the file from the ‘My Queries’ pane, or by using the shortcut Shift+Ctrl+Y:

When you first open the MyExtensions file, you will see something like this:

Let’s start by defining an enum, listing the different environment we might want to connect to:

Now you can add a ‘ConnectToCrm’ method in MyExtensions which takes one of these ‘environments’ as a parameter, and use a switch statement to build your connection string and connect to Dynamics 365:

NB: You must compile your MyExtensions file by hitting f5 before the code becomes available in your other scripts.
Now all you need to do to connect to the environment of your choice in any LINQPad script is to select one of your preconfigured environments:

Connecting to multiple environments at the same time
One of the advantages in using this method of logging in, compared to a pre-configured LINQPad connector, is that it allows you to connect to more than one environment in a single script, to compare data or maybe to move data from one environment to another.

which will give a result like this:

Do you really want to log into production?
Another feature which you can add to your MyExtensions code is a warning when a user is about to log into production. This can be very useful in preventing someone from accidentally running a script against a production instance. We can easily do this by using LINQPad’s Util.ReadLine method to prompt the user to confirm if they want to connect to Production:

A prompt will appear at the bottom of the page, asking for confirmation when a Production instance is chosen:

Adding Impersonation to our MyExtensions code
In this article, I explained how impersonating users can be very useful in diagnosing problems, or testing what happens when code as different users with different security roles. Adding an Impersonate method to your MyExtensions method can make this very straightforward.

Sharing the love
Once you have created your methods in your MyExtensions file, you can share this with the rest of the team, using the method outlined in this article. If you all set your  ‘Plugins and Extensions’ folder to the same folder in your Source Control system, you can all connect to Dynamics in exactly the same way without having to share any passwords.

In this second article, I will explain how to proceed if your account is additionally protected by Multi-Factor Authentication (MFA). When using MFA to authenticate against Dynamics 365, you are prompted to authenticate with an additional token, such as a code sent via text message or an authenticator app. In order to avoid having to repeatedly authenticate this way you can use an Azure App Registration so that connections made from LINQPad are pre-authenticated. First of all you have to create an App Registration in Azure which will allow you to register your ‘App’ (in this case your connection from LINQPad with Azure Active Directory). Log into the Azure Portal and open the App Registrations blade. You will see a screen like this:

Give your app registration a name, and provide a ‘Redirect URI’. For our purposes, this does not need to be a real URI, but it must be in the format of a real URI.
Click Register and you’ll be taken to a page like this:

You will use the Application (client) ID as part of your connection string.
Make the following amendments to your connection string in your LINQPad script:

• Change AuthType from Office365 to OAuth;
• Add the following additional parameters:
• AppId: This should be the token you copied from the Azure Portal.
• RedirectUri: This should be the Redirect URI you entered when setting up the App Registration.
• LoginPrompt=Auto;
• TokenCacheStorePath: The path to a location on your computer where a token will be stored after the first successful login, such as C:\temp\LinqPadOauth\cache.txt This will be used as the location in which the authentication token is stored so that you do not need to enter your credentials every time you log in.
• Remove the Password parameter altogether.

Your connection string should now look something like this:
AuthType=OAuth;Url=https://yourInstance.crm11.dynamics.com/;AppId=123449g6-45e9-489b-8eab-h20d45ea60e9;RedirectUri=https://anyoldurl.doesntmatter.com;LoginPrompt=Auto;Username=your.username@yourO365domain.onmicrosoft.com;RequireNewInstance=True;TokenCacheStorePath=C:\temp\LinqPadOauth\cache.txt
Running our script again, we should now get prompted once to enter our password and MFA token, but after that our credentials will be cached and we will not be prompted to enter our password again.
However, you will see that our connection generates an awful lot of diagnostic output, which can make it difficult to see what’s going on….

Luckily, there is a way to suppress all of this diagnostic information. Add this line to your code, and you will get a nice clean output again:

In the next article in the series, I’ll show you how you can encapsulate all of this code into a method so that you can easily create a connection in LINQPad by just typing a single line of code.

Whilst there is a LINQPad driver available for Dynamics here, it has not been updated for a while and I’ve never been able to connect to Dynamics 365 using this driver.
Even if you do manage to get the driver to work, there will be times when you want to create a connection to Dynamics 365 manually – for example if you want to be able to connect to multiple instances in order to be able to compare two environments, or to copy data from one instance to another.
Creating a connection to D365 – the Basics
Let’s start with creating a basic connection to Dynamics 365, using a standard Microsoft Active Directory account.
Create a new LINQPad file of type C# Statement, and add references to System.Net.dll and Microsoft.CrmSdk.XrmTooling.CoreAssembly. (If you have the premium edition of LINQPad, you can download the latter using the integrated NuGet Manager, otherwise you’ll have to download it outside of LINQPad and browse to the file.)
Here’s the code you need to create an organisation service connection:

There are a couple of things to notice here.
Firstly, note the use of TLS 1.2. Microsoft discontinued the use of TLS 1.0 or 1.1 with the Dynamics 365 platform in 2018, so all connections must be made using TLS 1.2.
Secondly, notice the use of the ‘RequireNewInstance‘ option. By default, this is set to False, which in many circumstances is sensible as it allows for the caching of the connection, which makes for faster execution. However, the disadvantage of this is that, if you make a connection to one instance of Dynamics 365, and then immediately to another instance (let’s say you are copying data from one instance to another in a script), you way well find that the second connection is to the same instance which you first connected to, which can be very confusing, if not downright dangerous!
So, now we can make a connection, but there are some further improvements which we might want to make.
Confirmation that we are logged in
Strangely enough, if you use invalid credentials in this code, you will not receive any error. The connection will fail silently, which is not very helpful.
We can, however, trap any errors by inspecting the ‘LastCrmError’ property of the connection:

We can quickly validate that we are logged in to the expected instance by displaying the details of the instance URI as follows:

and we can display the username of the user we are logged in as by performing a WhoAmI request:

Can you keep a secret? Using LINQPad’s Password Manager
The next improvement to be made is to start using LINQPad’s password manager so that we don’t keep our passwords in our scripts. Replace the variable holding the password (Line 2 in the first snippet) with this:

The first time that you run the script, you will be prompted to enter your password:

Every time you run the script after that, LINQPad will retrieve the password from its secure password store, so you don’t need to enter it every time.
This will also enable the sharing of scripts with other users without having to share login credentials – the passwords are not saved with the script, so each user will be prompted to enter their own credentials. You can save any information in the password manager, so this can also be useful to hold usernames so these are also not saved in scripts. Passwords can be managed (created/updated/deleted) directly in LINQPad, from the File -> Password Manager menu item. In the next part in this series, I will show you how to manage connections for accounts which use Multi-Factor Authentication.

With older versions of the Toolkit, I was just getting stuck in a loop where I’d successfully authenticate using MFA, be shown a list of instances, select one and then just get taken straight back to the initial login page.
With the latest version of the tool (9.1.0.1), I was getting a different problem – it wasn’t even showing me a list of instances, just giving me this error message after entering my username and password: Error : You don’t have permission to access any of the organizations in the Microsoft Common Data Service region that you specified. If you’re not sure which region your organization resides in, choose “Don’t know” for the CDS region and try again. Otherwise check with your CDS administrator.
Capturing the web traffic in Fiddler didn’t help much – I could see that the call was returning this message: “Due to a configuration change made by your administrator, or because you moved to a new location, you must use multi-factor authentication to access” but this still didn’t help me getting the problem solved.
It wasn’t until I spoke to an engineer at Microsoft (Thanks, Trenton) that I was able to resolve the issue. When using MFA with the Plugin Registration Tool, it turns out that you must not enter your username and password in the login dialogue box!

If you leave these fields blank, when you click Login, you will get taken to the Microsoft Log-In screen as normal and this time your login will actually work!
If you think this counter-intuitive UI could be improved, you could up-vote this idea posted on the PowerApps forum.
NB If you want to get hold of the latest version of the Plugin Registration Tool, you will need to download it from the NuGet repository as described here.