Xrm.Utility (clientseitige Referenz)

 

Veröffentlicht: Januar 2017

Gilt für: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Das Xrm.Utility-Objekt stellt eine Sammlung nützlicher Informationen bereit, die nicht direkt mit der aktuellen Seite zusammenhängen.

Diese Funktionen in jeder Anwendungsseite verfügbar, die Skripting unterstützt. Sie können sie in Formularskripten oder in Menübandbefehlen verwenden. Für HTML-Webressourcen sind sie verfügbar, wenn Sie sie in die ClientGlobalContext.js.aspx-Seite einschließen. Weitere Informationen finden Sie unter GetGlobalContext function und ClientGlobalContext.js.aspx (clientseitige Referenz).

Funktionen

• Dialoge
  Verwenden Sie alertDialog und confirmDialog, um den Beutzern Nachrichten anzuzeigen und Code basierend auf ihrer Antwort auszuführen. Diese Funktionen müssen mit mobilen Dynamics 365-Clients (Smartphones und Tablets) anstelle der window.alert- und window.confirm-Methoden verwendet werden.

• Native Gerätefunktionen (mobile Dynamics 365-Clients)
  Verwenden Sie getBarcodeValue und getCurrentPosition, um die nativen Gerätefunktionen mobiler Geräte zu verwenden, um den Barcodewert abzurufen, oder die aktuelle Position des Geräts zu erhalten.

• isActivityType
  Ermitteln Sie, ob eine Entität eine Aktivitätsentität ist.

• openEntityForm
  Öffnet ein Entitätsformular.

• openQuickCreate
  Verwenden Sie diese Funktion für Microsoft Dynamics CRM Online 2015-Update 1 oder höher, um ein neues Schnellerfassungsformular zu öffnen. Sie können diese Funktion verwenden zum Festlegen von Standardwerten mithilfe von Attributzuordnungen oder für bestimmte Attribute. Wenn der Benutzer den Datensatz speichert, können Sie einen Verweis auf den erstellten Datensatz erfassen.

• openWebResource
  Öffnet eine HTML-Webressource.

Dialoge

Zwei Dialogtypen stehen zur Verfügung: alertDialog und confirmDialog. Diese sind für die Verwendung mit Skripts enthalten, die mit mobilen Dynamics 365-Clients (Smartphones und Tablets) funktionieren. Mobile Dynamics 365-Clients lassen die Verwendung von JavaScript-Funktionen wie window.alert und window.confirm, die den Codefluss blockieren, nicht zu. Verwenden Sie diesen Methoden, wenn Sie eine Nachricht für Benutzer anzeigen müssen. der entscheidende Unterschied ist, dass diese Methoden Code nicht blockieren, bis sie ein Benutzer sie schließt. Sie enthalten einen Rückruffunktionsparameter, um anzuzeigen, welcher Code abhängig von der Antwort des Benutzers ausgeführt werden soll.

Hinweis

In mobilen Dynamics 365-Clients (Smartphones und Tablets) wird jede Verwendung der window.alert -Methode außer Kraft gesetzt, um Xrm.Utility.alertDialog ohne Rückruf zu verwenden. Hierdurch wird die Nachricht angezeigt, aber die Ausführung von Code nicht blockiert, wie bei window.alert. Diese Zuordnung von window.alert zu Xrm.Utility.alertDialog in mobilen Dynamics 365-Clients ist veraltetet und wird in der nächsten Hauptversion entfernt werden. Sie sollten Code, über den Sie jetzt verfügen, zur Verwendung von Xrm.Utility.alertDialog statt window.alert migrieren.

alertDialog

Zeigt ein Dialogfeld an, das eine anwendungsdefinierte Meldung enthält.

Xrm.Utility.alertDialog(message,onCloseCallback)

• Parameter

  Name	Typ	Erforderlich	Beschreibung
  Meldung	Zeichenfolge	Ja	Der Text der Meldung, die im Dialogfeld angezeigt wird.
  onCloseCallback	Funktion	Nein	Eine Funktion, die ausgeführt wird, wenn auf die OK-Schaltfläche geklickt wird.

• Anmerkungen
  Diese Methode ist nur für Aktualisierte Entitäten verfügbar.

