ServiceClient - Constructor useUniqueInstance, Clone, CallerId, WhoAmI

[fowl2]

What is the intended use of the useUniqueInstance constructor parameter?

I've been getting some strange permission errors that indicate that perhaps the CallerID property isn't being cleared between instances with this set to true. (It's also possible it's a bug in my code, but I think it's ok).

I'm trying to avoid the startup delay of the "whoami" call each time (is that really required?), but definitely need separate environments and users to be separate.

Some background: My use case is running as close to unmodified as possible plugin code in an Azure Function, so I've created an implementation of IOrganizationServiceFactory that creates a ServiceClient each call. The plugin code calls CreateOrganizationService quite a lot so performance is important.

[fowl2]

Under further investigation, even when useUniqueInstance is true it appears the CallerID property just doesn't work reliably.

I put a clearly incorrect value in immediately after construction and Execute() succeeded times before finally giving an error.

serviceClient.CallerId = new("deadbeef-dead-beef-dead-ffffffffffff") 

[MattB-msft]

So there are a few things going on here.

First lets talk about UseUniqueInstance
UseUniqueInstance is an optimization pattern -
When a client is created a copy of the client is stored in memory cache,
If UseUniqueInstance=false during construction, the in Memory client is used and no new connection is created, this is effectively a multi threaded use case for the client, which it handles though it will block on concurrent connection when using the Sync calls.
if UseUniqueInstance=true during construction, a new client is us created from scratch.
The default is set to true.

Generally, we recommend the use of .clone for creating distinct connections vs going though the whole new leg if your talking to the same instance. so in your case, keep a copy of the ServiceClient in memory and use .clone for each request vs creating a new connection ( this is actually pretty close to how the organizationservicefactory does this in Plugins BTW )

Caller ID is the ID of the System user in Dataverse, which I believe your aware of.
Caller ID is only effective post login, thus the client create flow uses the connecting user. This is different then how the OrganizationServiceFactory works for plugins as the underpinning engine is very different.

The WhoAmI call your seeing is done to validate the connection is alive and working, it's used because its an extremely lightweight call on the server ( no disk used as all ) and causes the server host to load its organization cache, allowing subsequent calls to be much faster.

[fowl2]

Caller ID is the ID of the System user in Dataverse, which I believe your aware of.
Caller ID is only effective post login, thus the client create flow uses the connecting user.

Are you saying I need to make a login() call off some kind before it will take effect? I'm used to the WebAPI where it's just a header added to each request.

I was expecting that if I create a new instance of ServiceClient, set the CallerID property something bogus then execute a request - eg. Retrieve, it should fail as that bogus user doesn't have permissions to the entity (as the bogus user doesn't have any permissions as they don't exist.

[fowl2]

The WhoAmI call your seeing is done to validate the connection is alive and working, it's used because its an extremely lightweight call on the server ( no disk used as all ) and causes the server host to load its organization cache, allowing subsequent calls to be much faster.

It still takes 100ms+ in network latency etc. that's not needed if

a. the server is already warm, from eg. other instances of my code.

b. the first request is always immediately following construction

Even if the server responds instantly the fixed overheads (TCP congestion windows etc) and the speed of light will hurt us.

[fowl2]

Generally, we recommend the use of .clone for creating distinct connections vs going though the whole new leg if your talking to the same instance. so in your case, keep a copy of the ServiceClient in memory and use .clone for each request vs creating a new connection ( this is actually pretty close to how the organizationservicefactory does this in Plugins BTW )

Is there any chance of an explicit connection pool concept being introduced? Otherwise each consumer will need to implement their own and pray they get the calculation of the key correct to not accidentally cross contaminate between users/environments. Getting the expiry/connection closure policy right is tough too.

Alternative, something closer to ADO.Net where instead of blocking, a new connection is created (up to a limit, which I guess could be influenced by the server's concurrency hint).

[fowl2]

Ps. Thanks so much for the detailed responses!

[MattB-msft]

Regarding Caller ID and the web API.
You can only send that after the call has been authenticated, in the case of the webAPI via Postman or some other client, your doing the JWT authentication flow and attaching it to the Authorize header when you talk to the WebAPI, coupled with the CallerID you achieve impersonation for that request.
In the Dataverse ServiceClient, assuming your not providing your own authentication handler, the client establishes the connection and does the first WhoAmI as the connecting user. At which point you have a ServiceClient you can set a Caller ID on.
See this article.. and note that there are 2 different properties..
CallerObjectId and MSCRMCallerId.
CallerObjectId == Client.CallerAADObjectId
MSCRMCallerId == Client.CallerId

if your passing AAD ObjectId to CallerId, the API will ignore it as it does not match a known user and it will use the connection user to process the request.
Also note that not all messages respect Impersonation.

Regarding WhoAmI,
There are many factors here... a given organization could be on 1- 30 nodes concurrently (depending on scaling), while any one node is warm, unless things are busy, it's unlikely all are. Once a connection is established, it will prefer the same node in the cluster unless there is a need for it to shift to another. The WhoAmI process is run only during initial connection and given the benefits of making sure the node's cache is loaded and ready for 'work' we decided to formalize that as the connection logic flow.
As I said above, if you wish to avoid it, you can create a single connection and then create clones of that connection for your process.

Regarding Connection pools and such.
We have no plans currently to provide such a utility. given the wide variety of client hosts the service client is used in, and the number of different types of use cases, we focused on optimizing the client itself vs trying to provide an implementation of a connection pool for one technology or another.

That said, if you think there will high enough volume to warrant a connection pool process, there are many things to consider and test for. Given your line of questioning, and that your asking about impersonation; I am making the assumption that your not using on behalf of authentication flows for your asp.net site.
One of the key things to consider is to decide if your volume on a given asp.net host is going to be high enough that port exhaustion is a concern.
If so, you should create a connection pool with a max concurrency manager to manage the number of clones that you would take off any given connection to keep it under the threshold for your host.

There are a number of other things to think though, but w/out understanding your site, and its purpose as well as expected volume's I cannot guide much beyond that.

As a general rule though, cloning seems work for most sites.

[fowl2]

Wow! A lot here, thanks again.

CallerId

In the Dataverse ServiceClient, assuming your not providing your own authentication handler, the client establishes the connection and does the first WhoAmI as the connecting user. At which point you have a ServiceClient you can set a Caller ID on.

I am using this constructor: public ServiceClient(Uri instanceUrl, Func<string, Task<string>> tokenProviderFunction, bool useUniqueInstance = true, ILogger logger = null) is the ServiceClient considered 'established' and the CallerID usable once the constructor returns?

CallerId vs CallerAADObjectId

I believe I managed to get this right, but wow that's confusing having the headers and properties being inconsistent like that.

Changing the property names may be illadvised, but perhaps even just the doc comment here could be improved?

        // Summary:
        //     Gets or Sets the current caller ID
        public Guid CallerId

eg.

        // Summary:
        //     The systemuser that should be impersonated. This corresponds to the MSCRMCallerId WebAPI header.
        //    Note that this property has no effect until the connection is establish. [reference to how to establish a connection]
        //    For an AAD user see CallerAADObjectId
        //    See also <link>Impersonation</link>
        public Guid CallerId

CallerId Ignoring Unknown Users

the API will ignore it as it does not match a known user and it will use the connection user to process the request.

So the "API" will ignore an invalid system user ID, but the handlers of individual messages might not - ie. an Update message will still fail because it will attempt to set the "Modified by" attribute. Does that sound right?

I'm also assuming that specifying an invalid AAD user ID using CallerAADObjectId will not be ignored?

Impersonation Support

Also note that not all messages respect Impersonation.

This is quite surprising. Impersonate another user doesn't mention this caveat at all. Is there any reference on what is and isn't supported? It's quite important to the security model of apps.

WhoAmI

I'm using Azure Functions consumption plan, which means that I can get autoscaled minute by minute. This makes cold startup quite a common scenario, so I'd still prefer a way of disabling the WhoAmI call. Calling the WebAPI directly doesn't incur this cost.

I can understand how warming up caches could save time overall if there was a delay between creating the ServiceClient and the first request. I'm not following however how it could save time when the first request is immediately after construction, due to doubling of network latency.

Your hint about Clone is well received however, thanks! :)

Clone

        // Summary:
        //     Clone, 'Clones" the current Dataverse ServiceClient with a new connection to
        //     Dataverse. Clone only works for connections creating using OAuth Protocol.
        //
        // Parameters:
        //   logger:
        //     Logging provider Microsoft.Extensions.Logging.ILogger
        //
        // Returns:
        //     returns an active ServiceClient or null
        public ServiceClient Clone(ILogger logger = null)

1. Does passing a tokenProviderFunction to the constructor count as a 'OAuth Protocol' here?
2. Under what circumstances would this return null?

And just to confirm, the CallerId property will take effect immediately on ServiceClient returned from this method?

[fowl2]

Connection pools

We have no plans currently to provide such a utility. given the wide variety of client hosts the service client is used in, and the number of different types of use cases, we focused on optimizing the client itself vs trying to provide an implementation of a connection pool for one technology or another.

Totally understand.

ServiceClient is quite analogous to HttpClient and SqlClient, neither of which are tied to any particular consuming technology with their connection pools. So I would still definitely encourage movement in this direction :)

