Verwenden Sie Verbindungszeichenfolgen in XRM-Tools, um eine Verbindung mit Microsoft Dataverse herzustellen.
Mit Dataverse ermöglicht Ihnen XRM-Tooling die Verbindung mit Ihrer Dataverse-Umgebung über Verbindungszeichenfolgen. 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. Dies ermöglicht es Ihnen, Dataverse-Verbindungen zur Bereitstellungszeit zu konfigurieren und nicht hartcodiert in der Anwendung, um eine Verbindung zu Ihrer Dataverse-Umgebung herzustellen.
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="MyCDSServer" connectionString="AuthType=OAuth;Username=jsmith@contoso.onmicrosoft.com;Password=passcode;Url=https://contosotest.crm.dynamics.com;AppId=51f81489-12ee-4a9e-aaae-a2591f45987d;RedirectUri=app://58145B91-0C36-4500-8554-080854F2AC97;TokenCacheStorePath=c:\MyTokenCache;LoginPrompt=Auto"/>
</connectionStrings>
Wichtig
Wenn Sie vertrauliche Informationen zu app.config oder web.config file 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 connection string named "MyCDSServer"
//from the configuration file
CrmServiceClient svc = new CrmServiceClient(ConnectionString);
Alternativ können Sie auch die ServiceClient-Klasse verwenden.
ServiceClient svc = new ServiceClient(ConnectionString);
Hinweis
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 Service-Client-Objekt erstellt haben, können Sie das Objekt verwenden, um in Dataverse Aktionen für Apps auszuführen. Weitere Informationen: Verwenden von XRM-Tooling zur Ausführung von Aktionen in Dataverse
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 des Dataflows |
|---|---|
ServiceUri, Service Uri, Url oder Server |
Gibt die URL zur Dataverse-Umgebung 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 https://<organization-name>.crm.dynamics.comDer Organisationsname muss angegeben werden. |
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 eine Verbindung mit der Dataverse-Umgebung herzustellen. Gültige Werte sind: AD, IFD (AD FS-aktiviert), OAuth, Certificate, ClientSecret oder Office365. Zulässige Werte für Dataverse-Umgebungen sind jedoch nur OAuth, Certificate, ClientSecret und Office365.HINWEIS: Der Office365-Authentifizierungstyp ist veraltet und wir empfehlen die Verwendung von OAuth als bevorzugten Authentifizierungstyp. Weitere Informationen: Was sollte ich tun, um meinen Anwendungscode zu reparieren, falls er betroffen ist? |
RequireNewInstance |
Definiert, ob die vorhandene Verbindung wieder verwendet wird, wenn Sie aufgerufen wird, solange die Verbindung noch aktiv ist. Wenn auf true festgelegt, wird das System gezwungen, eine eindeutige Verbindung herzustellen. Wenn Sie dies auf false festlegen, kann die bestehende Verbindung wiederverwendet werden. |
ClientId, AppId oder ApplicationId |
Gibt die ClientID an, die bei der Registrierung Ihrer Anwendung in Microsoft Entra ID oder Active Directory Federation Services (AD FS) zugewiesen wurde. |
ClientSecret oder Secret |
Erforderlich, wenn der Auth-Typ auf ClientSecret festgelegt ist. Zeichenfolge für geheimen Clientschlüssel für die Authentifizierung. |
RedirectUri oder ReplyUrl |
Gibt die Umleitungs-URI der Anwendung an, die Sie in Microsoft Entra ID 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 immer den Benutzer auf, Anmeldeinformationen anzugeben.- Auto: Ermöglicht dem Benutzer, in der Anmeldungssteuerelement-Benutzeroberfläche auszuwählen, ob die Eingabeaufforderung angezeigt wird 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. |
StoreName oder CertificateStoreName |
Definiert den Speichernamen, unter dem das Zertifikat für den Fingerabdruck gefunden wird. Wenn festgelegt, ist der Fingerabdruck erforderlich. |
Thumbprint oder CertThumbprint |
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. |
Integrated Security |
Gibt an, dass aktuelle Windows-Anmeldeinformationen verwendet werden sollen, um zu versuchen, ein Token für die Instanzen zu erstellen. Ab NuGet-Version Microsoft.CrmSdk.XrmTooling.CoreAssembly Version 9.1.0.21 |
Hinweis
Wenn der AuthType\AuthenticationType OAuth verwendet wird
Für Entwicklungs- und Erstausführungszwecke haben wir die folgenden AppId oder das ClientId bereitgestellt und URI für die Verwendung in OAuth-Flowsn weitergeleitet.
Für die Produktion sollten Sie ein AppId oder ein ClientId erstellen, die spezifisch sind für Ihren Mandanten im Azure Verwaltungsportal.
Beispiel AppId oder ClientId = 51f81489-12ee-4a9e-aaae-a2591f45987d
Beispiel RedirectUri = app://58145B91-0C36-4500-8554-080854F2AC97
Beispiele für Verbindungszeichenfolgen
Die folgenden Beispiele veranschaulichen, wie Sie Verbindungszeichenfolgen für die Verbindung mit Online-Bereitstellungen und Authentifizierungsszenarien verwenden können. Die Beispiele für Verbindungszeichenfolgen für lokale und IFD-Deployment-Instanzen sind nun in der Dokumentation Dynamics 365 Customer Engagement (on-premises) unter: Verwenden Sie Verbindungszeichenfolgen in XRM-Tools, um eine Verbindung herzustellen.
Benanntes Konto mit Office365
Erstellen Sie eine neue Verbindung zu Dataverse mithilfe eines Benutzernamens oder Kennworts über Office365 her.
Hinweis
Diese AuthType ist veraltet und wir empfehlen, OAuth als bevorzugter Authentifizierungstyp zu verwenden. Weitere Informationen: Authentifizieren Sie mithilfe von Office365
<add name="MyCDSServer"
connectionString="
AuthType=Office365;
Username=jsmith@contoso.onmicrosoft.com;
Password=passcode;
Url=https://contoso.crm.dynamics.com"/>
OAuth unter Verwendung des benannten Kontos in Microsoft 365 mit UX zur Abfrage der Authentifizierungsbestätigung
Erstellen Sie eine neue Verbindung mit Dataverse mit Hilfe einer UserID oder eines Kennworts via OAuth.
Hinweis
OAuth ist der bevorzugte Authentifizierungstyp für die Verbindung zu Dataverse, wenn ein interaktiver Flow verwendet wird. Dieser Authentifizierungstyp bietet volle Unterstützung der Funktionen des bedingten Microsoft Entra ID-Zugriffs und der Multi-Faktor-Authentifizierung.
<add name="MyCDSServer"
connectionString="
AuthType=OAuth;
Username=jsmith@contoso.onmicrosoft.com;
Password=passcode;
Url=https://contosotest.crm.dynamics.com;
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 Sie eine neue Verbindung zu Dataverse unter Verwendung des aktuell angemeldeten Benutzers über OAuth.
Hinweis
OAuth ist der bevorzugte Authentifizierungstyp für die Verbindung zu Dataverse, wenn ein interaktiver Flow verwendet wird. Dieser Authentifizierungstyp bietet volle Unterstützung der Funktionen des bedingten Microsoft Entra ID-Zugriffs und der Multi-Faktor-Authentifizierung.
<add name="MyCDSServer"
connectionString="
AuthType=OAuth;
Username=jsmith@contoso.onmicrosoft.com;
Integrated Security=true;
Url=https://contosotest.crm.dynamics.com;
AppId=51f81489-12ee-4a9e-aaae-a2591f45987d;
RedirectUri=app://58145B91-0C36-4500-8554-080854F2AC97;
TokenCacheStorePath=c:\MyTokenCache\msal_cache.data;
LoginPrompt=Auto"/>
Zertifikatsbasierte Authentifizierung
Erstellen Sie eine neue Verbindung zu Dataverse mithilfe einer Anwendungs- oder Client-ID und eines Zertifikats.
<add name="MyCDSServer"
connectionString="
AuthType=Certificate;
url=https://contosotest.crm.dynamics.com;
thumbprint={CertThumbPrintId};
ClientId={AppId};"
/>
Auf der ClientId oder dem geheimen Clientschlüssel basierte Authentifizierung
Erstellen Sie eine neue Verbindung zu Dataverse mithilfe einer Anwendungs- oder Client-ID und eines geheimen Clientschlüssels.
<add name="MyCDSServer"
connectionString="
AuthType=ClientSecret;
url=https://contosotest.crm.dynamics.com;
ClientId={AppId};
ClientSecret={ClientSecret}"
/>
Bestimmung Ihres Verbindungsstatus
Um zu bestimmen, ob die Verbindungsaufforderung erfolgreich war, überprüfen Sie den Wert für CrmServiceClient.IsReady. -Eigenschaft verfügbar. Wenn der Wert true ist, ist die Verbindung erfolgreich undSie können mit der Arbeit beginnen. Andernfalls überprüfen Sie die Werte der CrmServiceClient.LastCrmError- und CrmServiceClient.LastCrmException- Eigenschaften, um die Ursache für den Verbindungsfehler festzustellen.
Siehe auch
Erstellen von Windows-Client-Anwendungen mithilfe der XRM-Tools
CrmServiceClient-Konstruktoren verwenden, um eine Verbindung mit Dataverse herzustellen
Verwenden von XRM-Tooling zur Ausführung von Aktionen in Dataverse
CrmServiceClient
Hinweis
Können Sie uns Ihre Präferenzen für die Dokumentationssprache mitteilen? Nehmen Sie an einer kurzen Umfrage teil. (Beachten Sie, dass diese Umfrage auf Englisch ist.)
Die Umfrage dauert etwa sieben Minuten. Es werden keine personenbezogenen Daten erhoben. (Datenschutzbestimmungen).
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Tickets als Feedbackmechanismus für Inhalte auslaufen lassen und es durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter: https://aka.ms/ContentUserFeedback.
Einreichen und Feedback anzeigen für