confirmDialog

Zeigt ein Bestätigungsdialogfeld an, das eine optionale Nachricht und die Schaltflächen OK und Abbrechen enthält.

Xrm.Utility.confirmDialog(message,yesCloseCallback,noCloseCallback)

• Parameter

  Name	Typ	Erforderlich	Beschreibung
  Meldung	Zeichenfolge	Ja	Der Text der Meldung, die im Dialogfeld angezeigt wird
  yesCloseCallback	Funktion	Nein	Eine Funktion, die ausgeführt wird, wenn auf die OK-Schaltfläche geklickt wird.
  noCloseCallback	Funktion	Nein	Eine Funktion, die ausgeführt wird, wenn auf die Abbrechen-Schaltfläche geklickt wird.

• Anmerkungen
  Diese Methode ist nur für Aktualisierte Entitäten verfügbar.

Native Gerätefunktionen (mobile Dynamics 365-Clients)

Nutzen Sie diese Methoden für Dynamics 365 für Smartphones- und Dynamics 365 für Tablets-Clients, um die Benutzerfreundlichkeit für mobile Nutzer im Vertrieb, im Außendienst und in anderen Bereichen zu verbessern.

Hinweis

Diese Methoden wurden mit Update für Dynamics 365 (online und lokal), Dezember 2016 eingeführt.

getBarcodeValue

Gibt die Barcodeinformationen, wie eine Produktzahl zurück, gescannt mithilfe der Gerätekamera.

Xrm.Utility.getBarcodeValue().then(successCallback, errorCallback)

• Parameter

  Name	Typ	Erforderlich	Beschreibung
  successCallback	Funktion	Ja	Ein Funktion, die bei der Rückgabe des Barcodewerts aufgerufen wird.
  errorCallback	Funktion	Ja	Eine Funktion zum Aufrufen, wenn der Vorgang fehlschlug. Ein Fehlerobjekt mit der message-Eigenschaft wird übergeben, das die Fehlerdetails beschreibt.

• Anmerkungen
  Damit die getBarcodeValue-Methode funktioniert, müssen die mobilen Dynamics 365-Clients Zugriff auf die Gerätenkamera haben (standardmäßig aktiviert).

• Beispiel
  Im folgenden Beispielcode wird gezeigt, wie Sie diese Methode verwenden.

  Xrm.Utility.getBarcodeValue().then(
      function (result) {
          Xrm.Utility.alertDialog("Barcode value: " + result);
      },
      function (error) {
          Xrm.Utility.alertDialog(error.message);
      })
  

getCurrentPosition

Gibt den aktuellen Standort mithilfe der Gerätegeolokalisierungsfunktion zurück.

Xrm.Utility.getCurrentPosition().then(successCallback, errorCallback)

• Parameter

  Name	Typ	Erforderlich	Beschreibung
  successCallback	Funktion	Ja	Ein Funktion, die bei der Rückgabe der aktuellen Geostandortinformationen aufgerufen wird. Ein Geolokalisierungsobjekt mit folgenden Attributen wird an die Funktion übergeben. coords: Enthält einen Satz geografischer Koordinaten mit entsprechender Genauigkeit sowie einen Satz anderer optionaler Attribute wie die Höhe und Geschwindigkeit. timestamp: Stellt die Uhrzeit dar, zu der das Objekt erhalten wurde und ist ein DOMTimeStamp.
  errorCallback	Funktion	Ja	Eine Funktion zum Aufrufen, wenn der Vorgang fehlschlug. Es wird ein Objekt mit den folgenden Eigenschaften übergeben: code: Zahl. Der Fehlercode. message: Zeichenfolge. Lokalisierte Meldung, welche die Fehlerdetails beschreibt. Wenn der die Lokalisierungseinstellung des Benutzers nicht auf dem Mobilgerät aktiviert ist, zeigt die Fehlermeldung dies an. Falls Sie eine frühere Version des mobilen Dynamics 365-Clients verwenden, oder wenn die Geolokalisierungsfunktion nicht auf mobilen Geräten verfügbar ist, wird null an den Fehler-Callback übergeben.

