Verbindungszeichenfolgen im XRM-Tooling verwenden
Mit Dynamics 365 Customer Engagement (on-premises) ermöglicht das XRM-Tooling es Ihnen, eine Verbindung zu Ihrer Instanz herzustellen, indem Sie Verbindungszeichenfolgen verwenden. Dies ähnelt dem Konzept von Verbindungszeichenfolgen, das in SQL Server verwendet wird. Verbindungszeichenfolgen erhalten native Unterstützung in Konfigurationsdateien inklusive der Möglichkeit der Verschlüsselung der Konfigurationsabschnitte für maximale Sicherheit. Auf diese Weise können Sie Dynamics 365 Customer Engagement (on-premises)-Verbindungen zum Zeitpunkt des Bereitstellens konfigurieren und müssen in Ihrer Anwendung keinen Hardcode für die Verbindung zu Ihrer Instanz eingeben.
Notiz
Die Verbindungszeichenfolgedokumentation, die für Benutzer von Dataverse gilt, ist jetzt in der Power Apps Dokumentation verfügbar unter: Verbindungszeichenfolgen in XRM-Tooling zur Verbindung mit Dataverse verwenden
Erstellen einer Verbindungszeichenfolge
Sie geben diese Verbindungszeichenfolge in der Datei App.config oder web.config für das Projekt an, wie im folgenden Beispiel angezeigt.
<connectionStrings>
<add name="MyCRMServer" connectionString="AuthType=AD;Url=https://contoso:8080/Test;" />
</connectionStrings>
Wichtig
Wenn Sie vertrauliche Informationen zur Datei app.config oder web.config hinzufügen, z. B. ein Firmenkennwort, müssen Sie sicherstellen, dass geeignete Sicherheitsvorkehrungen zum Schutz dieser Informationen getroffen werden.
Nachdem Sie die Verbindungszeichenfolge erstellt haben, verwenden Sie diese, um ein CrmServiceClient-Objekt zu erstellen.
//Use the pre-configured connection string named "MyCRMServer"
CrmServiceClient crmSvc = new CrmServiceClient(ConfigurationManager.ConnectionStrings["MyCRMServer"].ConnectionString);
Notiz
Sie müssen die folgende using-Direktive in Ihrem Code verwenden, um auf den System.Configuration-Namespace verweisen, um auf die Verbindungszeichenfolge in Ihrem Code zuzugreifen: using System.Configuration;
Nachdem Sie ein CrmServiceClient Objekt erstellt haben, können Sie das Objekt werden, um Aktionen in Dynamics 365 Customer Engagement (on-premises) auszuführen. Weitere Informationen: XRM-Tooling zur Ausführung von Aktionen verwenden
Parameter für Verbindungszeichenfolgen
Die Verbindungszeichenfolge enthält eine Reihe von Name-Wert-Paaren, getrennt durch Semikolons. Die folgende Tabelle enthält unterstützte Parameter, die in beliebiger Reihenfolge eingegeben werden können.
| Parametername | Beschreibung |
|---|---|
ServiceUri, Service Uri, Url, oder Server |
Gibt die URL zu Dynamics 365 Server an. Die URL kann das http- oder https-Protokoll verwenden, und der Port ist optional. Standardmäßig wird der Port 80 für das http-Protokoll und 443 für das https-Protokoll verwendet. Die Server-URL ist normalerweise im Format für https://crm-server:port/organization-name oder für Dynamics 365 Customer Engagement (on-premises) gespeichert. Der Organisationsname muss angegeben werden. Sie können entweder den benutzerfreundlichen oder eindeutigen Namen der Organisation angeben, um eine Verbindung herzustellen. Beispiel: https://contoso/test, https://contoso:5555/test, https://contoso/test oder https://10.10.10.2/test. |
Domain |
Gibt die Domäne an, die Anmeldeinformationen von Benutzern überprüft. |
UserName, User Name, UserId, oder User Id |
Gibt die Benutzerkennung an, die den Anmeldeinformationen zugeordnet ist. |
Password |
Gibt das Kennwort für den Benutzernamen, das den Anmeldeinformationen zugeordnet ist. |
HomeRealmUri oder Home Realm Uri |
Gibt den Startbereichs-URL an. |
AuthenticationType oder AuthType |
Gibt den Authentifizierungstyp an, um die Verbindung zur Dynamics 365 Customer Engagement (on-premises) Instanz herzustellen. Gültige Werte sind: AD, IFD (AD FS) aktiviert, OAuth oder Office365.- AD und IFD sind nur für Dynamics 365 Customer Engagement (on-premises)-Instanzen zulässig.- OAuthist für Dynamics 365 Customer Engagement (on-premises)- und Dataverse-Instanzen zulässig. Für lokale ADFS ist 3.x+ und App\Client-ID-Registrierung mit ADFS für den OAuth-Typen erforderlich.- Office365 ist nur für Dataverse-Instanzen zulässig.– Die Verwendung eines Zertifikats oder eines geheimen Clientschlüssels zur Authentifizierung wird in Dataverse, aber nicht in Dynamics 365 Customer Engagement (on-premises) unterstützt. |
RequireNewInstance |
Definiert, ob die vorhandene Verbindung wieder verwendet wird, wenn Sie aufgerufen wird, solange die Verbindung noch aktiv ist. Standardwert ist false, der angibt, dass die bestehende Verbindung wiederverwendet wird. Wenn auf true festgelegt, wird das System gezwungen, eine eindeutige Verbindung herzustellen. |
ClientId, AppId or ApplicationId |
Gibt die ClientID an, die bei der Registrierung Ihrer Anwendung in Azure Active Directory oder Active Directory Federation Services (AD FS) zugewiesen wurde. |
RedirectUri oder ReplyUrl |
Gibt die Redirect-URI der Anwendung an, die Sie in Azure Active Directory oder Active Directory Federation Services (AD FS) registriert haben. Dieser Parameter gilt nur, wenn OAuth als Authentifizierungstyp angegeben ist. |
TokenCacheStorePath |
Gibt den vollständigen Pfad zum Speicherort an, an dem der Benutzertoken gespeichert werden soll. Der laufende Prozess muss über Zugriff auf den angegebenen Pfad verfügen. Es ist die Prozesszuständigkeit, diesen Pfad festzulegen und zu konfigurieren. Dieser Parameter gilt nur, wenn OAuth als Authentifizierungstyp angegeben ist. |
LoginPrompt |
Gibt an, ob der Benutzer zur Eingabe der Anmeldeinformationen aufgefordert wird, wenn die Anmeldeinformationen nicht angegeben wurden. Gültige Werte sind: - Always: Fordert den Benutzer immer auf, Anmeldeinformationen anzugeben.- Auto: Erlaubt es dem Benutzer, in der Schnittstelle des Steuerelements für die Anmeldung auszuwählen, ob die Eingabeaufforderung angezeigt werden soll oder nicht.- Never: Fordert den Benutzer nicht auf, Anmeldeinformationen anzugeben. Wenn für die Verwendung einer Verbindungsmethode keine Benutzeroberfläche bereitgestellt wird, müssen Sie diesen Wert verwenden.Dieser Parameter gilt nur, wenn OAuth als Authentifizierungstyp angegeben ist. |
SkipDiscovery |
Gibt an, ob Instanz-Erkennung aufgerufen wird, um die Verbindungs-URI für eine bestimmte Instanz zu bestimmen. Ab NuGet Version Microsoft.CrmSdk.XrmTooling.CoreAssembly 9.0.2.7, Standard = true. Standard der ältere Versionen werden false. Hinweis: Wenn Sie true festlegen, ist es wichtig, dass der Benutzer den entsprechenden und präzisen URI für die Zielinstanz zur Verfügung hat. |
Thumbprint oder CertificateThumbprint |
Definiert den Fingerabdruck des Zertifikats, der während einer S2S-Verbindung verwendet wird. Wenn festgelegt, ist die AppID erforderlich und die Benutzer-ID und das Kennwort werden ignoriert. |
StoreName oder CertificateStoreName |
Definiert den Speichernamen, unter dem das Zertifikat für den Fingerabdruck gefunden wird. Wenn festgelegt, ist der Fingerabdruck erforderlich. |
Anmerkung
Wenn Sie den OAuth-Authentifizierungstyp für Entwicklungs- und Erstausführungszwecke verwenden, haben wir die folgende AppId oder ClientId bereitgestellt und Weiterleitungs-URI für die Verwendung in OAuth-Flows weitergeleitet. Wir verwenden diese in allen unseren Codebeispielen.
Beispiel AppId oder ClientId = 51f81489-12ee-4a9e-aaae-a2591f45987d
Beispiel RedirectUri = app://58145B91-0C36-4500-8554-080854F2AC97
Für die Produktion sollten Sie ein AppId oder ein ClientId erstellen, die spezifisch sind für Ihren Mandanten im Azure Verwaltungsportal.
Beispiele für Verbindungszeichenfolgen
Die folgenden Beispiele veranschaulichen, wie Sie Verbindungszeichenfolgen für die Verbindung mit Dynamics 365 Customer Engagement (on-premises) und IFD-Bereitstellungen und Authentifizierungsszenarien verwenden können. Die Verbindungszeichenfolgen für Dataverse Instanzen ist jetzt in der Power Apps Dokumentation unter: Verbindungszeichenfolgen in XRM-Tooling zur Verbindung mit Dataverse verfügbar
Integrierte lokale Authentifizierung
<add name="MyCRMServer"
connectionString="AuthType=AD;
Url=https://contoso:8080/Test;" />
Benanntes Konto unter Verwendung der lokalen Authentifizierung
<add name="MyCRMServer"
connectionString="AuthType=AD;
Url=https://contoso:8080/Test;
Domain=CONTOSO;
Username=jsmith;
Password=passcode" />
OAuth unter Verwendung des benannten Kontos in Dynamics 365 Customer Engagement (on-premises) mit UX zur Abfrage der Authentifizierungsbestätigung
Erstellen einer neuen Verbindung mithilfe einer Benutzer-ID oder mit einem Kennwort über oAuth.
Notiz
OAuth ist der bevorzuge Authentifizierungstyp für die Verbindung mit Dynamics 365 Customer Engagement (on-premises), wenn ein interaktiver Flow verwendet wird. Dieser Authentifizierungstyp unterstützt die Funktion von Azure Active Directory Bedingter Zugriff und mehrstufige Authentifizierung.
<add name="MyCRMServer"
connectionString="
AuthType=OAuth;
Username=jsmith;
Password=passcode;
Url=https://contoso:8080/Test;
AppId=51f81489-12ee-4a9e-aaae-a2591f45987d;
RedirectUri=app://58145B91-0C36-4500-8554-080854F2AC97;
TokenCacheStorePath=c:\MyTokenCache;
LoginPrompt=Auto"/>
OAuth nutzt gerade angemeldete Benutzers mit mit Zurücksetzen von UX, um auf die Authentifizierung hinzuweisen
Erstellen einer neuen Verbindung mithilfe dem geraden angemeldeten Benutzer über oAuth.
Notiz
OAuth ist der bevorzuge Authentifizierungstyp für die Verbindung mit Dynamics 365 Customer Engagement (on-premises), wenn ein interaktiver Flow verwendet wird. Dieser Authentifizierungstyp unterstützt die Funktion von Azure Active Directory Bedingter Zugriff und mehrstufige Authentifizierung.
Um mehr über die Integrated Security Parameter zu erfahren, gehen sie zum Thema Hier.
<add name="MyCRMServer"
connectionString="
AuthType=OAuth;
Username=jsmith;
Integrated Security=true;
Url=https://contoso:8080/Test;
AppId=51f81489-12ee-4a9e-aaae-a2591f45987d;
RedirectUri=app://58145B91-0C36-4500-8554-080854F2AC97;
TokenCacheStorePath=c:\MyTokenCache;
LoginPrompt=Auto"/>
IFD unter Verwendung eines benannten Kontos mit Delegierung an einen Vorbereich
<add name="MyCRMServer"
connectionString="AuthType=IFD;Url=https://contoso:8080/Test;
HomeRealmUri=https://server-1.server.com/adfs/services/trust/mex/;
Domain=CONTOSO;
Username=jsmith;
Password=passcode" />
Bestimmung Ihres Verbindungsstatus
Um festzustellen, ob die Verbindungsanfrage erfolgreich war, prüfen Sie den Wert der Eigenschaft CrmServiceClient.IsReady. Wenn der Wert true ist, ist die Verbindung erfolgreich undSie können mit der Arbeit beginnen. Andernfalls überprüfen Sie die Werte der Eigenschaften CrmServiceClient.LastCrmError und CrmServiceClient.LastCrmException auf die Ursache für den Verbindungsfehler.
Siehe auch
Erstellen von Windows-Client-Anwendungen mithilfe der XRM-Tools
Benutzen Sie CrmServiceClient-Konstruktoren, um sich mit Dynamics 365 Customer Engagement (on-premises) und Dataverse zu verbinden
XRM-Tooling zur Ausführung von Aktionen verwenden
CrmServiceClient