One of the key things to consider is to decide if your volume on a given asp.net host is going to be high enough that port exhaustion is a concern.

Wouldn't/shouldn't port exhaustion be taken care of by the underlying HttpClient?

I note there isn't a public constructor overloads that accepts a HttpClient or HttpClientFactory.

[MattB-msft]

I am using this constructor: public ServiceClient(Uri instanceUrl, Func<string, Task> tokenProviderFunction, bool useUniqueInstance = true, ILogger logger = null) is the ServiceClient considered 'established' and the CallerID usable once the constructor returns?

It is once the connection is completed (The constructor returns)

I believe I managed to get this right, but wow that's confusing having the headers and properties being inconsistent like that.
Changing the property names may be illadvised, but perhaps even just the doc comment here could be improved?

The client properties predate the WebAPI headers :).. But, yes I agree we can add to the comments to correlate.

Regarding Clone,
The clone uses the authflow of the parent. The comment regarding oAuth is a hold over from CrmServiceClient. all Connections in DV ServiceClient ( accept AD ) are cloneable.

Wouldn't/shouldn't port exhaustion be taken care of by the underlying HttpClient?

No, that is still possible by extensive create and delete of clients.. Its harder to do these days but it is possible under high load.

I note there isn't a public constructor overloads that accepts a HttpClient or HttpClientFactory.

Correct, we are not exposing the wire protocol or provide access to it.. We use a number of different protocols, connection processes and in the future entirely different protocols . We hide this from you to insulate you from these changes as we make them.