• Anmerkungen
  Damit die getCurrentPosition-Methode funktioniert, muss Geolokalisierungsfunktion auf dem Gerät aktivier sein und der mobilen Dynamics 365-Client muss die Berechtigungen besitzen, auf den Gerätenspeicherort zuzugreifen (standardmäßig nicht aktiviert).

• Beispiel
  Im folgenden Beispielcode wird gezeigt, wie Sie diese Methode verwenden.

  Xrm.Utility.getCurrentPosition().then
      (function (location) {
          Xrm.Utility.alertDialog("Latitude: " + location.coords.latitude +
             ", Longitude: " + location.coords.longitude);
      },
      function (error) {
          Xrm.Utility.alertDialog(error.message);
      })
  

isActivityType

Ermitteln Sie, ob eine Entität eine Aktivitätsentität ist.

Xrm.Utility.isActivityType(entityName)

• Parameter

  Name	Typ	Erforderlich	Beschreibung
  entityName	Zeichenfolge	Ja	Der logische Name einer Entität.

• Rückgabewert

  Typ	Beschreibung
  Boolean	True, wenn die Entität eine Aktivitätsentität ist, sonst false.

openEntityForm

Öffnet ein Entitätsformular für einen neuen oder vorhandenen Entitätsdatensatz mithilfe der als Parameter festgelegten Optionen.

Xrm.Utility.openEntityForm(name,id,parameters,windowOptions)

• Parameter

  Name	Typ	Erforderlich	Beschreibung
  Name	Zeichenfolge	Ja	Der logische Name der Entität.
  id	Zeichenfolge	Nein	Die Zeichenfolgendarstellung eines eindeutigen Bezeichners oder des zu öffnenden Datensatzes im Formular. Falls nicht festgelegt, wird ein Formular geöffnet, um einen neuen Datensatz zu erstellen.
  Parameter	Objekt	Nein	Ein Wörterbuchobjekt, das dem Formular zusätzliche Parameter übergibt. Ungültige Parameter führen zu einem Fehler. Gültige zusätzliche Abfragezeichenfolgenparameter sind: Formular-ID: Um den ID-Wert des Hauptformulars festzulegen, das verwendet werden muss, wenn mehr als ein Formular verfügbar ist. Der Parameter ist formid. Standard Feld-IDs: Um Standardwerte für ein neues Formular festzulegen. Weitere Informationen finden Sie unter Festlegen von Feldwerten mithilfe von Parametern, die an ein Formular übergeben werden. Die navbar- und cmdbar-Parameter, die in Abfragezeichenfolgen-Parameter für die main.aspx-Seite beschrieben sind. Benutzerdefinierte Abfragezeichenfolgenparameter: Ein Formular kann konfiguriert werden, um benutzerdefinierte Abfragezeichenfolgenparameter zu akzepieren. Weitere Informationen finden Sie unter Ein Formular konfigurieren, um benutzerdefinierte Abfragezeichenfolgenparameter zu akzeptieren..
  windowOptions	Objekt	Nein	Verwenden Sie bei Microsoft Dynamics CRM Online 2015-Update 1 oder höher diesen optionalen Parameter in der Webanwendung, um zu steuern, wie das Formular geöffnet wird. Ein Formular kann in einem neuen Fenster geöffnet werden, indem Sie ein Wörterbuchobjekt übergeben, dessen Boolesche openInNewWindow-Eigenschaft auf true festgelegt ist. Dieser Parameter wird in mobilen Dynamics 365-Clients (Smartphones und Tablets) ignoriert.

• Anmerkungen
  Mit dieser Funktion können Sie sicherstellen, dass Benutzer nicht aufgefordert werden, sich unter bestimmten Umständen erneut anzumelden.

• Beispiele
  Öffnen Sie einen neuen Firmendatensatz mithilfe des Standardformulars

  Xrm.Utility.openEntityForm("account");
  

  Öffnen Sie einen bestehenden Firmendatensatz mithilfe des Standardformulars

  Xrm.Utility.openEntityForm("account","A85C0252-DF8B-E111-997C-00155D8A8410");
  

  Öffnen eines neuen Firmendatensatzes mit einem bestimmten Formular und Einstellung von Standardwerten

  var parameters = {};
  parameters["formid"] = "b053a39a-041a-4356-acef-ddf00182762b";
  parameters["name"] = "Test";
  parameters["telephone1"] = "(425) 555-1234";
  Xrm.Utility.openEntityForm("account", null, parameters);
  

  Öffnen Sie einen neuen Firmendatensatz mithilfe des Standardformulars in einem neuen Fenster

  var windowOptions = {
   openInNewWindow: true
  };
  Xrm.Utility.openEntityForm("account",null,null,windowOptions);
  

openQuickCreate

Verwenden Sie diese Funktion für Microsoft Dynamics CRM Online 2015-Update 1 oder höher, um ein neues Schnellerfassungsformular zu öffnen. Sie können diese Funktion verwenden zum Festlegen von Standardwerten mithilfe von Attributzuordnungen oder für bestimmte Attribute. Wenn der Benutzer den Datensatz speichert, können Sie einen Verweis auf den erstellten Datensatz erfassen.

Xrm.Utility.openQuickCreate(entityLogicalName,createFromEntity,parameters).then(successCallback, errorCallback);

• Parameter

  Name	Typ	Erforderlich	Beschreibung
  entityLogicalName	Zeichenfolge	Ja	Der logische Name der zu erstellenden Entität
  createFromEntity	Suche	Nein	Gibt einen Datensatz an, der Standardwerte basierend auf zugeordneten Attributwerten bereitstellt. Ein Such-Objekt bietet folgende String-Eigenschaften: entityType: der logische Name der Entität. id: Eine Zeichenfolgendarstellung eines GUID-Werts für den Datensatz. name: der primäre Attributwert des Datensatzes.
  Parameter	Objekt	Nein	Ein Wörterbuchobjekt, das dem Formular zusätzliche Abfragezeichenfolgeparameter übergibt. Ungültige Abfragezeichenfolgenparameter führen zu einem Fehler Gültige zusätzliche Abfragezeichenfolgenparameter sind: Standard Feld-IDs: Um Standardwerte für ein neues Formular festzulegen. Weitere Informationen finden Sie unter Festlegen von Feldwerten mithilfe von Parametern, die an ein Formular übergeben werden. Benutzerdefinierte Abfragezeichenfolgenparameter: Ein Formular kann konfiguriert werden, um benutzerdefinierte Abfragezeichenfolgenparameter zu akzepieren. Weitere Informationen finden Sie unter Ein Formular konfigurieren, um benutzerdefinierte Abfragezeichenfolgenparameter zu akzeptieren..
  successCallback	Funktion	Nein	Die Funktion, die aufgerufen wird, wenn ein Datensatz erstellt wird. Dieser Funktion wird ein Objekt als Parameter übergeben. Dieses Objekt enthält eine savedEntityReference-Eigenschaft mit den folgenden Eigenschaften, um den erstellten Datensatz zu ermitteln: entityType: der logische Name der Entität. id: Eine Zeichenfolgendarstellung eines GUID-Werts für den Datensatz. name: der primäre Attributwert des erstellten Datensatzes.
  errorCallback	Funktion	Nein	Eine Funktion zum Aufrufen, wenn der Vorgang fehlschlug. Es wird ein Objekt mit den folgenden Eigenschaften übergeben: errorCode: Number. Der Fehlercode. message: String. Eine loklisierte Fehlermeldung.

• Anmerkungen
  Diese Funktion ist nur für Microsoft Dynamics CRM Online 2015-Update 1 oder höher verfügbar.

  Es gibt ein Limit von zehn geschachtelten Schnellerfassungsformularen in der Webanwendung. Ist dieser Grenzwert überschritten, öffnet diese Funktion das vollständige Entitätsformular anstelle des Schnellerfassungsformulars.

• Beispiel
  Wenn dieser Code in einem Firmenentitätsformular ausgeführt wird, erstellt ein Schnellerfassungsformular eine neue untergeordnete Firma mit einem standardmäßigen Namen, der so festlegt ist, dass er den Namen der übergeordneten Firma enthält.

  var thisAccount = {
      entityType: "account",
      id: Xrm.Page.data.entity.getId()
  };
  var callback = function (obj) {
      console.log("Created new " + obj.savedEntityReference.entityType + " named '" + obj.savedEntityReference.name + "' with id:" + obj.savedEntityReference.id);
  }
  var setName = { name: "Child account of " + Xrm.Page.getAttribute("name").getValue() };
  Xrm.Utility.openQuickCreate("account", thisAccount, setName).then(callback, function (error) {
      console.log(error.message);
  });
  

  Wenn dieser Code mit Browserentwicklertools (F12-Tools) ausgeführt wird, stellt das Folgende die Ausgabe an die Konsole dar, wenn die Ausführung im Rahmen einer Firma namens "A. Datum Corporation (sample)" erfolgt und der Benutzer den Standardnamen, der für die neue untergeordnete Firma festgelegt wurde, nicht ändert.

  Created new account named 'Child account of A. Datum Corporation (sample)' with id:{1D4BFF87-E8C5-E411-80CF-00155DB58496}
  

openWebResource

Öffnet eine HTML-Webressource.

Hinweis

Diese Funktion wird für mobile Dynamics 365-Clients (Smartphones und Tablets) und den interaktiven Servicehub nicht unterstützt.

Xrm.Utility.openWebResource(webResourceName,webResourceData,width, height)

• Parameter

  Name	Typ	Erforderlich	Beschreibung
  webResourceName	Zeichenfolge	Ja	Der Name der zu öffnenden HTML-Webressource.
  webResourceData	Zeichenfolge	Nein	Daten, die in den Datenparameter übergeben werden.
  width	Anzahl	Nein	Die Breite des zu öffnenden Fensters in Pixeln.
  height	Anzahl	Nein	Die Höhe des zu öffnenden Fensters in Pixeln.

• Rückgabewert
  Fensterobjekt.

• Anmerkungen
  Eine HTML-Webressource kann die Parameterwerte annehmen, die in Parameter an HTML-Webressourcen übergeben beschrieben sind. Diese Funktion dient nur zum Übergeben des optionalen Datenparameters. Um Werte für weitere gültige Parameter zu übergeben, müssen Sie sie an den webResourceName-Parameter anfügen.

• Beispiele
  Öffnen einer HTML-Webressource namens "new_webResource.htm"

  Xrm.Utility.openWebResource("new_webResource.htm");
  

  Öffnen einer HTML-Webressource und ein einzelnes Element von Daten für den Datenparameter

  Xrm.Utility.openWebResource("new_webResource.htm","dataItemValue");
  

  Öffnen einer HTML-Webressource zum Übergeben mehrerer Werte über den Datenparameter

  var customParameters = encodeURIComponent("first=First Value&second=Second Value&third=Third Value");
  Xrm.Utility.openWebResource("new_webResource.htm",customParameters);
  

  Hinweis

  Diese Werte müssen aus dem Wert des Datenparameters in der HTML-webressource extrahiert werden. Weitere Informationen finden Sie unter Beispiel: Mehrere Werte über den Datenparameter an eine Webressource übergeben.

  Öffnen einer HTML-Webressource mit den von HTML-Webressourcen erwarteten Parametern

  Xrm.Utility.openWebResource("new_webResource.htm?typename=account&userlcid=1033");
  

  Weitere Informationen finden Sie unter Parameter an HTML-Webressourcen übergeben.

  Öffnen einer HTML-Webressource, die Höhe und Breite festlegt

  Xrm.Utility.openWebResource("new_webResource.htm", null, 300,300);
  

Siehe auch

Cclientseitige Programmierreferenz
Öffnen von Formularen, Ansichten, Dialogen und Berichten mit einer URL
Festlegen von Feldwerten mithilfe von Parametern, die an ein Formular übergeben werden
Ein Formular konfigurieren, um benutzerdefinierte Abfragezeichenfolgenparameter zu akzeptieren.
Kurzübersicht zum Formularskripting
Schreiben von Code für Microsoft Dynamics 365-Formulare
Verwenden des Xrm.Page-Objektmodells

Microsoft Dynamics 365

© 2017 Microsoft. Alle Rechte vorbehalten. Copyright